@timeback/caliper 0.1.5 → 0.1.6

package/dist/public-types.d.ts

@@ -0,0 +1,879 @@
+/**
+ * Timeback Shared Primitives
+ *
+ * Core types used across multiple Timeback protocols.
+ *
+ * Organization:
+ * - Shared types (this file): Used by multiple protocols (Caliper, OneRoster, etc.)
+ * - Protocol-specific types: Live in their respective protocols/X/primitives.ts files
+ *
+ * What belongs here:
+ * - TimebackSubject - Used in OneRoster courses AND Caliper events
+ * - TimebackGrade - Used across OneRoster, Caliper, and QTI
+ * - IMSErrorResponse - IMS Global standard used by multiple 1EdTech protocols
+ *
+ * What doesn't belong here:
+ * - OneRoster-specific: protocols/oneroster/primitives.ts
+ * - QTI-specific: protocols/qti/primitives.ts
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TIMEBACK SHARED TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Valid Timeback subject values.
+ * Used in OneRoster courses and Caliper events.
+ */
+type TimebackSubject =
+	| 'Reading'
+	| 'Language'
+	| 'Vocabulary'
+	| 'Social Studies'
+	| 'Writing'
+	| 'Science'
+	| 'FastMath'
+	| 'Math'
+	| 'None'
+	| 'Other'
+
+/**
+ * Timeback Profile Types
+ *
+ * First-class types for the Timeback Caliper profile, including
+ * ActivityCompletedEvent and TimeSpentEvent.
+ */
+
+
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIMEBACK ACTIVITY CONTEXT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIMEBACK USER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * User role in the Timeback platform.
+ */
+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',
+ * }
+ * ```
+ */
+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.
+ */
+interface TimebackApp {
+	/** Application identifier (IRI format) */
+	id?: string
+	/** Application name */
+	name: string
+	/** Additional custom attributes */
+	extensions?: Record<string, unknown>
+}
+
+/**
+ * Course reference within activity context.
+ */
+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.
+ */
+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' },
+ * }
+ * ```
+ */
+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
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ACTIVITY METRICS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Types of activity metrics.
+ */
+type ActivityMetricType =
+	| 'xpEarned'
+	| 'totalQuestions'
+	| 'correctQuestions'
+	| 'masteredUnits'
+
+/**
+ * Individual activity metric.
+ *
+ * @example
+ * ```typescript
+ * const metric: TimebackActivityMetric = {
+ *   type: 'correctQuestions',
+ *   value: 8,
+ * }
+ * ```
+ */
+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 },
+ * }
+ * ```
+ */
+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
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIME SPENT METRICS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Types of time spent metrics.
+ */
+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',
+ * }
+ * ```
+ */
+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 },
+ *   ],
+ * }
+ * ```
+ */
+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
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIMEBACK EVENTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * 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 },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
+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 },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
+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.
+ */
+type TimebackEvent = ActivityCompletedEvent | TimeSpentEvent
+
+/**
+ * Caliper Event Types
+ *
+ * Types for Caliper Analytics events and envelopes.
+ */
+
+
+
+/**
+ * Supported Caliper profiles.
+ */
+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.
+ */
+type CaliperEntity = string | { [key: string]: unknown }
+
+/**
+ * Caliper actor entity (for sending events).
+ *
+ * Timeback API requires actors to have extensions.email.
+ */
+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.
+ */
+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.
+ */
+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[]
+}
+
+/**
+ * Result of sending events.
+ */
+interface SendEventsResult {
+	/** Job ID for tracking async processing */
+	jobId: string
+}
+
+/**
+ * Individual event result from job completion.
+ */
+interface EventResult {
+	/** Allocated internal ID */
+	allocatedId: string
+	/** External event ID */
+	externalId: string
+}
+
+/**
+ * Job status response.
+ */
+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
+ */
+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.
+ */
+interface ListEventsResult {
+	events: StoredEvent[]
+	pagination: PaginationMeta
+}
+
+/**
+ * API Response Types
+ *
+ * Types for Caliper API responses.
+ *
+ * @remarks
+ * **IMPORTANT - API Docs Drift**: The official API documentation (caliper/response.yaml
+ * and caliper-api.yaml) does NOT accurately reflect actual API responses. The types
+ * in this file were derived from testing actual API responses. See individual type
+ * comments for specific discrepancies.
+ */
+
+
+
+/**
+ * Generic API response wrapper.
+ */
+interface ApiResponse<T> {
+	status: 'success' | 'error'
+	message?: string
+	data?: T
+}
+
+/**
+ * Pagination metadata returned by list endpoints.
+ */
+interface PaginationMeta {
+	/** Total number of items across all pages */
+	total: number
+	/** Total number of pages */
+	totalPages: number
+	/** Current page number (1-indexed) */
+	currentPage: number
+	/** Number of items per page */
+	limit: number
+}
+
+/**
+ * Response from GET /caliper/events (list events).
+ *
+ * @remarks
+ * **API Docs Drift**: Official docs (caliper/response.yaml) incorrectly show
+ * `{ status, message, errors? }`. Actual response is `{ events, pagination }`.
+ */
+interface ListEventsResponse {
+	/** Array of stored events */
+	events: StoredEvent[]
+	/** Pagination metadata */
+	pagination: PaginationMeta
+}
+
+/**
+ * Response from GET /caliper/events/:externalId (get single event).
+ *
+ * @remarks
+ * **API Docs Drift**: Official docs (caliper/response.yaml) incorrectly show
+ * `{ status, message, errors? }`. Actual response is `{ status, event }`.
+ */
+interface GetEventResponse {
+	/** Status indicator */
+	status: 'success' | 'error'
+	/** The requested event */
+	event: StoredEvent
+}
+
+/**
+ * Response from POST /caliper/event (send events).
+ *
+ * @remarks
+ * **API Docs Drift**: Official docs (caliper/response.yaml) incorrectly show
+ * `{ status, message, errors? }`. Actual response is `{ jobId }`.
+ * Use the jobId with `jobs.getStatus()` to track processing.
+ */
+interface SendEventsResponse {
+	/** Job ID for tracking async processing */
+	jobId: string
+}
+
+/**
+ * Job status response payload (GET /jobs/{jobId}/status).
+ *
+ * @remarks
+ * This endpoint is correctly documented in caliper/response.yaml.
+ */
+interface JobStatusResponse {
+	job: JobStatus
+}
+
+/**
+ * Options for waitForCompletion polling.
+ */
+interface WaitForCompletionOptions {
+	/** Maximum time to wait in milliseconds (default: 30000) */
+	timeoutMs?: number
+	/** Interval between status checks in milliseconds (default: 1000) */
+	pollIntervalMs?: number
+}
+
+/**
+ * Validation result from the validate endpoint.
+ */
+interface ValidationResult {
+	/** Whether validation succeeded */
+	status: 'success' | 'error'
+	/** Human-readable message */
+	message?: string
+	/** Validation errors (if any) */
+	errors?: unknown
+}
+
+/**
+ * Caliper Constants
+ *
+ * Configuration constants for the Caliper Analytics client.
+ */
+
+/**
+ * Caliper JSON-LD context version.
+ */
+declare const CALIPER_DATA_VERSION = "http://purl.imsglobal.org/ctx/caliper/v1p2";
+
+type input<T> = T extends {
+    _zod: {
+        input: any;
+    };
+} ? T["_zod"]["input"] : unknown;
+
+/**
+ * Caliper Schemas
+ *
+ * Zod schemas for the IMS Caliper Analytics standard with Timeback Profile.
+ */
+
+
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// BUILDER INPUTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+declare const ActivityCompletedInput = z
+	.object({
+		actor: TimebackUser,
+		object: TimebackActivityContext,
+		metrics: z.array(TimebackActivityMetric).min(1, 'metrics must contain at least one metric'),
+		eventTime: IsoDateTimeString.optional(),
+		metricsId: z.string().optional(),
+		id: z.string().optional(),
+		/** Event-level extensions */
+		extensions: z.record(z.string(), z.unknown()).optional(),
+		/**
+		 * Application context (IRI or entity).
+		 *
+		 * Maps to `edApp` in the Caliper event. Identifies the educational
+		 * application where the event occurred.
+		 */
+		edApp: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+		/**
+		 * Session context (IRI or entity).
+		 *
+		 * Maps to `session` in the Caliper event. Used for event-to-session
+		 * correlation (e.g., linking heartbeats with completions via runId).
+		 */
+		session: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+		/**
+		 * Attempt number (1-based).
+		 *
+		 * Maps to `generated.attempt` in the Caliper event.
+		 */
+		attempt: z.number().int().min(1).optional(),
+		/**
+		 * Extensions for the generated metrics collection.
+		 *
+		 * Maps to `generated.extensions` in the Caliper event.
+		 * Use `generatedExtensions.pctCompleteApp` (0–100) for app-reported course progress.
+		 */
+		generatedExtensions: z
+			.object({
+				/**
+				 * App-reported course progress (per enrollment), as a percentage from 0–100.
+				 *
+				 * This is emitted to Caliper as `generated.extensions.pctCompleteApp`.
+				 *
+				 * @remarks
+				 * This value is not clamped here (Caliper client keeps the raw shape).
+				 */
+				pctCompleteApp: z.number().optional(),
+			})
+			.loose()
+			.optional(),
+	})
+	.strict()
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TYPE EXPORTS (REQUEST INPUTS)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+type ActivityCompletedInput = input<typeof ActivityCompletedInput>
+
+declare const TimeSpentInput = z
+	.object({
+		actor: TimebackUser,
+		object: TimebackActivityContext,
+		metrics: z.array(TimebackTimeMetric).min(1, 'metrics must contain at least one metric'),
+		eventTime: IsoDateTimeString.optional(),
+		metricsId: z.string().optional(),
+		id: z.string().optional(),
+		extensions: z.record(z.string(), z.unknown()).optional(),
+		edApp: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+		session: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+	})
+	.strict()
+type TimeSpentInput = input<typeof TimeSpentInput>
+
+declare const CaliperListEventsParams = z
+	.object({
+		limit: z.number().int().positive().optional(),
+		offset: z.number().int().min(0).optional(),
+		sensor: z.string().min(1).optional(),
+		startDate: IsoDateTimeString.optional(),
+		endDate: IsoDateTimeString.optional(),
+		actorId: z.string().min(1).optional(),
+		actorEmail: z.email().optional(),
+	})
+	.strict()
+type CaliperListEventsParams = input<typeof CaliperListEventsParams>
+
+export { ActivityCompletedInput, CALIPER_DATA_VERSION, CaliperListEventsParams as ListEventsParams, TimeSpentInput };
+export type { ActivityCompletedEvent, ActivityMetricType, ApiResponse, CaliperActor, CaliperEntity, CaliperEnvelope, CaliperEvent, CaliperProfile, EventResult, GetEventResponse, JobStatus, JobStatusResponse, ListEventsResponse, ListEventsResult, PaginationMeta, SendEventsResponse, SendEventsResult, StoredEvent, TimeSpentEvent, TimeSpentMetric, TimeSpentMetricType, TimebackActivity, TimebackActivityContext, TimebackActivityMetric, TimebackActivityMetricsCollection, TimebackApp, TimebackCourse, TimebackEvent, TimebackEventBase, TimebackSubject, TimebackTimeSpentMetricsCollection, TimebackUser, TimebackUserRole, ValidationResult, WaitForCompletionOptions };