@timeback/caliper 0.1.0

package/dist/types/events.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Caliper Event Types
+ *
+ * Types for Caliper Analytics events and envelopes.
+ */
+import type { CALIPER_DATA_VERSION } from '../constants';
+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 - can be a URI string or an object with properties.
+ */
+export type CaliperEntity = string | {
+    [key: string]: unknown;
+};
+/**
+ * Caliper actor entity (for sending events).
+ *
+ * Timeback API requires actors to have extensions.email.
+ */
+export interface CaliperActor {
+    /** Unique identifier (IRI format) */
+    id: string;
+    /** Entity type (e.g., 'Person', 'TimebackUser') */
+    type: string;
+    /** Extensions - email is required by Timeback API */
+    extensions: {
+        /** Actor's email address (required by Timeback) */
+        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 (string URL, CaliperActor, or TimebackUser) */
+    actor: string | 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: typeof CALIPER_DATA_VERSION;
+    /** Array of events or entities */
+    data: CaliperEvent[];
+}
+/**
+ * Result of sending events.
+ */
+export interface SendEventsResult {
+    /** Job ID for tracking async processing */
+    jobId: string;
+}
+/**
+ * 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;
+}
+/**
+ * Parameters for listing events.
+ */
+export interface ListEventsParams {
+    limit?: number;
+    offset?: number;
+    sensor?: string;
+    startDate?: string;
+    endDate?: string;
+    actorId?: string;
+    actorEmail?: string;
+}
+/**
+ * Result from listing events.
+ */
+export interface ListEventsResult {
+    events: StoredEvent[];
+    pagination: PaginationMeta;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Caliper Types
+ *
+ * Type definitions for the Caliper client.
+ */
+export * from './api';
+export * from './client';
+export * from './events';
+export * from './timeback';
+export { CALIPER_DATA_VERSION } from '../constants';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,OAAO,CAAA;AACrB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA"}

package/dist/types/timeback.d.ts

@@ -0,0 +1,395 @@
+/**
+ * Timeback Profile Types
+ *
+ * First-class types for the Timeback Caliper profile, including
+ * ActivityCompletedEvent and TimeSpentEvent.
+ */
+import type { CALIPER_DATA_VERSION } from '../constants';
+/**
+ * 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;
+}
+/**
+ * Subject areas supported by the Timeback platform.
+ */
+export type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None' | 'Other';
+/**
+ * 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',
+ *   items: [
+ *     { type: 'totalQuestions', value: 10 },
+ *     { type: 'correctQuestions', value: 8 },
+ *     { type: 'xpEarned', value: 150 },
+ *   ],
+ * }
+ * ```
+ */
+export interface TimebackActivityMetricsCollection {
+    /** Collection identifier (IRI format) */
+    id: string;
+    /** Must be 'TimebackActivityMetricsCollection' */
+    type: 'TimebackActivityMetricsCollection';
+    /** Array of metrics */
+    items: TimebackActivityMetric[];
+    /** Additional custom attributes */
+    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': typeof CALIPER_DATA_VERSION;
+    /** 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;
+/**
+ * Input for creating an ActivityCompletedEvent.
+ *
+ * Omits fields that are auto-generated (id, eventTime, @context, profile).
+ */
+export interface ActivityCompletedInput {
+    /** The user who completed the activity */
+    actor: TimebackUser;
+    /** The activity context */
+    object: TimebackActivityContext;
+    /** Activity metrics */
+    metrics: TimebackActivityMetric[];
+    /** Optional: Event time (defaults to now) */
+    eventTime?: string;
+    /** Optional: Metrics collection ID (auto-generated if not provided) */
+    metricsId?: string;
+    /** Optional: Event ID (auto-generated if not provided) */
+    id?: string;
+    /** Optional: Additional custom attributes */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Input for creating a TimeSpentEvent.
+ *
+ * Omits fields that are auto-generated (id, eventTime, @context, profile).
+ */
+export interface TimeSpentInput {
+    /** The user who spent time */
+    actor: TimebackUser;
+    /** The activity context */
+    object: TimebackActivityContext;
+    /** Time spent metrics */
+    metrics: TimeSpentMetric[];
+    /** Optional: Event time (defaults to now) */
+    eventTime?: string;
+    /** Optional: Metrics collection ID (auto-generated if not provided) */
+    metricsId?: string;
+    /** Optional: Event ID (auto-generated if not provided) */
+    id?: string;
+    /** Optional: Additional custom attributes */
+    extensions?: Record<string, unknown>;
+}
+export {};
+//# sourceMappingURL=timeback.d.ts.map

package/dist/types/timeback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeback.d.ts","sourceRoot":"","sources":["../../src/types/timeback.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Caliper Types (subpath export)
+ *
+ * Re-exports all types for the ./types subpath.
+ */
+export * from './types/index';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAA"}