@timeback/sdk 0.1.4 → 0.1.5

package/dist/server/handlers/activity.d.ts

@@ -3,19 +3,16 @@
  *
  * Route handlers for activity tracking.
  */
-import type { ApiCredentials, AppConfig, Environment, IdentityConfig } from '../types';
-/**
- * Configuration for the activity handler.
- */
+import type { ApiCredentials, AppConfig, Environment, IdentityConfig, TimebackConfig } from '../types';
+/** Configuration for the activity handler. */
 interface ActivityHandlerConfig {
     env: Environment;
     identity: IdentityConfig;
     appConfig: AppConfig;
     api: ApiCredentials;
+    hooks?: TimebackConfig['hooks'];
 }
-/**
- * Activity handler type.
- */
+/** Activity handler type. */
 type ActivityHandler = (req: Request) => Promise<Response>;
 /**
  * Create the activity POST handler.

package/dist/server/handlers/activity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/activity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAuFtF;;GAEG;AACH,UAAU,qBAAqB;IAC9B,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,SAAS,EAAE,SAAS,CAAA;IACpB,GAAG,EAAE,cAAc,CAAA;CACnB;AAED;;GAEG;AACH,KAAK,eAAe,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE1D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAqIpF"}
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/activity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4BH,OAAO,KAAK,EAEX,cAAc,EACd,SAAS,EACT,WAAW,EACX,cAAc,EACd,cAAc,EACd,MAAM,UAAU,CAAA;AA4CjB,8CAA8C;AAC9C,UAAU,qBAAqB;IAC9B,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,SAAS,EAAE,SAAS,CAAA;IACpB,GAAG,EAAE,cAAc,CAAA;IACnB,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;CAC/B;AAED,6BAA6B;AAC7B,KAAK,eAAe,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AA4S1D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAmFpF"}

package/dist/server/handlers/user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/user.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAItF;;GAEG;AACH,UAAU,iBAAiB;IAC1B,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,EAAE,SAAS,CAAA;CACpB;AAED;;GAEG;AACH,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAyFxE"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/user.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAItF;;GAEG;AACH,UAAU,iBAAiB;IAC1B,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,EAAE,SAAS,CAAA;CACpB;AAED;;GAEG;AACH,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAuGxE"}

package/dist/server/lib/build-activity-events.d.ts

@@ -2,16 +2,44 @@ import type { ActivityCompletedEvent, TimebackActivityContext, TimebackActivityM
 import type { TimebackClient } from '@timeback/core';
 import type { ActivityEndPayload, ActivityMetrics } from '../../shared/types';
 import type { AppConfig } from '../types';
+/**
+ * Error thrown when a course is missing a synced ID for the target environment.
+ */
+export declare class MissingSyncedCourseIdError extends Error {
+    readonly course: AppConfig['courses'][number];
+    readonly env: 'staging' | 'production';
+    constructor(course: AppConfig['courses'][number], env: 'staging' | 'production');
+}
+/**
+ * Error thrown when the sensor URL is invalid.
+ */
+export declare class InvalidSensorUrlError extends Error {
+    readonly sensor: string;
+    constructor(sensor: string);
+}
 /**
  * Build a Timeback activity context for Caliper events.
  *
+ * Handles both grade-based and grade-less courses:
+ * - Grade-based: uses subject + grade for IDs
+ * - Grade-less: uses code for IDs
+ *
+ * The `id` field (`object.id` in Caliper) is a canonical URL derived from the
+ * sensor, course selector, and activity slug. This enables upstream systems to
+ * process the activity as an "external URL" activity without requiring
+ * pre-synced OneRoster component resources.
+ *
+ * The `activity` field contains only the human-readable `name` (no `id`),
+ * since the canonical URL in `object.id` serves as the stable identifier.
+ *
  * @param payload - Validated activity payload
  * @param course - Matched course config
  * @param appName - Timeback app display name
  * @param apiEnv - Target Timeback API environment
+ * @param sensor - Sensor URL for building the canonical activity URL
  * @returns Caliper activity context payload
  */
-export declare function buildActivityContext(payload: ActivityEndPayload, course: AppConfig['courses'][number], appName: string, apiEnv: 'staging' | 'production'): TimebackActivityContext;
+export declare function buildActivityContext(payload: ActivityEndPayload, course: AppConfig['courses'][number], appName: string, apiEnv: 'staging' | 'production', sensor: string): TimebackActivityContext;
 /**
  * Build Caliper activity metrics from the client payload.
  *

package/dist/server/lib/build-activity-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-activity-events.d.ts","sourceRoot":"","sources":["../../../src/server/lib/build-activity-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EAEtB,cAAc,EACd,eAAe,EACf,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEzC;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EACpC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,GAAG,YAAY,GAC9B,uBAAuB,CAgBzB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,sBAAsB,EAAE,CAoBvF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAQ5F;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,sBAAsB,EACrC,cAAc,EAAE,cAAc,GAC5B,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"build-activity-events.d.ts","sourceRoot":"","sources":["../../../src/server/lib/build-activity-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EAEtB,cAAc,EACd,eAAe,EACf,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EAAqB,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAChG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEzC;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;IAC7C,QAAQ,CAAC,GAAG,EAAE,SAAS,GAAG,YAAY,CAAA;IAEtC,YAAY,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,YAAY,EAW9E;CACD;AA8CD;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB,YAAY,MAAM,EAAE,MAAM,EAMzB;CACD;AAiED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EACpC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,GAAG,YAAY,EAChC,MAAM,EAAE,MAAM,GACZ,uBAAuB,CAYzB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,sBAAsB,EAAE,CAoBvF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAQ5F;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,sBAAsB,EACrC,cAAc,EAAE,cAAc,GAC5B,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/server/lib/index.d.ts

@@ -6,9 +6,7 @@
 export { getIssuer, buildAuthorizationUrl, exchangeCodeForTokens, getUserInfo } from './oidc';
 export { jsonResponse, redirectResponse, encodeBase64Url, decodeBase64Url, mapEnvForApi, } from './utils';
 export { ssoLog, oidcLog, createScopedLogger } from './logger';
-export { resolveTimebackUserByEmail, TimebackUserResolutionError } from './resolve-timeback-user';
-export { buildActivityContext, buildActivityMetrics, buildTimeSpentMetrics, sendCaliperEnvelope, } from './build-activity-events';
-export { resolveActivityCourse, ActivityCourseResolutionError } from './resolve-activity-course';
-export { resolveStatusForUserResolutionError, resolveTimebackIdForActivity, } from './resolve-timeback-id';
+export { ActivityCourseResolutionError, lookupTimebackIdByEmail, resolveActivityCourse, resolveStatusForUserResolutionError, resolveTimebackUserByEmail, TimebackUserResolutionError, } from './resolve';
+export { buildActivityContext, buildActivityMetrics, buildTimeSpentMetrics, InvalidSensorUrlError, MissingSyncedCourseIdError, sendCaliperEnvelope, } from './build-activity-events';
 export { buildCourseLookup, getUtcDayRange, mapEnrollmentsToCourses, pickGoalsFromEnrollments, sumXp, } from './build-user-profile';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC7F,OAAO,EACN,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,GACZ,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC9D,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAA;AACjG,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,2BAA2B,CAAA;AAChG,OAAO,EACN,mCAAmC,EACnC,4BAA4B,GAC5B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACN,iBAAiB,EACjB,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,KAAK,GACL,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC7F,OAAO,EACN,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,GACZ,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC9D,OAAO,EACN,6BAA6B,EAC7B,uBAAuB,EACvB,qBAAqB,EACrB,mCAAmC,EACnC,0BAA0B,EAC1B,2BAA2B,GAC3B,MAAM,WAAW,CAAA;AAClB,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,GACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACN,iBAAiB,EACjB,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,KAAK,GACL,MAAM,sBAAsB,CAAA"}

package/dist/server/lib/resolve.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Resolution Utilities
+ *
+ * Functions for resolving Timeback users and activity courses.
+ *
+ * ## User Resolution
+ *
+ * - `resolveTimebackUserByEmail` — Full user resolution returning profile + IdP claims.
+ *   Used by SSO callback to build the authenticated user object.
+ *
+ * - `lookupTimebackIdByEmail` — Simple lookup returning just the timebackId.
+ *   Used by activity/user handlers when only the ID is needed.
+ *
+ * - `resolveStatusForUserResolutionError` — Maps error codes to HTTP status.
+ *   Used by handlers to return appropriate status codes on resolution failure.
+ *
+ * ## Course Resolution
+ *
+ * - `resolveActivityCourse` — Resolves a course selector to a config entry.
+ *   Used by activity handler to match client payload to configured courses.
+ */
+import { TimebackClient } from '@timeback/core';
+import type { ActivityCourseRef, TimebackAuthUser } from '../../shared/types';
+import type { ApiCredentials, AppConfig, Environment, OIDCUserInfo, TimebackUserResolutionErrorCode } from '../types';
+/**
+ * Error thrown when Timeback user resolution fails.
+ */
+export declare class TimebackUserResolutionError extends Error {
+    readonly code: TimebackUserResolutionErrorCode;
+    constructor(message: string, code: TimebackUserResolutionErrorCode);
+}
+/**
+ * Map a user resolution error to an HTTP status code.
+ *
+ * @param err - Timeback user resolution error
+ * @returns HTTP status code (409 for ambiguous, 404 otherwise)
+ */
+export declare function resolveStatusForUserResolutionError(err: TimebackUserResolutionError): number;
+interface ResolveTimebackUserByEmailParams {
+    /** Environment (staging/production) */
+    env: Environment;
+    /** API credentials for Timeback API */
+    apiCredentials: ApiCredentials;
+    /** OIDC user info from the IdP */
+    userInfo: OIDCUserInfo;
+    /**
+     * Optional pre-configured Timeback client.
+     * When provided, this function will use it and will NOT close it.
+     */
+    client?: TimebackClient;
+}
+interface LookupTimebackIdByEmailParams {
+    /** User's email address */
+    email: string;
+    /** Pre-configured Timeback client */
+    client: TimebackClient;
+}
+/**
+ * Resolve a full TimebackAuthUser by email.
+ *
+ * **Use case:** SSO callback — after OIDC authentication, look up the Timeback
+ * user and return a complete auth object with profile data and IdP claims.
+ *
+ * @param params - Resolution parameters including OIDC userInfo
+ * @returns TimebackAuthUser with profile and IdP claims
+ * @throws {TimebackUserResolutionError} If resolution fails
+ */
+export declare function resolveTimebackUserByEmail(params: ResolveTimebackUserByEmailParams): Promise<TimebackAuthUser>;
+/**
+ * Look up the Timeback user ID by email.
+ *
+ * **Use case:** Activity/user handlers — when you only need the timebackId,
+ * not the full auth object.
+ *
+ * @param params - Email and pre-configured client
+ * @returns The Timeback user ID (sourcedId)
+ * @throws {TimebackUserResolutionError} If lookup fails
+ */
+export declare function lookupTimebackIdByEmail(params: LookupTimebackIdByEmailParams): Promise<string>;
+/**
+ * Error thrown when a course selector cannot be resolved against config.
+ */
+export declare class ActivityCourseResolutionError extends Error {
+    readonly code: 'unknown_course' | 'ambiguous_course';
+    readonly selector: ActivityCourseRef;
+    readonly count?: number;
+    constructor(code: ActivityCourseResolutionError['code'], selector: ActivityCourseRef, count?: number);
+    /**
+     * Get a human-readable description of the selector.
+     *
+     * @returns Human-readable selector description
+     */
+    get selectorDescription(): string;
+}
+/**
+ * Resolve a course config entry from an activity course selector.
+ *
+ * **Use case:** Activity handler — match the client's course selector
+ * to a configured course in `timeback.config.ts`.
+ *
+ * Supports two selector modes:
+ * - **subjectGrade**: Match by `(subject, grade)`
+ * - **courseCode**: Match by `courseCode`
+ *
+ * @param courses - Configured courses from `timeback.config.ts`
+ * @param courseRef - Course selector from the client payload
+ * @returns Matched course config entry
+ * @throws {ActivityCourseResolutionError} When selector is unknown or ambiguous
+ */
+export declare function resolveActivityCourse(courses: AppConfig['courses'], courseRef: ActivityCourseRef): AppConfig['courses'][number];
+export {};
+//# sourceMappingURL=resolve.d.ts.map

package/dist/server/lib/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/server/lib/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAM/C,OAAO,KAAK,EACX,iBAAiB,EAEjB,gBAAgB,EAEhB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EACX,cAAc,EACd,SAAS,EACT,WAAW,EACX,YAAY,EACZ,+BAA+B,EAC/B,MAAM,UAAU,CAAA;AAQjB;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;aAGpC,IAAI,EAAE,+BAA+B;IAFtD,YACC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,+BAA+B,EAIrD;CACD;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,2BAA2B,GAAG,MAAM,CAE5F;AAMD,UAAU,gCAAgC;IACzC,uCAAuC;IACvC,GAAG,EAAE,WAAW,CAAA;IAChB,uCAAuC;IACvC,cAAc,EAAE,cAAc,CAAA;IAC9B,kCAAkC;IAClC,QAAQ,EAAE,YAAY,CAAA;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAA;CACvB;AAED,UAAU,6BAA6B;IACtC,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,MAAM,EAAE,cAAc,CAAA;CACtB;AA2FD;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC/C,MAAM,EAAE,gCAAgC,GACtC,OAAO,CAAC,gBAAgB,CAAC,CAsD3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC5C,MAAM,EAAE,6BAA6B,GACnC,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAMD;;GAEG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACvD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CAAA;IACpD,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IAEvB,YACC,IAAI,EAAE,6BAA6B,CAAC,MAAM,CAAC,EAC3C,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,CAAC,EAAE,MAAM,EAMd;IAED;;;;OAIG;IACH,IAAI,mBAAmB,IAAI,MAAM,CAKhC;CACD;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,EAC7B,SAAS,EAAE,iBAAiB,GAC1B,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAoB9B"}

package/dist/server/timeback.d.ts

@@ -56,9 +56,9 @@ import type { TimebackConfig, TimebackInstance } from './types';
  *   api: { ... },
  *   identity: {
  *     mode: 'custom',
- *     getUser: async (req) => {
+ *     getEmail: async (req) => {
  *       const session = await getSession(req)
- *       return session ? { id: session.userId, email: session.email } : undefined
+ *       return session?.email
  *     },
  *   },
  * })

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

@@ -1 +1 @@
-{"version":3,"file":"timeback.d.ts","sourceRoot":"","sources":["../../src/server/timeback.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAsB,cAAc,CAAC,MAAM,GAAG,OAAO,EACpD,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAsEnC"}
+{"version":3,"file":"timeback.d.ts","sourceRoot":"","sources":["../../src/server/timeback.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAa,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAsB1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAsB,cAAc,CAAC,MAAM,GAAG,OAAO,EACpD,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAuEnC"}

package/dist/server/types.d.ts

@@ -3,8 +3,9 @@
  *
  * Configuration and internal types for the server SDK.
  */
+import type { ActivityCompletedEvent, TimeSpentEvent } from '@timeback/caliper';
 import type { TimebackClient } from '@timeback/core';
-import type { TimebackAuthUser, TimebackIdentity } from '../shared/types';
+import type { ActivityEndPayload, TimebackAuthUser, TimebackIdentity } from '../shared/types';
 /**
  * Environment configuration.
  */
@@ -278,20 +279,65 @@ export interface SsoIdentityConfig<TState = unknown, TSuccessContext = CallbackS
 export interface CustomIdentityConfig {
     mode: 'custom';
     /**
-     * Get the current user from the request.
+     * Get the current user's email from the request.
      *
-     * Read your session cookie/JWT and return the user, or undefined if not authenticated.
+     * Read your session cookie/JWT and return the user's email, or undefined if not authenticated.
+     * The SDK resolves the Timeback user by email.
      * Can return synchronously or as a Promise.
      *
      * @param req - The incoming request
-     * @returns User object or undefined (sync or async)
+     * @returns User's email or undefined (sync or async)
+     *
+     * @example
+     * ```typescript
+     * // From session cookie
+     * getEmail: req => getSessionFromCookie(req)?.email
+     *
+     * // From JWT
+     * getEmail: async req => {
+     *   const token = await verifyToken(req)
+     *   return token?.email
+     * }
+     * ```
      */
-    getUser(req: Request): Promise<TimebackIdentity | undefined> | TimebackIdentity | undefined;
+    getEmail(req: Request): Promise<string | undefined> | string | undefined;
 }
 /**
  * Identity configuration (SSO or custom).
  */
 export type IdentityConfig<TState = unknown> = SsoIdentityConfig<TState> | CustomIdentityConfig;
+/**
+ * Data provided to `hooks.beforeActivitySend`.
+ *
+ * This is the payload the client POSTed plus the Caliper events the SDK built.
+ * Returning `null` from the hook skips sending.
+ */
+export interface ActivityBeforeSendData {
+    /** Sensor URL selected for the event submission */
+    sensor: string;
+    /** Actor object used in generated Caliper events */
+    actor: {
+        id: string;
+        type: 'TimebackUser';
+        email: string;
+    };
+    /** Caliper context object (shape depends on SDK internals) */
+    object: unknown;
+    /** Built events (ActivityEvent + TimeSpentEvent) */
+    events: [ActivityCompletedEvent, TimeSpentEvent];
+    /** Original payload posted by the client */
+    payload: ActivityEndPayload;
+    /** Matched course from `timeback.config.ts` */
+    course: AppConfig['courses'][number];
+    /** App name (from config) */
+    appName: string;
+    /** API environment used for resolution */
+    apiEnv: 'staging' | 'production';
+    /** User email */
+    email: string;
+    /** Canonical Timeback user id */
+    timebackId: string;
+}
 /**
  * Full Timeback SDK configuration.
  */
@@ -304,6 +350,24 @@ export interface TimebackConfig<TState = unknown> {
     api: ApiCredentials;
     /** Identity configuration */
     identity: IdentityConfig<TState>;
+    /**
+     * Optional hooks for customizing SDK handler behavior.
+     *
+     * These are primarily useful for testing, demos, and advanced integrations.
+     */
+    hooks?: {
+        /**
+         * Called after Caliper events are built, right before sending.
+         *
+         * - Return the (optionally modified) data to proceed with sending
+         * - Return `null` to skip sending (handler still returns success)
+         * - Throw to fail the request
+         *
+         * @param data - Built activity events + context
+         * @returns Modified data to send, or null to skip
+         */
+        beforeActivitySend?: (data: ActivityBeforeSendData) => ActivityBeforeSendData | null | Promise<ActivityBeforeSendData | null>;
+    };
 }
 /**
  * Request handlers namespace.
@@ -326,31 +390,92 @@ export interface Handlers {
         me: (req: Request) => Promise<Response>;
     };
 }
+type AppCourseMetadata = {
+    goals?: {
+        dailyXp?: number;
+        dailyLessons?: number;
+        dailyActiveMinutes?: number;
+        dailyAccuracy?: number;
+        dailyMasteredUnits?: number;
+    };
+};
+type AppCourseBase = {
+    subject: string;
+    level?: string;
+    ids?: {
+        staging?: string;
+        production?: string;
+    } | null;
+    /** Per-course sensor URL (overrides top-level sensor). */
+    sensor?: string;
+    /** Per-course launch URL (overrides top-level launchUrl). */
+    launchUrl?: string;
+    /**
+     * Environment-specific overrides for non-identity fields.
+     *
+     * These are applied when syncing/editing a course for a specific env.
+     * For activity sending, the env-specific sensor override (when present)
+     * takes precedence over base `sensor` and top-level `sensor`.
+     */
+    overrides?: {
+        staging?: {
+            level?: string;
+            sensor?: string;
+            launchUrl?: string;
+            metadata?: AppCourseMetadata;
+        };
+        production?: {
+            level?: string;
+            sensor?: string;
+            launchUrl?: string;
+            metadata?: AppCourseMetadata;
+        };
+    };
+    metadata?: AppCourseMetadata;
+};
+/**
+ * Course config as used by the SDK server handlers.
+ *
+ * Identity rules:
+ * - Grade-based: `grade` is set, `courseCode` optional
+ * - Grade-less: `grade` is undefined, `courseCode` required
+ */
+type AppCourse = (AppCourseBase & {
+    /** Grade level. */
+    grade: number;
+    /** Course code. Optional for grade-based courses. */
+    courseCode?: string;
+}) | (AppCourseBase & {
+    /** Grade-less course. */
+    grade?: undefined;
+    /** Course code. Required for grade-less courses. */
+    courseCode: string;
+});
 /**
  * App configuration from timeback.config.ts.
+ *
+ * Note: Config invariants are validated at runtime by `@timeback/types/zod`.
+ * The stricter unions here help keep SDK handler code type-safe.
+ *
+ * Course identity rules:
+ * - Grade-based: `grade` is set
+ * - Grade-less: `grade` is undefined, `courseCode` is required
+ *
+ * Sensor resolution:
+ * - Every course must have an effective sensor
+ *   (`course.overrides[env].sensor ?? course.sensor ?? config.sensor`).
+ * - This is enforced by zod validation at config load time.
+ *
+ * LaunchUrl resolution:
+ * - Every course must have an effective launchUrl
+ *   (`course.overrides[env].launchUrl ?? course.launchUrl ?? config.launchUrl`).
+ * - This is enforced by zod validation at config load time.
  */
 export interface AppConfig {
     name: string;
-    sensors: string[];
-    courses: Array<{
-        subject: string;
-        grade: number;
-        courseCode?: string;
-        level?: string;
-        ids?: {
-            staging?: string;
-            production?: string;
-        } | null;
-        metadata?: {
-            goals?: {
-                dailyXp?: number;
-                dailyLessons?: number;
-                dailyActiveMinutes?: number;
-                dailyAccuracy?: number;
-                dailyMasteredUnits?: number;
-            };
-        };
-    }>;
+    sensor?: string;
+    launchUrl?: string;
+    courses: AppCourse[];
 }
 /**
  * Timeback SDK instance (framework-agnostic).

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

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

package/dist/shared/types.d.ts

@@ -47,6 +47,8 @@ export interface TimebackProfile {
         dailyXp?: number;
         dailyLessons?: number;
         dailyActiveMinutes?: number;
+        dailyAccuracy?: number;
+        dailyMasteredUnits?: number;
     };
 }
 /**
@@ -96,21 +98,102 @@ export interface TimebackAuthUser extends TimebackProfile {
     claims: IdentityClaims;
 }
 /**
- * Course selector for activity tracking.
+ * Course selector by subject and grade (grade-based apps).
  *
- * This should correspond to a unique course entry in `timeback.config.ts`.
+ * Use this for traditional K-12 apps where courses are identified by subject + grade.
  */
-export interface ActivityCourseRef {
+export interface SubjectGradeCourseRef {
     subject: TimebackSubject;
     grade: TimebackGrade;
 }
+/**
+ * Course selector by code (grade-less apps).
+ *
+ * Use this for apps without grade levels (e.g., CS platforms) where courses
+ * are identified by a unique course code.
+ */
+export interface CourseCodeRef {
+    code: string;
+}
+/**
+ * Course selector for activity tracking.
+ *
+ * This should correspond to a unique course entry in `timeback.config.ts`.
+ *
+ * Two selector modes are supported:
+ * - **Grade-based**: `{ subject, grade }` — K-12 style
+ * - **Grade-less**: `{ code }` — CS/skill-based
+ *
+ * @example Grade-based
+ * ```typescript
+ * { subject: 'Math', grade: 3 }
+ * ```
+ *
+ * @example Grade-less
+ * ```typescript
+ * { code: 'CS-101' }
+ * ```
+ */
+export type ActivityCourseRef = SubjectGradeCourseRef | CourseCodeRef;
+/**
+ * Type guard: Check if a course ref uses subject+grade identity.
+ *
+ * @param ref - Course reference to check
+ * @returns True if grade-based selector
+ */
+export declare function isSubjectGradeCourseRef(ref: ActivityCourseRef): ref is SubjectGradeCourseRef;
 /**
  * Activity start parameters.
+ *
+ * @remarks
+ * The `id` field is treated as a **slug** (not a URL). The SDK derives the
+ * canonical activity URL (`event.object.id`) from:
+ * - The configured sensor URL
+ * - The course selector (subject + grade or code)
+ * - This slug (URI-encoded)
+ *
+ * This allows upstream systems to process activities without requiring
+ * pre-synced OneRoster component resources.
+ *
+ * @example
+ * ```typescript
+ * // Grade-based course
+ * timeback.activity.start({
+ *   id: 'fractions-with-like-denominators', // slug
+ *   name: 'Fractions with Like Denominators', // human-readable
+ *   course: { subject: 'Math', grade: 3 },
+ * })
+ * // => object.id: https://sensor.example.com/activities/Math/g3/fractions-with-like-denominators
+ *
+ * // Grade-less course
+ * timeback.activity.start({
+ *   id: 'intro-to-loops',
+ *   name: 'Introduction to Loops',
+ *   course: { code: 'CS-101' },
+ * })
+ * // => object.id: https://sensor.example.com/activities/CS-101/intro-to-loops
+ * ```
  */
 export interface ActivityParams {
-    /** Unique identifier for the learning object */
+    /**
+     * Activity slug (stable identifier for the learning object).
+     *
+     * This is used to construct the canonical activity URL sent to Caliper.
+     * Use a short, URL-safe slug like `"fractions-with-like-denominators"` or
+     * `"lesson-1"`. Special characters will be URI-encoded.
+     *
+     * @example 'fractions-with-like-denominators'
+     * @example 'ccss.math.content.3.nf.a.1'
+     * @example 'lesson-1'
+     */
     id: string;
-    /** Display name of the activity */
+    /**
+     * Human-readable display name of the activity.
+     *
+     * This is sent as `object.activity.name` in Caliper events.
+     *
+     * @example 'Fractions with Like Denominators'
+     */
     name: string;
     /** Course selector (must match a unique course in timeback.config.ts) */
     course: ActivityCourseRef;
@@ -130,11 +213,21 @@ export interface ActivityMetrics {
 }
 /**
  * Activity state sent to the server when ending.
+ *
+ * @see {@link ActivityParams} for documentation on `id` and `name` semantics.
  */
 export interface ActivityEndPayload {
-    /** Unique identifier for the learning object */
+    /**
+     * Activity slug (stable identifier for the learning object).
+     *
+     * @see {@link ActivityParams.id}
+     */
     id: string;
-    /** Display name of the activity */
+    /**
+     * Human-readable display name of the activity.
+     *
+     * @see {@link ActivityParams.name}
+     */
     name: string;
     /** Course selector (must match a unique course in timeback.config.ts) */
     course: ActivityCourseRef;
@@ -148,6 +241,22 @@ export interface ActivityEndPayload {
     pausedMs: number;
     /** Activity metrics */
     metrics: ActivityMetrics;
+    /**
+     * Attempt number for this activity (1-based).
+     *
+     * If provided, this is forwarded to Caliper events as `generated.attempt`.
+     */
+    attemptNumber?: number;
+    /**
+     * App-reported course progress (per enrollment), as a percentage from 0–100.
+     *
+     * This is forwarded to Caliper events as `generated.extensions.pctCompleteApp`.
+     *
+     * @remarks
+     * - Scale: 0 to 100 (not 0 to 1)
+     * - Values outside 0–100 are clamped by the SDK server handler if present
+     */
+    pctCompleteApp?: number;
 }
 /**
  * Activity submission response.