/**
 * Caliper Event Types
 *
 * Types for Caliper Analytics events and envelopes.
 */
import type { PaginationMeta } from './api';
import type { TimebackUser } from './timeback';
/**
 * Supported Caliper profiles.
 */
export type CaliperProfile = 'AnnotationProfile' | 'AssessmentProfile' | 'ToolUseProfile' | 'GeneralProfile' | 'FeedbackProfile' | 'MediaProfile' | 'SurveyProfile' | 'ResourceManagementProfile' | 'ForumProfile' | 'AssignableProfile' | 'GradingProfile' | 'ReadingProfile' | 'SessionProfile' | 'SearchProfile' | 'ToolLaunchProfile' | 'TimebackProfile';
/**
 * Base Caliper entity representation.
 *
 * Many Caliper fields can be provided either as an IRI string or as an
 * object-shaped entity, so the shared protocol model keeps this flexible.
 */
export type CaliperEntity = string | {
    [key: string]: unknown;
};
/**
 * One actor-object shape for sending events.
 *
 * This is a structured actor object with an `id`, a `type`, and an
 * `extensions` bag containing `email`. It is one valid actor-object shape,
 * not the only representation allowed by `CaliperEvent.actor`.
 */
export interface CaliperActor {
    /** Unique identifier (IRI format) */
    id: string;
    /** Entity type (e.g., 'Person', 'TimebackUser') */
    type: string;
    /** Extensions carried on this actor-object shape */
    extensions: {
        /** Actor email on this actor-object shape */
        email: string;
        /** Additional extension properties */
        [key: string]: unknown;
    };
}
/**
 * Caliper Event.
 *
 * Represents a learning activity event conforming to IMS Caliper v1.2.
 */
export interface CaliperEvent {
    /** JSON-LD context */
    '@context'?: string;
    /** Unique identifier (URN UUID format) */
    id: string;
    /** Event type */
    type: string;
    /** The agent who initiated the event (IRI string, CaliperActor, TimebackUser, or generic entity) */
    actor: CaliperEntity | CaliperActor | TimebackUser;
    /** The action or predicate */
    action: string;
    /** The object of the interaction */
    object: CaliperEntity;
    /** ISO 8601 datetime when event occurred */
    eventTime: string;
    /** Profile governing interpretation */
    profile: CaliperProfile;
    /** Application context */
    edApp?: CaliperEntity;
    /** Entity generated as result */
    generated?: CaliperEntity;
    /** Target segment within object */
    target?: CaliperEntity;
    /** Referring context */
    referrer?: CaliperEntity;
    /** Organization/group context */
    group?: CaliperEntity;
    /** User's membership/role */
    membership?: CaliperEntity;
    /** Current user session */
    session?: CaliperEntity;
    /** LTI session context */
    federatedSession?: CaliperEntity;
    /** Additional custom attributes */
    extensions?: Record<string, unknown>;
}
/**
 * Caliper Envelope.
 *
 * Container for transmitting Caliper events to the API.
 */
export interface CaliperEnvelope {
    /** Sensor identifier (IRI format) */
    sensor: string;
    /** ISO 8601 datetime when data was sent */
    sendTime: string;
    /** Caliper data version */
    dataVersion: 'http://purl.imsglobal.org/ctx/caliper/v1p2';
    /** Array of events or entities */
    data: CaliperEvent[];
    /** Allow additional properties for forward-compatibility and transformer passthrough. */
    [key: string]: unknown;
}
/**
 * Result of sending events.
 */
export interface SendEventsResult {
    /** Job ID for tracking async processing (undefined when the platform does not return one) */
    jobId: string | undefined;
}
/**
 * Individual event result from job completion.
 */
export interface EventResult {
    /** Allocated internal ID */
    allocatedId: string;
    /** External event ID */
    externalId: string;
}
/**
 * Job status response.
 */
export interface JobStatus {
    id: string;
    state: 'waiting' | 'active' | 'completed' | 'failed';
    returnValue?: {
        status: 'success' | 'error';
        results: EventResult[];
    };
    processedOn?: string | null;
}
/**
 * Stored Caliper event (from list/get).
 *
 * This represents an event as returned by the API, which differs from the
 * input CaliperEvent format. The API adds internal fields and transforms
 * the original event ID to `externalId`.
 *
 * @remarks
 * **API Docs Drift**: The official OpenAPI spec (caliper-api.yaml) does not
 * accurately document this response structure. This type was derived from
 * actual API responses. Key differences:
 * - `id` is a number (internal DB ID), not a string
 * - `externalId` contains the original URN UUID (use this for `get()` calls)
 * - Response is wrapped in `{ events: StoredEvent[] }` for list, `{ event: StoredEvent }` for get
 */
export interface StoredEvent {
    /** Internal numeric ID (allocated by the database) */
    id: number;
    /** Original event ID (URN UUID format) - use this for get() calls */
    externalId: string;
    /** Sensor that sent the event */
    sensor: string;
    /** Event type (e.g., 'ActivityEvent', 'Event') */
    type: string;
    /** Caliper profile (e.g., 'TimebackProfile') */
    profile?: string;
    /** The action or predicate */
    action: string;
    /** When the event occurred */
    eventTime: string;
    /** When the event was sent */
    sendTime: string;
    /** When the record was last updated */
    updated_at: string | null;
    /** When the record was created */
    created_at: string;
    /** When the record was deleted (soft delete) */
    deleted_at: string | null;
    /** The agent who initiated the event */
    actor: CaliperEntity;
    /** The object of the event */
    object: CaliperEntity;
    /** Generated entity (e.g., result, score) */
    generated?: CaliperEntity | null;
    /** Target entity */
    target?: CaliperEntity | null;
    /** Referrer entity */
    referrer?: CaliperEntity | null;
    /** EdApp entity */
    edApp?: CaliperEntity | null;
    /** Group/organization entity */
    group?: CaliperEntity | null;
    /** Membership entity */
    membership?: CaliperEntity | null;
    /** Session entity */
    session?: CaliperEntity | null;
    /** Federated session entity */
    federatedSession?: CaliperEntity | null;
    /** Extension data */
    extensions?: Record<string, unknown> | null;
    /** Client application ID */
    clientAppId?: string | null;
}
/**
 * Result from listing events.
 */
export interface ListEventsResult {
    events: StoredEvent[];
    pagination: PaginationMeta;
}
/**
 * AssessmentItemEvent (Question Seen / Question Answered).
 *
 * Represents when a student is presented with a question (Started)
 * or submits an answer (Completed).
 */
export interface AssessmentItemEvent extends CaliperEvent {
    type: 'AssessmentItemEvent';
    action: 'Started' | 'Completed';
    profile: 'AssessmentProfile';
}
/**
 * GradeEvent for question-level grading.
 *
 * Represents when a question response is graded, with a Score entity
 * containing `scoreType: "QUESTION_RESULT"` in the `generated` field.
 */
export interface QuestionGradeEvent extends CaliperEvent {
    type: 'GradeEvent';
    action: 'Graded';
    profile: 'GradingProfile';
}
//# sourceMappingURL=events.d.ts.map