@timeback/caliper 0.1.5 → 0.1.6

package/dist/index.d.ts

@@ -1,80 +1,1409 @@
+import * as _timeback_internal_client_infra from '@timeback/internal-client-infra';
+import { ClientConfig, TransportOnlyConfig, CaliperPaths, RequestOptions, PaginatedResponse, ProviderClientConfig, BaseTransportConfig, Paginator as Paginator$1, ListParams, ProviderRegistry, TimebackProvider, AuthCheckResult, BaseTransport } from '@timeback/internal-client-infra';
+export { AuthCheckResult, EnvAuth, Environment, ExplicitAuth } from '@timeback/internal-client-infra';
+
 /**
- * Caliper Analytics client SDK for Timeback.
+ * Timeback Shared Primitives
  *
- * Caliper Analytics client SDK for Timeback.
+ * 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
- * // Timeback Profile - Activity Completed (recommended)
- * import { CaliperClient } from '@timeback/caliper'
+ * 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.
+ */
+
+
+
+/**
+ * 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
+}
+
+/**
+ * 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
+}
+
+/**
+ * Client Configuration Types
+ *
+ * Configuration types for the Caliper client.
+ */
+
+/**
+ * Transport interface for Caliper client.
+ *
+ * Extends base transport requirements with Caliper-specific paths.
+ * Required when using transport mode with CaliperClient.
+ */
+interface CaliperTransportLike {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** API path profiles for Caliper operations */
+    paths: CaliperPaths;
+    /** Make an authenticated request */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Make a paginated request using body-based pagination */
+    requestPaginated<T>(path: string, options?: RequestOptions): Promise<PaginatedResponse<T>>;
+}
+/**
+ * Caliper client configuration options.
+ *
+ * Supports four modes:
+ * - **Provider mode**: `{ provider: TimebackProvider }` — pre-built provider with token sharing
+ * - **Environment mode**: `{ platform?, env, auth }` — Timeback hosted APIs
+ * - **Explicit mode**: `{ baseUrl, auth: { authUrl } }` — custom API URLs
+ * - **Transport mode**: `{ transport: CaliperTransportLike }` — custom transport with paths
+ *
+ * The `platform` field (in env mode) selects which Timeback implementation to use:
+ * - `'BEYOND_AI'` (default): BeyondAI's Timeback platform
+ * - `'LEARNWITH_AI'`: Samy's LearnWith.AI platform
+ */
+type CaliperClientConfig = ClientConfig | TransportOnlyConfig<CaliperTransportLike> | ProviderClientConfig;
+/**
+ * Configuration for Caliper transport.
+ */
+type CaliperTransportConfig = BaseTransportConfig & {
+    /** API path profiles for Caliper operations */
+    paths: CaliperPaths;
+};
+/**
+ * Instance type of CaliperClient.
+ */
+type CaliperClientInstance = InstanceType<typeof CaliperClient>;
+
+/**
+ * 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>
+
+/**
+ * Pagination Utilities
  *
+ * Re-exports the common Paginator with Caliper-specific configuration.
+ */
+
+/**
+ * Caliper-specific Paginator that uses the Caliper transport.
+ *
+ * Uses body-based pagination with the events response format.
+ *
+ * @typeParam T - The type of items being paginated
+ */
+declare class Paginator<T> extends Paginator$1<T> {
+    /**
+     * Create a new Caliper Paginator.
+     *
+     * @param transport - Caliper transport instance
+     * @param path - API endpoint path
+     * @param params - List parameters including optional max
+     */
+    constructor(transport: CaliperTransportLike, path: string, params?: ListParams);
+}
+
+/**
+ * Events Resource
+ *
+ * Manage Caliper events - send, list, and retrieve.
+ */
+
+/**
+ * Caliper Events resource.
+ *
+ * Provides methods to send, list, and retrieve Caliper events.
+ */
+declare class EventsResource {
+    private readonly transport;
+    constructor(transport: CaliperTransportLike);
+    /**
+     * Send Caliper events.
+     *
+     * Wraps events in an envelope and sends to the API.
+     * Events are validated against the IMS Caliper specification
+     * and queued for async processing.
+     *
+     * @param sensor - Sensor identifier (IRI format)
+     * @param events - Array of Caliper events
+     * @returns Job ID for tracking processing status
+     *
+     * @remarks
+     * **API Response Drift**: The official API docs (caliper/response.yaml) document
+     * the response as `{ status, message, errors? }`, but the actual API returns
+     * `{ jobId }`. This client correctly handles the actual response.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.events.send(
+     *   'https://example.edu/sensors/1',
+     *   [event1, event2]
+     * )
+     * ```
+     */
+    send(sensor: string, events: CaliperEvent[]): Promise<SendEventsResult>;
+    /**
+     * Send a raw Caliper envelope.
+     *
+     * Use this when you need full control over the envelope structure.
+     * For most cases, prefer `send()` which builds the envelope for you.
+     *
+     * @param envelope - Caliper envelope containing events
+     * @returns Job ID for tracking processing status
+     *
+     * @remarks
+     * **API Response Drift**: See `send()` for details on response format drift.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.events.sendEnvelope({
+     *   sensor: 'https://example.edu/sensors/1',
+     *   sendTime: new Date().toISOString(),
+     *   dataVersion: 'http://purl.imsglobal.org/ctx/caliper/v1p2',
+     *   data: [event1, event2],
+     * })
+     * ```
+     */
+    sendEnvelope(envelope: CaliperEnvelope): Promise<SendEventsResult>;
+    /**
+     * Validate Caliper events without storing them.
+     *
+     * Use this to check if events conform to the IMS Caliper specification
+     * before sending them for processing.
+     *
+     * @param envelope - Caliper envelope containing events to validate
+     * @returns Validation result with status and any errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.events.validate({
+     *   sensor: 'https://example.edu/sensors/1',
+     *   sendTime: new Date().toISOString(),
+     *   dataVersion: 'http://purl.imsglobal.org/ctx/caliper/v1p2',
+     *   data: [event1, event2],
+     * })
+     *
+     * if (result.status === 'success') {
+     *   console.log('Events are valid!')
+     * } else {
+     *   console.log('Validation errors:', result.errors)
+     * }
+     * ```
+     */
+    validate(envelope: CaliperEnvelope): Promise<ValidationResult>;
+    /**
+     * List Caliper events with optional filtering.
+     *
+     * @param params - Filter parameters
+     * @returns Events array and pagination metadata
+     *
+     * @remarks
+     * **API Response Drift**: The official API docs (caliper/response.yaml) document
+     * the response as `{ status, message, errors? }`, but the actual API returns
+     * `{ events: StoredEvent[], pagination: { total, totalPages, currentPage, limit } }`.
+     * This client correctly handles the actual response.
+     *
+     * @example
+     * ```typescript
+     * const { events } = await client.events.list({
+     *   limit: 50,
+     *   actorEmail: 'student@example.edu',
+     *   startDate: '2024-01-01',
+     * })
+     *
+     * // Access pagination metadata
+     * const { events, pagination } = await client.events.list({ limit: 10 })
+     * console.log(`Total: ${pagination.total}`)
+     * ```
+     */
+    list(params?: CaliperListEventsParams): Promise<ListEventsResult>;
+    /**
+     * Stream Caliper events with automatic pagination.
+     *
+     * Returns a Paginator that lazily fetches pages as you iterate.
+     * Use this for large datasets or when you need all matching events.
+     *
+     * @param params - Filter parameters (same as list())
+     * @returns Paginator for async iteration
+     *
+     * @example
+     * ```typescript
+     * // Iterate over all events
+     * for await (const event of client.events.stream({ startDate: '2024-01-01' })) {
+     *   console.log(event.id)
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Collect all events into an array
+     * const allEvents = await client.events
+     *   .stream({ startDate: '2024-01-01' })
+     *   .toArray()
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Limit total events fetched
+     * const events = await client.events
+     *   .stream({ startDate: '2024-01-01', max: 1000 })
+     *   .toArray()
+     * ```
+     */
+    stream(params?: CaliperListEventsParams & {
+        max?: number;
+    }): Paginator<StoredEvent>;
+    /**
+     * Get a specific event by its external ID.
+     *
+     * @param externalId - The event's external ID (URN UUID format, e.g., 'urn:uuid:...')
+     * @returns The stored event
+     *
+     * @remarks
+     * **API Response Drift**: The official API docs (caliper/response.yaml) document
+     * the response as `{ status, message, errors? }`, but the actual API returns
+     * `{ status, event: StoredEvent }`. This client correctly handles the actual response.
+     *
+     * **Important**: Use `externalId` (URN UUID), not the internal numeric `id`.
+     * The `StoredEvent` returned from `list()` contains both - use `event.externalId`.
+     *
+     * @example
+     * ```typescript
+     * const event = await client.events.get('urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594')
+     * ```
+     */
+    get(externalId: string): Promise<StoredEvent>;
+    /**
+     * Send an activity event (Timeback Profile).
+     *
+     * Records student activity completion with performance metrics.
+     * This is a first-class method for the Timeback platform.
+     *
+     * @param sensor - Sensor identifier (IRI format)
+     * @param input - Activity completion data
+     * @returns Job ID for tracking processing status
+     *
+     * @example
+     * ```typescript
+     * const result = await client.events.sendActivity(
+     *   'https://myapp.example.com/sensors/main',
+     *   {
+     *     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' },
+     *     },
+     *     metrics: [
+     *       { type: 'totalQuestions', value: 10 },
+     *       { type: 'correctQuestions', value: 8 },
+     *       { type: 'xpEarned', value: 150 },
+     *     ],
+     *   },
+     * )
+     * ```
+     */
+    sendActivity(sensor: string, input: ActivityCompletedInput): Promise<SendEventsResult>;
+    /**
+     * Send a time spent event (Timeback Profile).
+     *
+     * Records time spent on an activity, categorized by engagement type.
+     * This is a first-class method for the Timeback platform.
+     *
+     * @param sensor - Sensor identifier (IRI format)
+     * @param input - Time spent data
+     * @returns Job ID for tracking processing status
+     *
+     * @example
+     * ```typescript
+     * const result = await client.events.sendTimeSpent(
+     *   'https://myapp.example.com/sensors/main',
+     *   {
+     *     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' },
+     *     },
+     *     metrics: [
+     *       { type: 'active', value: 1800 },  // 30 minutes
+     *       { type: 'inactive', value: 300 }, // 5 minutes
+     *     ],
+     *   },
+     * )
+     * ```
+     */
+    sendTimeSpent(sensor: string, input: TimeSpentInput): Promise<SendEventsResult>;
+}
+
+/**
+ * Jobs Resource
+ *
+ * Track status of async event processing jobs.
+ */
+
+/**
+ * Jobs resource for tracking async processing.
+ *
+ * When events are submitted, they are queued for async processing.
+ * Use this resource to check job status and retrieve results.
+ */
+declare class JobsResource {
+    private readonly transport;
+    constructor(transport: CaliperTransportLike);
+    /**
+     * Get the status of a processing job.
+     *
+     * @param jobId - The job ID returned from events.send()
+     * @returns Job status including state and results
+     *
+     * @example
+     * ```typescript
+     * const status = await client.jobs.getStatus(jobId)
+     *
+     * if (status.state === 'completed') {
+     *   console.log('Events processed:', status.returnValue?.results)
+     * }
+     * ```
+     */
+    getStatus(jobId: string): Promise<JobStatus>;
+    /**
+     * Wait for a job to complete with polling.
+     *
+     * @param jobId - The job ID to wait for
+     * @param options - Polling options
+     * @returns Final job status
+     * @throws {Error} If job fails or times out
+     *
+     * @example
+     * ```typescript
+     * const result = await client.events.send(envelope)
+     * const status = await client.jobs.waitForCompletion(result.jobId)
+     * console.log('Processed events:', status.returnValue?.results)
+     * ```
+     */
+    waitForCompletion(jobId: string, options?: WaitForCompletionOptions): Promise<JobStatus>;
+}
+
+/**
+ * Caliper Client
+ *
+ * Main entry point for the Caliper Analytics SDK.
+ */
+/**
+ * Caliper Analytics API client.
+ *
+ * Provides methods to send, list, and retrieve Caliper learning events,
+ * as well as track async processing jobs.
+ *
+ * @example
+ * ```typescript
+ * // Environment mode (Timeback APIs)
  * const client = new CaliperClient({
- *   env: 'staging',
+ *   env: 'staging', // or 'production'
  *   auth: {
  *     clientId: 'your-client-id',
  *     clientSecret: 'your-client-secret',
  *   },
  * })
+ * ```
  *
- * // Send activity completion with metrics
- * const result = await client.events.sendActivity(
- *   'https://myapp.example.com/sensors/main',
- *   {
- *     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' },
- *     },
- *     metrics: [
- *       { type: 'totalQuestions', value: 10 },
- *       { type: 'correctQuestions', value: 8 },
- *       { type: 'xpEarned', value: 150 },
- *     ],
+ * @example
+ * ```typescript
+ * // Provider mode (shared tokens)
+ * import { TimebackProvider } from '@timeback/internal-client-infra'
+ *
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ *
+ * const client = new CaliperClient({ provider })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Explicit mode (custom API)
+ * const client = new CaliperClient({
+ *   baseUrl: 'https://caliper.example.com',
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *     authUrl: 'https://auth.example.com/oauth2/token',
  *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Environment variables fallback
+ * // Set CALIPER_BASE_URL, CALIPER_TOKEN_URL,
+ * // CALIPER_CLIENT_ID, CALIPER_CLIENT_SECRET
+ * const client = new CaliperClient()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Sending events
+ * const result = await client.events.send(
+ *   'https://example.edu/sensors/lms',
+ *   [{
+ *     id: 'urn:uuid:...',
+ *     type: 'NavigationEvent',
+ *     actor: 'https://example.edu/users/123',
+ *     action: 'NavigatedTo',
+ *     object: 'https://example.edu/courses/456',
+ *     eventTime: new Date().toISOString(),
+ *     profile: 'GeneralProfile',
+ *   }]
  * )
  *
  * // Wait for processing
  * const status = await client.jobs.waitForCompletion(result.jobId)
  * ```
+ */
+declare const CaliperClient: {
+    new (config?: CaliperClientConfig): {
+        readonly transport: CaliperTransportLike;
+        readonly _provider?: _timeback_internal_client_infra.TimebackProvider | undefined;
+        readonly events: EventsResource;
+        readonly jobs: JobsResource;
+        getTransport(): CaliperTransportLike;
+        checkAuth(): Promise<_timeback_internal_client_infra.AuthCheckResult>;
+    };
+};
+
+/**
+ * Caliper Client Factory
+ *
+ * Creates CaliperClient classes bound to specific provider registries.
+ */
+
+/**
+ * Create a CaliperClient class bound to a specific provider registry.
+ *
+ * @param registry - Provider registry to use (defaults to all Timeback platforms)
+ * @returns CaliperClient class bound to the registry
+ */
+declare function createCaliperClient(registry?: ProviderRegistry): {
+    new (config?: CaliperClientConfig): {
+        /** @internal */
+        readonly transport: CaliperTransportLike;
+        /** @internal */
+        readonly _provider?: TimebackProvider | undefined;
+        /** Send and query Caliper learning events for analytics and activity tracking */
+        readonly events: EventsResource;
+        /** Create and monitor batch event processing jobs for high-volume event ingestion */
+        readonly jobs: JobsResource;
+        /**
+         * Get the underlying transport for advanced use cases.
+         * @returns The transport instance used by this client
+         */
+        getTransport(): CaliperTransportLike;
+        /**
+         * Verify that OAuth authentication is working.
+         * @returns Auth check result
+         * @throws {Error} If client was initialized with custom transport (no provider)
+         */
+        checkAuth(): Promise<AuthCheckResult>;
+    };
+};
+
+/**
+ * Event Factory Functions
+ *
+ * Pure factory functions for creating Timeback profile events.
+ * Use these when you want to batch multiple events into a single envelope.
+ */
+
+/**
+ * Create an ActivityEvent from input.
+ *
+ * Pure factory function - creates the event object without sending.
+ * Use this when you want to batch multiple events into a single envelope.
+ *
+ * @param input - Activity completion data
+ * @returns A fully-formed ActivityCompletedEvent ready to send
  *
  * @example
  * ```typescript
- * // Timeback Profile - Time Spent
- * await client.events.sendTimeSpent(
- *   'https://myapp.example.com/sensors/main',
- *   {
- *     actor: { id: '...', type: 'TimebackUser', email: 'student@example.edu' },
- *     object: { id: '...', type: 'TimebackActivityContext', subject: 'Reading', app: { name: 'My App' } },
- *     metrics: [
- *       { type: 'active', value: 1800 },   // 30 minutes
- *       { type: 'inactive', value: 300 },  // 5 minutes
- *     ],
- *   },
- * )
+ * import { createActivityEvent, createTimeSpentEvent } from '@timeback/caliper'
+ *
+ * const activityEvent = createActivityEvent({
+ *   actor: { id: '...', type: 'TimebackUser', email: 'student@example.edu' },
+ *   object: { id: '...', type: 'TimebackActivityContext', subject: 'Math', app: { name: 'My App' } },
+ *   metrics: [
+ *     { type: 'totalQuestions', value: 10 },
+ *     { type: 'correctQuestions', value: 8 },
+ *   ],
+ * })
+ *
+ * const timeSpentEvent = createTimeSpentEvent({
+ *   actor: { id: '...', type: 'TimebackUser', email: 'student@example.edu' },
+ *   object: { id: '...', type: 'TimebackActivityContext', subject: 'Math', app: { name: 'My App' } },
+ *   metrics: [{ type: 'active', value: 1800 }],
+ * })
+ *
+ * // Send both in one envelope
+ * await client.events.send(sensor, [activityEvent, timeSpentEvent])
  * ```
+ */
+declare function createActivityEvent(input: ActivityCompletedInput): ActivityCompletedEvent;
+/**
+ * Create a TimeSpentEvent from input.
+ *
+ * Pure factory function - creates the event object without sending.
+ * Use this when you want to batch multiple events into a single envelope.
+ *
+ * @param input - Time spent data
+ * @returns A fully-formed TimeSpentEvent ready to send
  *
  * @example
  * ```typescript
- * // Generic Caliper Events
- * // For non-Timeback Caliper events, use the generic method
- * await client.events.send('https://sensor.url', [genericCaliperEvent])
+ * import { createTimeSpentEvent } from '@timeback/caliper'
+ *
+ * const event = createTimeSpentEvent({
+ *   actor: { id: '...', type: 'TimebackUser', email: 'student@example.edu' },
+ *   object: { id: '...', type: 'TimebackActivityContext', subject: 'Reading', app: { name: 'My App' } },
+ *   metrics: [
+ *     { type: 'active', value: 1800 },
+ *     { type: 'inactive', value: 300 },
+ *   ],
+ * })
+ *
+ * await client.events.send(sensor, [event])
  * ```
  */
-export { CaliperClient } from './client';
-export { createCaliperClient } from './factory';
-export type { CaliperClientInstance } from './client';
-export type { CaliperClientConfig, Environment, EnvAuth, ExplicitAuth } from './types/client';
-export type { AuthCheckResult } from '@timeback/internal-client-infra';
-export { createActivityEvent, createTimeSpentEvent } from './lib/event-factories';
-export type { TimebackUser, TimebackUserRole, TimebackActivityContext, TimebackSubject, TimebackApp, TimebackCourse, TimebackActivity, TimebackActivityMetric, TimebackActivityMetricsCollection, ActivityMetricType, TimeSpentMetric, TimebackTimeSpentMetricsCollection, TimeSpentMetricType, ActivityCompletedEvent, TimeSpentEvent, TimebackEvent, } from '@timeback/types/protocols/caliper';
-export type { ActivityCompletedInput, TimeSpentInput, CaliperListEventsParams as ListEventsParams, } from '@timeback/types/zod';
-export { CALIPER_DATA_VERSION } from './constants';
-export type { CaliperEnvelope, CaliperEvent, CaliperProfile, JobStatus, SendEventsResult, StoredEvent, ValidationResult, } from '@timeback/types/protocols/caliper';
-export { Transport } from './lib';
-//# sourceMappingURL=index.d.ts.map
+declare function createTimeSpentEvent(input: TimeSpentInput): TimeSpentEvent;
+
+/**
+ * Transport Layer
+ *
+ * HTTP transport for Caliper API communication.
+ */
+
+/**
+ * HTTP transport layer for Caliper API communication.
+ *
+ * Extends BaseTransport with Caliper-specific path configuration.
+ * Uses body-based pagination (events array + pagination metadata).
+ */
+declare class Transport extends BaseTransport {
+    /** API path profiles for Caliper operations */
+    readonly paths: CaliperPaths;
+    constructor(config: CaliperTransportConfig);
+    /**
+     * Make a paginated request using body-based pagination.
+     *
+     * Caliper APIs return pagination metadata in the response body:
+     * - `events`: Array of items
+     * - `pagination`: { total, totalPages, currentPage, limit }
+     *
+     * @param path - API endpoint path
+     * @param options - Request options
+     * @returns Normalized paginated response with hasMore and total
+     */
+    requestPaginated<T>(path: string, options?: RequestOptions): Promise<PaginatedResponse<T>>;
+}
+
+export { ActivityCompletedInput, CALIPER_DATA_VERSION, CaliperClient, CaliperListEventsParams as ListEventsParams, TimeSpentInput, Transport, createActivityEvent, createCaliperClient, createTimeSpentEvent };
+export type { ActivityCompletedEvent, ActivityMetricType, CaliperClientConfig, CaliperClientInstance, CaliperEnvelope, CaliperEvent, CaliperProfile, JobStatus, SendEventsResult, StoredEvent, TimeSpentEvent, TimeSpentMetric, TimeSpentMetricType, TimebackActivity, TimebackActivityContext, TimebackActivityMetric, TimebackActivityMetricsCollection, TimebackApp, TimebackCourse, TimebackEvent, TimebackSubject, TimebackTimeSpentMetricsCollection, TimebackUser, TimebackUserRole, ValidationResult };