@timeback/caliper 0.1.0

package/README.md

@@ -0,0 +1,278 @@
+# @timeback/caliper
+
+TypeScript client for IMS Caliper Analytics v1.2 — learning activity events with Timeback Profile support.
+
+## Installation
+
+```bash
+bun add @timeback/caliper
+```
+
+## Quick Start
+
+```typescript
+import { CaliperClient } from '@timeback/caliper'
+
+const caliper = new CaliperClient({
+	env: 'staging', // or 'production'
+	auth: {
+		clientId: 'your-client-id',
+		clientSecret: 'your-client-secret',
+	},
+})
+
+// Send a Timeback activity completion event
+const result = await caliper.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 },
+	],
+})
+
+const status = await caliper.jobs.waitForCompletion(result.jobId)
+```
+
+## API Design
+
+### Standalone vs Composed
+
+```typescript
+// Composed
+import { TimebackClient } from '@timeback/core'
+
+// Standalone
+const caliper = new CaliperClient({ env: 'staging', auth })
+
+const client = new TimebackClient({ env: 'staging', auth })
+client.caliper.events.sendActivity(sensor, input)
+```
+
+### Client Structure
+
+```typescript
+const client = new CaliperClient(options)
+
+// Events
+client.events.send(sensor, events)                  // Send events
+client.events.sendEnvelope(envelope)                // Send raw envelope
+client.events.validate(envelope)                    // Validate without storing
+client.events.sendActivity(sensor, input)  			// Timeback Profile
+client.events.sendTimeSpent(sensor, input)          // Timeback Profile
+client.events.list(params?)                         // List events
+client.events.get(externalId)                       // Get event by ID
+
+// Jobs
+client.jobs.getStatus(jobId)                        // Check job status
+client.jobs.waitForCompletion(jobId, options?)      // Poll until complete
+```
+
+### Timeback Profile (Recommended)
+
+The Timeback Profile extends Caliper with events optimized for the Timeback platform:
+
+```typescript
+// Activity completion with metrics
+await client.events.sendActivity(sensor, {
+	actor: {
+		id: 'https://api.example.com/users/123',
+		type: 'TimebackUser',
+		email: 'student@example.edu',
+		role: 'student',
+	},
+	object: {
+		id: 'https://myapp.example.com/activities/456',
+		type: 'TimebackActivityContext',
+		subject: 'Math', // Reading, Language, Science, etc.
+		app: { name: 'My Learning App' },
+		course: { name: 'Algebra 101' },
+		activity: { name: 'Chapter 1 Quiz' },
+	},
+	metrics: [
+		{ type: 'totalQuestions', value: 10 },
+		{ type: 'correctQuestions', value: 8 },
+		{ type: 'xpEarned', value: 150 },
+		{ type: 'masteredUnits', value: 2 },
+	],
+})
+
+// Time spent tracking
+await client.events.sendTimeSpent(sensor, {
+	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 in seconds
+		{ type: 'inactive', value: 300 }, // 5 minutes
+	],
+})
+```
+
+### Batching Events
+
+Use factory functions to batch multiple events in a single envelope:
+
+```typescript
+import {
+	CaliperClient,
+	createActivityEvent,
+	createTimeSpentEvent,
+} from '@timeback/caliper'
+
+const activityEvent = createActivityEvent({
+	actor: { ... },
+	object: { ... },
+	metrics: [{ type: 'correctQuestions', value: 8 }],
+})
+
+const timeSpentEvent = createTimeSpentEvent({
+	actor: { ... },
+	object: { ... },
+	metrics: [{ type: 'active', value: 1800 }],
+})
+
+// Send both in one API call
+const result = await client.events.send(sensor, [activityEvent, timeSpentEvent])
+```
+
+### Generic Caliper Events
+
+For non-Timeback events, use the generic API:
+
+```typescript
+const event = {
+	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',
+}
+
+await client.events.send(sensor, [event])
+```
+
+### Job Tracking
+
+Events are processed asynchronously. Track status with the jobs resource:
+
+```typescript
+const result = await client.events.sendActivity(sensor, input)
+
+// Poll until complete
+const status = await client.jobs.waitForCompletion(result.jobId, {
+	timeoutMs: 30000, // Max wait time (default: 30s)
+	pollIntervalMs: 1000, // Check interval (default: 1s)
+})
+
+if (status.state === 'completed') {
+	console.log('Processed:', status.returnValue?.results)
+}
+
+// Or check manually
+const status = await client.jobs.getStatus(result.jobId)
+// status.state: 'waiting' | 'active' | 'completed' | 'failed'
+```
+
+### Authentication
+
+The client handles OAuth2 token management automatically:
+
+```typescript
+// Environment mode (recommended for Timeback APIs)
+const client = new CaliperClient({
+	env: 'staging', // or 'production'
+	auth: {
+		clientId: 'xxx',
+		clientSecret: 'xxx',
+	},
+})
+
+// Explicit mode (custom API)
+const client = new CaliperClient({
+	baseUrl: 'https://caliper.example.com',
+	auth: {
+		clientId: 'xxx',
+		clientSecret: 'xxx',
+		authUrl: 'https://auth.example.com/oauth2/token',
+	},
+})
+```
+
+Tokens are cached and refreshed automatically before expiry.
+
+### Error Handling
+
+```typescript
+import { ApiError } from '@timeback/caliper'
+
+try {
+	await client.events.get('invalid-id')
+} catch (error) {
+	if (error instanceof ApiError) {
+		console.log(error.status) // HTTP status
+		console.log(error.message) // Error message
+	}
+}
+```
+
+## Configuration
+
+```typescript
+new CaliperClient({
+	// Environment mode (Timeback APIs)
+	env: 'staging' | 'production',
+	auth: {
+		clientId: string,
+		clientSecret: string,
+	},
+
+	// OR Explicit mode (custom API)
+	baseUrl: string,
+	auth: {
+		clientId: string,
+		clientSecret: string,
+		authUrl: string,
+	},
+
+	// Optional
+	fetch?: typeof fetch,  // Custom fetch implementation
+	timeout?: number,      // Request timeout in ms (default: 30000)
+
+	// Internal (for composition with @timeback/core)
+	transport?: Transport, // Shared HTTP transport
+})
+```
+
+## Debug Mode
+
+Enable debug logging by setting `DEBUG=1` or `DEBUG=true`:
+
+```bash
+DEBUG=1 bun run my-script.ts
+```
+
+This outputs detailed logs for HTTP requests and authentication:
+
+```bash
+[2025-01-15T10:30:00.000Z] DEBUG [caliper:auth] Fetching new access token...
+[2025-01-15T10:30:00.500Z] DEBUG [caliper:auth] Token acquired (500ms, expires in 3600s)
+[2025-01-15T10:30:00.501Z] DEBUG [caliper:http] → POST https://api.example.com/caliper/event
+[2025-01-15T10:30:00.800Z] DEBUG [caliper:http] ← 202 Accepted (299ms)
+```

package/dist/client.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 Environment mode (Timeback APIs)
+ * ```typescript
+ * const client = new CaliperClient({
+ *   env: 'staging', // or 'production'
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *   },
+ * })
+ * ```
+ *
+ * @example Provider mode (shared tokens)
+ * ```typescript
+ * 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 Explicit mode (custom API)
+ * ```typescript
+ * 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 Environment variables fallback
+ * ```typescript
+ * // Set CALIPER_BASE_URL, CALIPER_TOKEN_URL,
+ * // CALIPER_CLIENT_ID, CALIPER_CLIENT_SECRET
+ * const client = new CaliperClient()
+ * ```
+ *
+ * @example Sending events
+ * ```typescript
+ * 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)
+ * ```
+ */
+export declare const CaliperClient: {
+    new (config?: import("./types").CaliperClientConfig): {
+        readonly transport: import("./types").CaliperTransportLike;
+        readonly _provider?: import("@timeback/internal-client-infra").TimebackProvider | undefined;
+        readonly events: import("./resources").EventsResource;
+        readonly jobs: import("./resources").JobsResource;
+        getTransport(): import("./types").CaliperTransportLike;
+        checkAuth(): Promise<import("@timeback/internal-client-infra").AuthCheckResult>;
+    };
+};
+export type { CaliperClientInstance } from './types';
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;CAAwB,CAAA;AAElD,YAAY,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA"}

package/dist/constants.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Caliper Constants
+ *
+ * Configuration constants for the Caliper Analytics client.
+ */
+import type { ClientUrlMaps, Platform } from '@timeback/internal-client-infra';
+/**
+ * Environment variable names for Caliper configuration.
+ */
+export declare const CALIPER_ENV_VARS: {
+    readonly baseUrl: "CALIPER_BASE_URL";
+    readonly authUrl: "CALIPER_TOKEN_URL";
+    readonly clientId: "CALIPER_CLIENT_ID";
+    readonly clientSecret: "CALIPER_CLIENT_SECRET";
+};
+/**
+ * Caliper JSON-LD context version.
+ */
+export declare const CALIPER_DATA_VERSION = "http://purl.imsglobal.org/ctx/caliper/v1p2";
+/**
+ * Get URL maps for a specific platform.
+ * Defaults to 'BEYOND_AI' for backwards compatibility.
+ * @param platform - Platform name
+ * @returns Client URL maps for the platform
+ */
+export declare function getUrlMapsForPlatform(platform?: Platform): ClientUrlMaps;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAE9E;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAA;AAEV;;GAEG;AACH,eAAO,MAAM,oBAAoB,+CAA+C,CAAA;AAEhF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAE,QAA2B,GAAG,aAAa,CAM1F"}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Caliper Error Classes
+ *
+ * Re-exports common errors from `@timeback/internal-client-infra`.
+ */
+export { ApiError as CaliperError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError, } from '@timeback/internal-client-infra';
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,QAAQ,IAAI,YAAY,EACxB,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,GACf,MAAM,iCAAiC,CAAA"}

package/dist/factory.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Caliper Client Factory
+ *
+ * Creates CaliperClient classes bound to specific provider registries.
+ */
+import { EventsResource, JobsResource } from './resources';
+import type { AuthCheckResult, ProviderRegistry, TimebackProvider } from '@timeback/internal-client-infra';
+import type { CaliperClientConfig, CaliperTransportLike } from './types';
+/**
+ * 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
+ */
+export 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>;
+    };
+};
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG1D,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAC1G,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAExE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,gBAA4C;;QAQxF,gBAAgB;;QAGhB,gBAAgB;;QAGhB,iFAAiF;;QAEjF,qFAAqF;;QA0CrF;;;WAGG;;QAKH;;;;WAIG;;;EASJ"}

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Caliper Analytics client SDK for Timeback.
+ *
+ * Caliper Analytics client SDK for Timeback.
+ *
+ * @example Timeback Profile - Activity Completed (recommended)
+ * ```typescript
+ * import { CaliperClient } from '@timeback/caliper'
+ *
+ * const client = new CaliperClient({
+ *   env: 'staging',
+ *   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 },
+ *     ],
+ *   },
+ * )
+ *
+ * // Wait for processing
+ * const status = await client.jobs.waitForCompletion(result.jobId)
+ * ```
+ *
+ * @example Timeback Profile - Time Spent
+ * ```typescript
+ * 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
+ *     ],
+ *   },
+ * )
+ * ```
+ *
+ * @example Generic Caliper Events
+ * ```typescript
+ * // For non-Timeback Caliper events, use the generic method
+ * await client.events.send('https://sensor.url', [genericCaliperEvent])
+ * ```
+ */
+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, ActivityCompletedInput, TimeSpentInput, } from './types/timeback';
+export { CALIPER_DATA_VERSION } from './constants';
+export type { CaliperEnvelope, CaliperEvent, CaliperProfile, JobStatus, ListEventsParams, SendEventsResult, StoredEvent, ValidationResult, } from './types';
+export { Transport } from './lib';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAMH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAE/C,YAAY,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AACrD,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7F,YAAY,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAMtE,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAEjF,YAAY,EACX,YAAY,EACZ,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,iCAAiC,EACjC,kBAAkB,EAClB,eAAe,EACf,kCAAkC,EAClC,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,sBAAsB,EACtB,cAAc,GACd,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAElD,YAAY,EACX,eAAe,EACf,YAAY,EACZ,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GAChB,MAAM,SAAS,CAAA;AAMhB,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA"}