@timeback/sdk 0.1.9 → 0.1.10

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

@@ -3,23 +3,50 @@
  *
  * Feature-local types for the activity submission flow.
  */
+import type { ActivityCompletedEvent, TimebackActivityContext } from '@timeback/caliper';
+import type { TimebackClient } from '@timeback/core';
 import type { ActivityCourseRef } from '../../../shared/types';
 import type { ApiCredentials, AppConfig, Environment, IdentityConfig, TimebackConfig } from '../../types';
+import type { maybeWriteCompletionEntry } from './completion';
+import type { computeProgress } from './progress';
 /** User identity info needed for activity submission. */
 export interface ActivityUserInfo {
     email: string;
     /** Timeback ID if already resolved (SSO mode). When present, skip lookup. */
     timebackId?: string;
 }
-/** Validated activity payload ready for submission. */
-export interface ValidatedActivityPayload {
+/** Validated completion payload for activity submission. */
+export interface CompletionPayload {
     id: string;
     name: string;
     course: ActivityCourseRef;
+    endedAt: string;
+    metrics: {
+        totalQuestions?: number;
+        correctQuestions?: number;
+        xpEarned?: number;
+        masteredUnits?: number;
+    };
+    pctComplete?: number;
+}
+/** Validated heartbeat payload for time-spent tracking. */
+export interface ValidatedHeartbeatPayload {
+    id: string;
+    name: string;
+    course: ActivityCourseRef;
+    runId: string;
     startedAt: string;
     endedAt: string;
     elapsedMs: number;
     pausedMs: number;
+}
+/** Validated submit payload for activity completion. */
+export interface ValidatedSubmitPayload {
+    id: string;
+    name: string;
+    course: ActivityCourseRef;
+    runId: string;
+    endedAt: string;
     metrics: {
         totalQuestions?: number;
         correctQuestions?: number;
@@ -28,10 +55,20 @@ export interface ValidatedActivityPayload {
     };
     pctComplete?: number;
 }
-/** Result of request validation - either valid data or an error response. */
-export type ValidationResult = {
+/** Result of heartbeat validation. */
+export type HeartbeatValidationResult = {
     ok: true;
-    payload: ValidatedActivityPayload;
+    payload: ValidatedHeartbeatPayload;
+    course: AppConfig['courses'][number];
+    sensor: string;
+} | {
+    ok: false;
+    response: Response;
+};
+/** Result of submit validation. */
+export type SubmitValidationResult = {
+    ok: true;
+    payload: ValidatedSubmitPayload;
     course: AppConfig['courses'][number];
     sensor: string;
 } | {
@@ -44,8 +81,92 @@ export interface ActivityHandlerConfig {
     identity: IdentityConfig;
     appConfig: AppConfig;
     api: ApiCredentials;
+    getClient: () => TimebackClient;
     hooks?: TimebackConfig['hooks'];
 }
 /** Activity handler type. */
 export type ActivityHandler = (req: Request) => Promise<Response>;
+/**
+ * Configuration for activity completion recording.
+ */
+export interface CompletionConfig {
+    /** Environment (local, staging, production) */
+    env: Environment;
+    /** API credentials */
+    api: ApiCredentials;
+    /** App configuration */
+    appConfig: AppConfig;
+    /** Get the shared Timeback API client. */
+    getClient: () => TimebackClient;
+    /** Optional hooks */
+    hooks?: TimebackConfig['hooks'];
+}
+/**
+ * Options for recording an activity completion.
+ */
+export interface CompletionOptions {
+    /** User info (email + optional timebackId) */
+    userInfo: ActivityUserInfo;
+    /** Validated completion payload */
+    payload: CompletionPayload;
+    /** Resolved course from config */
+    course: AppConfig['courses'][number];
+    /** Resolved sensor URL */
+    sensor: string;
+    /** Whether to skip sending (preview mode) */
+    preview?: boolean;
+    /** Optional correlation ID linking to client-side heartbeats */
+    runId?: string;
+}
+/**
+ * Result of recording an activity completion.
+ */
+export interface CompletionResult {
+    success: true;
+    preview?: boolean;
+    sensor?: string;
+    actor?: {
+        id: string;
+        type: 'TimebackUser';
+        email: string;
+    };
+    object?: TimebackActivityContext;
+    event?: ActivityCompletedEvent;
+}
+/**
+ * Options for sending a time-spent event.
+ */
+export interface TimeSpentOptions {
+    /** User info (email + optional timebackId) */
+    userInfo: ActivityUserInfo;
+    /** Time-spent payload */
+    payload: {
+        id: string;
+        name: string;
+        course: ActivityCourseRef;
+        startedAt: string;
+        endedAt: string;
+        elapsedMs: number;
+        pausedMs: number;
+    };
+    /** Resolved course from config */
+    course: AppConfig['courses'][number];
+    /** Resolved sensor URL */
+    sensor: string;
+    /** Correlation ID linking to client-side heartbeats */
+    runId?: string;
+}
+/**
+ * Internal dependencies for activity completion.
+ *
+ * This interface enables unit tests to inject mock implementations of
+ * computeProgress and maybeWriteCompletionEntry without mocking the entire
+ * TimebackClient.
+ *
+ * Not part of the public API - only exposed for testing purposes.
+ */
+export interface CompletionDeps {
+    computeProgress: typeof computeProgress;
+    maybeWriteCompletionEntry: typeof maybeWriteCompletionEntry;
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/activity/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EACX,cAAc,EACd,SAAS,EACT,WAAW,EACX,cAAc,EACd,cAAc,EACd,MAAM,aAAa,CAAA;AAMpB,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD,uDAAuD;AACvD,MAAM,WAAW,wBAAwB;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,iBAAiB,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,aAAa,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;IACD,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAMD,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GACzB;IACA,EAAE,EAAE,IAAI,CAAA;IACR,OAAO,EAAE,wBAAwB,CAAA;IACjC,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;IACpC,MAAM,EAAE,MAAM,CAAA;CACb,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAA;AAMpC,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACrC,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,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/activity/types.ts"],"names":[],"mappings":"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"}

package/dist/server/handlers/identity/handler.d.ts

@@ -3,12 +3,31 @@
  *
  * This module includes Timeback user resolution and therefore depends on Timeback API access.
  */
-import type { IdentityHandlerParams, IdentityHandlers } from './types';
+import type { IdentityHandlerParams } from './types';
 /**
- * Create identity route handlers (full SDK).
+ * Create the sign-in handler.
+ *
+ * Initiates the OIDC sign-in flow by redirecting to the identity provider.
+ *
+ * @param params - Handler configuration
+ * @returns Sign-in request handler
+ */
+export declare function createSignInHandler<TState = unknown>(params: IdentityHandlerParams<TState>): (req: Request) => Promise<Response>;
+/**
+ * Create the OIDC callback handler.
+ *
+ * Exchanges the authorization code for tokens and resolves the Timeback user.
  *
  * @param params - Handler configuration
- * @returns Identity handlers
+ * @returns Callback request handler
+ */
+export declare function createCallbackHandler<TState = unknown>(params: IdentityHandlerParams<TState>): (req: Request) => Promise<Response>;
+/**
+ * Create a sign-out handler.
+ *
+ * Returns a redirect to the root path.
+ *
+ * @returns Sign-out handler
  */
-export declare function createIdentityHandlers<TState = unknown>(params: IdentityHandlerParams<TState>): IdentityHandlers;
+export declare function createSignOutHandler(): () => Response;
 //# sourceMappingURL=handler.d.ts.map

package/dist/server/handlers/identity/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/identity/handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAEtE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAG,OAAO,EACtD,MAAM,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACnC,gBAAgB,CAQlB"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/identity/handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAG,OAAO,EACnD,MAAM,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACnC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAGrC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,GAAG,OAAO,EACrD,MAAM,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACnC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAGrC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,QAAQ,CAErD"}

package/dist/server/handlers/identity/index.d.ts

@@ -3,6 +3,6 @@
  *
  * Route handlers for SSO authentication with Timeback user resolution.
  */
-export { createIdentityHandlers } from './handler';
-export type { IdentityHandlerParams, IdentityHandlers } from './types';
+export { createSignInHandler, createCallbackHandler, createSignOutHandler } from './handler';
+export type { IdentityHandlerParams } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/handlers/identity/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/identity/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAClD,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/identity/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAC5F,YAAY,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA"}

package/dist/server/handlers/identity/oidc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/identity/oidc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,OAAO,KAAK,EAA0B,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAMpD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,MAAM,EACxC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,CAcnB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAC5C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,EAClD,GAAG,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GACvC,OAAO,CAAC,QAAQ,CAAC,CA0DnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAC1C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,EAChC,GAAG,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GACvC,OAAO,CAAC,QAAQ,CAAC,CAiBnB"}
+{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/identity/oidc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH,OAAO,KAAK,EAA0B,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAMpD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,MAAM,EACxC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,CAcnB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAC5C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,EAClD,GAAG,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GACvC,OAAO,CAAC,QAAQ,CAAC,CA8DnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAC1C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,EAChC,GAAG,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GACvC,OAAO,CAAC,QAAQ,CAAC,CAiBnB"}

package/dist/server/handlers/identity/types.d.ts

@@ -14,11 +14,5 @@ export interface IdentityHandlerParams<TState = unknown> {
         getClient: () => TimebackClient;
     };
 }
-/** Identity handlers returned by createIdentityHandlers. */
-export interface IdentityHandlers {
-    signIn: (req: Request) => Promise<Response>;
-    callback: (req: Request) => Promise<Response>;
-    signOut: () => Response;
-}
 export type { CallbackErrorContext, CallbackSuccessContext, Environment, IdentityConfig, SsoIdentityConfig, };
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/identity/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EACX,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,MAAM,aAAa,CAAA;AAEpB,sDAAsD;AACtD,MAAM,WAAW,qBAAqB,CAAC,MAAM,GAAG,OAAO;IACtD,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;IAChC,GAAG,EAAE;QACJ,WAAW,EAAE,cAAc,CAAA;QAC3B,SAAS,EAAE,MAAM,cAAc,CAAA;KAC/B,CAAA;CACD;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC3C,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC7C,OAAO,EAAE,MAAM,QAAQ,CAAA;CACvB;AAGD,YAAY,EACX,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,cAAc,EACd,iBAAiB,GACjB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/identity/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EACX,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,MAAM,aAAa,CAAA;AAEpB,sDAAsD;AACtD,MAAM,WAAW,qBAAqB,CAAC,MAAM,GAAG,OAAO;IACtD,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;IAChC,GAAG,EAAE;QACJ,WAAW,EAAE,cAAc,CAAA;QAC3B,SAAS,EAAE,MAAM,cAAc,CAAA;KAC/B,CAAA;CACD;AAGD,YAAY,EACX,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,cAAc,EACd,iBAAiB,GACjB,CAAA"}

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

@@ -3,10 +3,10 @@
  *
  * Route handlers for Timeback server operations.
  */
-export { createActivityHandler } from './activity';
-export { createIdentityHandlers } from './identity';
+export { createHeartbeatHandler, createSubmitHandler } from './activity';
+export { createSignInHandler, createCallbackHandler, createSignOutHandler } from './identity';
 export { createUserHandler, createUserVerifyHandler } from './user';
 export type { ActivityHandler, ActivityHandlerConfig } from './activity';
-export type { IdentityHandlerParams, IdentityHandlers } from './identity';
+export type { IdentityHandlerParams } from './identity';
 export type { UserHandler, UserHandlerConfig, UserVerifyHandler, UserVerifyHandlerConfig } from './user';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAA;AAEnE,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AACxE,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACzE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAC7F,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAA;AAEnE,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AACvD,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/user/handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AA6C7D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAiDxE"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/user/handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AA8C7D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAwCxE"}

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

@@ -1 +1 @@
-{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/user/profile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAQ5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,SAAS,GAAG,YAAY,GAC9B,OAAO,CAAC,eAAe,CAAC,CAoC1B"}
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/user/profile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,SAAS,GAAG,YAAY,GAC9B,OAAO,CAAC,eAAe,CAAC,CAoC1B"}

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

@@ -3,6 +3,7 @@
  *
  * Feature-local types for the user profile handler.
  */
+import type { TimebackClient } from '@timeback/core';
 import type { ApiCredentials, AppConfig, Environment, IdentityConfig } from '../../types';
 /** Configuration for the user handler. */
 export interface UserHandlerConfig {
@@ -10,6 +11,7 @@ export interface UserHandlerConfig {
     identity: IdentityConfig;
     api: ApiCredentials;
     appConfig: AppConfig;
+    getClient: () => TimebackClient;
 }
 /** User handler type. */
 export type UserHandler = (req: Request) => Promise<Response>;
@@ -18,6 +20,7 @@ export interface UserVerifyHandlerConfig {
     env: Environment;
     identity: IdentityConfig;
     api: ApiCredentials;
+    getClient: () => TimebackClient;
 }
 /** User verify handler type. */
 export type UserVerifyHandler = (req: Request) => Promise<Response>;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/user/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEzF,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,EAAE,SAAS,CAAA;CACpB;AAED,yBAAyB;AACzB,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE7D,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACvC,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,GAAG,EAAE,cAAc,CAAA;CACnB;AAED,gCAAgC;AAChC,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEnE,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/user/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEzF,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,EAAE,SAAS,CAAA;IACpB,SAAS,EAAE,MAAM,cAAc,CAAA;CAC/B;AAED,yBAAyB;AACzB,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE7D,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACvC,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,EAAE,MAAM,cAAc,CAAA;CAC/B;AAED,gCAAgC;AAChC,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEnE,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;CACd"}

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

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/user/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AA0BzE;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,uBAAuB,GAAG,iBAAiB,CA0D1F"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/user/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AA0BzE;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,uBAAuB,GAAG,iBAAiB,CA+C1F"}

package/dist/server/index.d.ts

@@ -5,5 +5,5 @@
  */
 export { createTimeback } from './timeback';
 export { createTimebackIdentity } from './timeback-identity';
-export type { TimebackConfig, TimebackInstance, Environment, EnvironmentInput, ApiCredentials, IdentityConfig, SsoIdentityConfig, CustomIdentityConfig, Handlers, IdentityOnlyConfig, IdentityOnlyInstance, IdentityOnlyHandlers, BuildStateContext, CallbackSuccessContext, IdentityOnlyCallbackSuccessContext, CallbackErrorContext, OIDCTokens, OIDCUserInfo, IdpData, TimebackUserResolutionErrorCode, } from './types';
+export type { TimebackConfig, TimebackInstance, Environment, EnvironmentInput, ApiCredentials, IdentityConfig, SsoIdentityConfig, CustomIdentityConfig, Handlers, ActivityRecordInput, ActivityRecordUserInput, ActivityRecordActivityInput, ActivityRecordMetricsInput, ActivityRecordTimeInput, ActivityNamespace, UserNamespace, IdentityOnlyConfig, IdentityOnlyInstance, IdentityOnlyHandlers, BuildStateContext, CallbackSuccessContext, IdentityOnlyCallbackSuccessContext, CallbackErrorContext, OIDCTokens, OIDCUserInfo, IdpData, ActivityBeforeSendData, TimeSpentBeforeSendData, HandlerName, RequestStartContext, RequestEndContext, TimebackUserResolutionErrorCode, ErrorCode, SdkError, SdkErrorBody, SdkLogger, SdkLogLevel, } from './types';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,YAAY,EAEX,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,QAAQ,EAER,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EAEpB,iBAAiB,EACjB,sBAAsB,EACtB,kCAAkC,EAClC,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,OAAO,EAEP,+BAA+B,GAC/B,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,YAAY,EAEX,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,QAAQ,EAER,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,0BAA0B,EAC1B,uBAAuB,EACvB,iBAAiB,EAEjB,aAAa,EAEb,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EAEpB,iBAAiB,EACjB,sBAAsB,EACtB,kCAAkC,EAClC,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,OAAO,EAEP,sBAAsB,EACtB,uBAAuB,EAEvB,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EAEjB,+BAA+B,EAC/B,SAAS,EACT,QAAQ,EACR,YAAY,EAEZ,SAAS,EACT,WAAW,GACX,MAAM,SAAS,CAAA"}

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

@@ -0,0 +1,20 @@
+/**
+ * Request Lifecycle Hook Utilities
+ *
+ * Wraps request handlers with optional `onRequestStart` / `onRequestEnd` hooks
+ * for timing, tracing, and metrics.
+ */
+import type { HandlerName, TimebackConfig } from '../types';
+/**
+ * Wrap a request handler with lifecycle hooks.
+ *
+ * When neither `onRequestStart` nor `onRequestEnd` is configured the original
+ * handler is returned as-is (zero overhead).
+ *
+ * @param handler - Handler name for identification
+ * @param hooks - Hook configuration
+ * @param fn - The request handler to wrap
+ * @returns Wrapped handler
+ */
+export declare function withRequestHooks(handler: HandlerName, hooks: TimebackConfig['hooks'], fn: (req: Request) => Promise<Response>): (req: Request) => Promise<Response>;
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/server/lib/hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAE3D;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,EAC9B,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GACrC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAyBrC"}

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

@@ -4,8 +4,10 @@
  * Shared utilities for the server SDK.
  */
 export { getIssuer, buildAuthorizationUrl, exchangeCodeForTokens, getUserInfo } from './oidc';
-export { deriveCourseStructureIds, jsonResponse, redirectResponse, encodeBase64Url, decodeBase64Url, mapEnvForApi, normalizeEnv, safeIdSegment, sameInstant, hashSuffix64Base36, sha256Hex, } from './utils';
-export { ssoLog, oidcLog, createScopedLogger } from './logger';
+export { deriveCourseStructureIds, jsonResponse, errorResponse, redirectResponse, encodeBase64Url, decodeBase64Url, mapEnvForApi, normalizeEnv, safeIdSegment, sameInstant, hashSuffix64Base36, sha256Hex, } from './utils';
+export { ssoLog, oidcLog, createScopedLogger, configureSdkLogging, resetSdkLogging } from './logger';
 export { lookupTimebackIdByEmail, resolveStatusForUserResolutionError, resolveTimebackUserByEmail, TimebackUserResolutionError, } from './resolve';
 export { buildErrorContext, computeRedirectUri, handleIdpError, handleMissingCode, initiateSignIn, parseCallback, tryDecodeState, } from './sso';
+export { refineQuestionMetrics, resolveSensor } from './validation';
+export { withRequestHooks } from './hooks';
 //# 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,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,GACT,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC9D,OAAO,EACN,uBAAuB,EACvB,mCAAmC,EACnC,0BAA0B,EAC1B,2BAA2B,GAC3B,MAAM,WAAW,CAAA;AAClB,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,GACd,MAAM,OAAO,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,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,GACT,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACpG,OAAO,EACN,uBAAuB,EACvB,mCAAmC,EACnC,0BAA0B,EAC1B,2BAA2B,GAC3B,MAAM,WAAW,CAAA;AAClB,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,GACd,MAAM,OAAO,CAAA;AACd,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA"}

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

@@ -1,21 +1,48 @@
 /**
  * SDK Logger
  *
- * Debug logging for the Timeback SDK server components.
- * Only logs when DEBUG=1 or DEBUG=true is set.
+ * Configurable logging for the Timeback SDK server components.
+ *
+ * All handler modules create loggers at import time:
+ *
+ *   const log = createScopedLogger('handlers:user')
+ *
+ * These loggers are lazy proxies — each call resolves the effective
+ * logger at invocation time, so module-level loggers automatically
+ * pick up configuration set later in `createTimeback()`.
+ */
+import type { SdkLogger, SdkLogLevel } from '../types';
+/**
+ * Configure SDK-wide logging.
+ *
+ * Called by `createTimeback()` during initialization. Clears the logger cache
+ * so all existing proxies pick up the new configuration on their next call.
+ *
+ * @param options - Logger and level overrides
+ */
+export declare function configureSdkLogging(options: {
+    logger?: SdkLogger;
+    logLevel?: SdkLogLevel;
+}): void;
+/**
+ * Reset SDK logging to defaults.
+ *
+ * Intended for tests that need isolation between runs.
  */
-import type { Logger } from '@timeback/internal-logger';
+export declare function resetSdkLogging(): void;
 /**
  * Create a scoped logger for SDK components.
  *
- * Only logs debug/info when DEBUG=1 or DEBUG=true.
+ * Returns a lazy proxy — each log call resolves the effective logger
+ * at invocation time. This allows module-level loggers to pick up
+ * configuration set after import.
  *
- * @param scope - Logger scope name (e.g., 'sso', 'oidc')
- * @returns Configured logger instance
+ * @param scope - Logger scope name (e.g., 'handlers:user', 'resolve')
+ * @returns Logger proxy scoped to `timeback:{scope}`
  */
-export declare function createScopedLogger(scope: string): Logger;
+export declare function createScopedLogger(scope: string): SdkLogger;
 /** Logger for SSO/identity operations */
-export declare const ssoLog: Logger;
+export declare const ssoLog: SdkLogger;
 /** Logger for OIDC protocol operations */
-export declare const oidcLog: Logger;
+export declare const oidcLog: SdkLogger;
 //# sourceMappingURL=logger.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/server/lib/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AAgBvD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,yCAAyC;AACzC,eAAO,MAAM,MAAM,QAA4B,CAAA;AAE/C,0CAA0C;AAC1C,eAAO,MAAM,OAAO,QAA6B,CAAA"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/server/lib/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAgGtD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,IAAI,CAIjG;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAiB3D;AAED,yCAAyC;AACzC,eAAO,MAAM,MAAM,WAA4B,CAAA;AAE/C,0CAA0C;AAC1C,eAAO,MAAM,OAAO,WAA6B,CAAA"}

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

@@ -26,7 +26,7 @@ export declare class TimebackUserResolutionError extends Error {
  * 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)
+ * @returns HTTP status code (409 for ambiguous, 404 for not found, 502 otherwise)
  */
 export declare function resolveStatusForUserResolutionError(err: TimebackUserResolutionError): number;
 interface ResolveTimebackUserByEmailParams {

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

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/server/lib/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAM/C,OAAO,KAAK,EAAkB,gBAAgB,EAAmB,MAAM,oBAAoB,CAAA;AAC3F,OAAO,KAAK,EACX,cAAc,EACd,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"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/server/lib/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAM/C,OAAO,KAAK,EAAkB,gBAAgB,EAAmB,MAAM,oBAAoB,CAAA;AAC3F,OAAO,KAAK,EACX,cAAc,EACd,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,CAS5F;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"}

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

@@ -3,7 +3,7 @@
  *
  * Internal utility functions for the server SDK.
  */
-import type { Environment, EnvironmentInput } from '../types';
+import type { Environment, EnvironmentInput, ErrorCode } from '../types';
 /**
  * Derived resource IDs for a course structure.
  */
@@ -118,6 +118,24 @@ export declare function normalizeEnv(env: EnvironmentInput): Environment;
  * @returns JSON response
  */
 export declare function jsonResponse<T>(data: T, status?: number, headers?: HeadersInit): Response;
+/**
+ * Create a JSON error response with the standard SDK error shape.
+ *
+ * All error responses include `success: false` and a structured `error`
+ * object with a machine-readable `code` and human-readable `message`.
+ *
+ * @param code - Machine-readable error code
+ * @param message - Human-readable error message
+ * @param status - HTTP status code
+ * @param options - Additional fields
+ * @returns HTTP Response
+ */
+export declare function errorResponse(code: ErrorCode, message: string, status: number, options?: {
+    /** Additional top-level fields merged into the body (e.g., `{ verified: false }`). */
+    fields?: Record<string, unknown>;
+    /** Validation details included in the error object. */
+    details?: unknown;
+}): Response;
 /**
  * Create a redirect response.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/server/lib/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAM7D;;GAEG;AACH,UAAU,kBAAkB;IAC3B,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAO7E;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAcxD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,YAAY,CAMvE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,WAAW,CAK/D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,SAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAItF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAI7E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAKrD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/server/lib/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAMxE;;GAEG;AACH,UAAU,kBAAkB;IAC3B,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAO7E;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAcxD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,YAAY,CAMvE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,WAAW,CAK/D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,SAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAItF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACT,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB,GACC,QAAQ,CAQV;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAI7E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAKrD"}

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

@@ -0,0 +1,55 @@
+/**
+ * Shared Validation Utilities
+ *
+ * Common validation logic used across server schemas.
+ */
+import type * as z from 'zod';
+import type { AppConfig, Environment } from '../types';
+/**
+ * Refine question metrics to ensure consistency.
+ *
+ * Validation rules:
+ * - `totalQuestions` and `correctQuestions` must be provided together (both or neither)
+ * - `correctQuestions` cannot exceed `totalQuestions`
+ *
+ * @param metrics - The metrics object containing optional question counts
+ * @param ctx - Zod refinement context for adding validation issues
+ *
+ * @example
+ * ```ts
+ * const metricsSchema = z.object({
+ *   totalQuestions: z.number().int().nonnegative().optional(),
+ *   correctQuestions: z.number().int().nonnegative().optional(),
+ * }).superRefine(refineQuestionMetrics)
+ * ```
+ */
+export declare function refineQuestionMetrics(metrics: {
+    totalQuestions?: number;
+    correctQuestions?: number;
+}, ctx: z.RefinementCtx): void;
+/**
+ * Resolve the effective sensor URL for a course.
+ *
+ * The sensor URL identifies where Caliper events should be sent.
+ *
+ * Resolution order:
+ * 1. Environment-specific sensor override: `course.overrides[env].sensor`
+ * 2. Course-level sensor: `course.sensor`
+ * 3. App-level sensor: `appConfig.sensor`
+ * 4. Derived from launchUrl origin (if available)
+ *
+ * @param appConfig - App configuration from timeback.config.json
+ * @param course - Resolved course from config
+ * @param env - Environment (local/staging/production)
+ * @returns The resolved sensor URL, or undefined if none could be determined
+ *
+ * @example
+ * ```ts
+ * const sensor = resolveSensor(appConfig, course, env)
+ * if (!sensor) {
+ *   throw new Error('No sensor configured for course')
+ * }
+ * ```
+ */
+export declare function resolveSensor(appConfig: AppConfig, course: AppConfig['courses'][number], env: Environment): string | undefined;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/server/lib/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,CAAA;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/D,GAAG,EAAE,CAAC,CAAC,aAAa,GAClB,IAAI,CAuBN;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC5B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EACpC,GAAG,EAAE,WAAW,GACd,MAAM,GAAG,SAAS,CAqBpB"}

package/dist/server/namespaces/activity/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Activity Record
+ *
+ * Server-side activity recording API.
+ */
+export { createActivityRecord, ActivityRecordValidationError, ActivityRecordCourseError, } from './record';
+export { activityRecordInputSchema } from './schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/namespaces/activity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/namespaces/activity/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,oBAAoB,EACpB,6BAA6B,EAC7B,yBAAyB,GACzB,MAAM,UAAU,CAAA;AAEjB,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAA"}