/**
 * Timeback Profile Types
 *
 * First-class types for the Timeback Caliper profile, including
 * ActivityCompletedEvent and TimeSpentEvent.
 */
import type { TimebackSubject } from '../../primitives';
/**
 * User role in the Timeback platform.
 */
export type TimebackUserRole = 'student' | 'teacher' | 'admin' | 'guide';
/**
 * Timeback user entity.
 *
 * Represents a user in the Timeback platform. The `id` should ideally be
 * the OneRoster URL for the user when available.
 *
 * @example
 * ```typescript
 * const user: TimebackUser = {
 *   id: 'https://api.alpha-1edtech.ai/ims/oneroster/rostering/v1p2/users/123',
 *   type: 'TimebackUser',
 *   email: 'student@example.edu',
 *   name: 'Jane Doe',
 *   role: 'student',
 * }
 * ```
 */
export interface TimebackUser {
    /** User identifier (IRI format, preferably OneRoster URL) */
    id: string;
    /** Must be 'TimebackUser' */
    type: 'TimebackUser';
    /** User email address */
    email: string;
    /** User display name */
    name?: string;
    /** User role */
    role?: TimebackUserRole;
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
    /** Index signature for Caliper compatibility */
    [key: string]: unknown;
}
/**
 * Application reference within activity context.
 */
export interface TimebackApp {
    /** Application identifier (IRI format) */
    id?: string;
    /** Application name */
    name: string;
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
}
/**
 * Course reference within activity context.
 */
export interface TimebackCourse {
    /** Course identifier (IRI format, preferably OneRoster URL) */
    id?: string;
    /** Course name */
    name?: string;
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
}
/**
 * Activity reference within activity context.
 */
export interface TimebackActivity {
    /** Activity identifier (IRI format) */
    id?: string;
    /** Activity name */
    name: string;
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
}
/**
 * Timeback activity context.
 *
 * Represents the context where an event was recorded, including
 * subject, application, course, and activity information.
 *
 * @example
 * ```typescript
 * const context: TimebackActivityContext = {
 *   id: 'https://myapp.example.com/activities/123',
 *   type: 'TimebackActivityContext',
 *   subject: 'Math',
 *   app: { name: 'My Learning App' },
 *   course: { name: 'Algebra 101' },
 *   activity: { name: 'Chapter 1 Quiz' },
 * }
 * ```
 */
export interface TimebackActivityContext {
    /** Context identifier (IRI format) */
    id: string;
    /** Must be 'TimebackActivityContext' */
    type: 'TimebackActivityContext';
    /** Subject area */
    subject: TimebackSubject;
    /** Application where event was recorded */
    app: TimebackApp;
    /** Course where event was recorded */
    course: TimebackCourse;
    /** Activity where event was recorded */
    activity?: TimebackActivity;
    /** Whether to process this event */
    process?: boolean;
    /** Index signature for Caliper compatibility */
    [key: string]: unknown;
}
/**
 * Types of activity metrics.
 */
export type ActivityMetricType = 'xpEarned' | 'totalQuestions' | 'correctQuestions' | 'masteredUnits';
/**
 * Individual activity metric.
 *
 * @example
 * ```typescript
 * const metric: TimebackActivityMetric = {
 *   type: 'correctQuestions',
 *   value: 8,
 * }
 * ```
 */
export interface TimebackActivityMetric {
    /** Metric type */
    type: ActivityMetricType;
    /** Metric value */
    value: number;
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
}
/**
 * Collection of activity metrics.
 *
 * @example
 * ```typescript
 * const metrics: TimebackActivityMetricsCollection = {
 *   id: 'https://myapp.example.com/metrics/123',
 *   type: 'TimebackActivityMetricsCollection',
 *   attempt: 1,
 *   items: [
 *     { type: 'totalQuestions', value: 10 },
 *     { type: 'correctQuestions', value: 8 },
 *     { type: 'xpEarned', value: 150 },
 *   ],
 *   extensions: { pctCompleteApp: 67 },
 * }
 * ```
 */
export interface TimebackActivityMetricsCollection {
    /** Collection identifier (IRI format) */
    id: string;
    /** Must be 'TimebackActivityMetricsCollection' */
    type: 'TimebackActivityMetricsCollection';
    /** Attempt number (1-based) */
    attempt?: number;
    /** Array of metrics */
    items: TimebackActivityMetric[];
    /**
     * Additional custom attributes.
     *
     * Common fields:
     * - `pctCompleteApp`: App-defined course completion percentage (0–100)
     */
    extensions?: Record<string, unknown>;
    /** Index signature for Caliper compatibility */
    [key: string]: unknown;
}
/**
 * Types of time spent metrics.
 */
export type TimeSpentMetricType = 'active' | 'inactive' | 'waste' | 'unknown' | 'anti-pattern';
/**
 * Individual time spent metric.
 *
 * @example
 * ```typescript
 * const metric: TimeSpentMetric = {
 *   type: 'active',
 *   value: 1800, // 30 minutes in seconds
 *   startDate: '2024-01-15T10:00:00Z',
 *   endDate: '2024-01-15T10:30:00Z',
 * }
 * ```
 */
export interface TimeSpentMetric {
    /** Metric type */
    type: TimeSpentMetricType;
    /** Time spent in seconds (max 86400 = 24 hours) */
    value: number;
    /** Sub-type for additional categorization */
    subType?: string;
    /** Start of the time period */
    startDate?: string;
    /** End of the time period */
    endDate?: string;
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
}
/**
 * Collection of time spent metrics.
 *
 * @example
 * ```typescript
 * const metrics: TimebackTimeSpentMetricsCollection = {
 *   id: 'https://myapp.example.com/time-metrics/123',
 *   type: 'TimebackTimeSpentMetricsCollection',
 *   items: [
 *     { type: 'active', value: 1800 },
 *     { type: 'inactive', value: 300 },
 *   ],
 * }
 * ```
 */
export interface TimebackTimeSpentMetricsCollection {
    /** Collection identifier (IRI format) */
    id: string;
    /** Must be 'TimebackTimeSpentMetricsCollection' */
    type: 'TimebackTimeSpentMetricsCollection';
    /** Array of time spent metrics */
    items: TimeSpentMetric[];
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
    /** Index signature for Caliper compatibility */
    [key: string]: unknown;
}
/**
 * Base properties common to all Timeback events.
 */
interface TimebackEventBase {
    /** JSON-LD context */
    '@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2';
    /** Unique identifier (URN UUID format) */
    id: string;
    /** The user who performed the action */
    actor: TimebackUser;
    /** The activity context */
    object: TimebackActivityContext;
    /** ISO 8601 datetime when event occurred */
    eventTime: string;
    /** Must be 'TimebackProfile' */
    profile: 'TimebackProfile';
    /** Application context (IRI or entity) */
    edApp?: string | Record<string, unknown>;
    /** Target segment within object */
    target?: string | Record<string, unknown>;
    /** Referring context */
    referrer?: string | Record<string, unknown>;
    /** Organization/group context */
    group?: string | Record<string, unknown>;
    /** User's membership/role */
    membership?: string | Record<string, unknown>;
    /** Current user session */
    session?: string | Record<string, unknown>;
    /** LTI session context */
    federatedSession?: string | Record<string, unknown>;
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
}
/**
 * Timeback Activity Completed Event.
 *
 * Records when a student completes an activity, along with performance metrics.
 *
 * @example
 * ```typescript
 * const event: ActivityCompletedEvent = {
 *   '@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2',
 *   id: 'urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594',
 *   type: 'ActivityEvent',
 *   action: 'Completed',
 *   actor: {
 *     id: 'https://api.example.com/users/123',
 *     type: 'TimebackUser',
 *     email: 'student@example.edu',
 *   },
 *   object: {
 *     id: 'https://myapp.example.com/activities/456',
 *     type: 'TimebackActivityContext',
 *     subject: 'Math',
 *     app: { name: 'My Learning App' },
 *   },
 *   eventTime: '2024-01-15T14:30:00Z',
 *   profile: 'TimebackProfile',
 *   generated: {
 *     id: 'https://myapp.example.com/metrics/789',
 *     type: 'TimebackActivityMetricsCollection',
 *     items: [
 *       { type: 'totalQuestions', value: 10 },
 *       { type: 'correctQuestions', value: 8 },
 *     ],
 *   },
 * }
 * ```
 */
export interface ActivityCompletedEvent extends TimebackEventBase {
    /** Must be 'ActivityEvent' */
    type: 'ActivityEvent';
    /** Must be 'Completed' */
    action: 'Completed';
    /** Activity metrics generated from this completion */
    generated: TimebackActivityMetricsCollection;
}
/**
 * Timeback Time Spent Event.
 *
 * Records time spent on an activity, categorized by engagement type.
 *
 * @example
 * ```typescript
 * const event: TimeSpentEvent = {
 *   '@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2',
 *   id: 'urn:uuid:d62681f5-g9fe-5d29-cc4b-efg62c3dd695',
 *   type: 'TimeSpentEvent',
 *   action: 'SpentTime',
 *   actor: {
 *     id: 'https://api.example.com/users/123',
 *     type: 'TimebackUser',
 *     email: 'student@example.edu',
 *   },
 *   object: {
 *     id: 'https://myapp.example.com/activities/456',
 *     type: 'TimebackActivityContext',
 *     subject: 'Reading',
 *     app: { name: 'My Learning App' },
 *   },
 *   eventTime: '2024-01-15T15:00:00Z',
 *   profile: 'TimebackProfile',
 *   generated: {
 *     id: 'https://myapp.example.com/time-metrics/789',
 *     type: 'TimebackTimeSpentMetricsCollection',
 *     items: [
 *       { type: 'active', value: 1800 },
 *       { type: 'inactive', value: 300 },
 *     ],
 *   },
 * }
 * ```
 */
export interface TimeSpentEvent extends TimebackEventBase {
    /** Must be 'TimeSpentEvent' */
    type: 'TimeSpentEvent';
    /** Must be 'SpentTime' */
    action: 'SpentTime';
    /** Time spent metrics generated from this session */
    generated: TimebackTimeSpentMetricsCollection;
}
/**
 * Union of all Timeback event types.
 */
export type TimebackEvent = ActivityCompletedEvent | TimeSpentEvent;
export {};
//# sourceMappingURL=timeback.d.ts.map