timeback 0.1.2 → 0.1.3

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

@@ -9,6 +9,48 @@ import type { AnyTimebackInput } from './types';
  * Union of handler types returned by getHandlers.
  */
 type AnyHandlers = Handlers | IdentityOnlyHandlers;
+/**
+ * A canonical route identifier for Timeback's built-in endpoints.
+ */
+type TimebackRouteId = 'identity.signIn' | 'identity.callback' | 'identity.signOut' | 'user.me' | 'activity';
+/**
+ * Normalize a path-like string to a pathname only (no query string).
+ *
+ * Some frameworks may provide path-like values that include a query string
+ * (e.g. `/api/timeback/identity/signin?returnTo=/`). Route matching should
+ * operate on pathnames only.
+ *
+ * @param path - Path-like string (may include query string)
+ * @returns Pathname only (no query string)
+ */
+export declare function normalizePathname(path: string): string;
+/**
+ * Attempt to map a request to a Timeback built-in route.
+ *
+ * This consolidates route matching logic so adapters don't each re-implement
+ * their own `endsWith(...)` chains.
+ *
+ * Matching strategy:
+ * - If `callbackPath` is provided and equals the request pathname, treat it as
+ *   the identity callback route (GET only).
+ * - If `basePath` is provided, match *exactly* against `basePath + ROUTES.*`
+ *   by stripping the base path and comparing the relative path.
+ * - If `basePath` is not provided, fall back to suffix matching (`endsWith`)
+ *   to support catch-all mounts where the mount prefix isn't known.
+ *
+ * @param params - Matching inputs
+ * @param params.pathname - Request pathname (may include query string; will be normalized)
+ * @param params.method - HTTP method
+ * @param params.basePath - Optional base path (recommended when available)
+ * @param params.callbackPath - Optional custom callback path
+ * @returns A matched route id, or null if not a Timeback route
+ */
+export declare function matchTimebackRoute(params: {
+    pathname: string;
+    method: string;
+    basePath?: string;
+    callbackPath?: string;
+}): TimebackRouteId | null;
 /**
  * Extract handlers from flexible input.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;GAEG;AACH,KAAK,WAAW,GAAG,QAAQ,GAAG,oBAAoB,CAAA;AAElD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,QAAQ,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,QAAQ,CAE1E"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;GAEG;AACH,KAAK,WAAW,GAAG,QAAQ,GAAG,oBAAoB,CAAA;AAElD;;GAEG;AACH,KAAK,eAAe,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,kBAAkB,GAClB,SAAS,GACT,UAAU,CAAA;AAEb;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBtD;AA8BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,eAAe,GAAG,IAAI,CAsDzB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,QAAQ,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,QAAQ,CAE1E"}

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

@@ -11,7 +11,7 @@ interface ActivityHandlerConfig {
     env: Environment;
     identity: IdentityConfig;
     appConfig: AppConfig;
-    apiCredentials: ApiCredentials;
+    api: ApiCredentials;
 }
 /**
  * Activity handler type.

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;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAkCtF;;GAEG;AACH,UAAU,qBAAqB;IAC9B,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,SAAS,EAAE,SAAS,CAAA;IACpB,cAAc,EAAE,cAAc,CAAA;CAC9B;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,CAuCpF"}
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/activity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAkCtF;;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,CAuCpF"}

package/dist/server/handlers/identity-full.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Identity Handlers (full SDK)
+ *
+ * This module includes Timeback user resolution and therefore depends on Timeback API access.
+ */
+import type { TimebackClient } from '@timeback/core';
+import type { ApiCredentials, Environment, IdentityConfig } from '../types';
+type FullIdentityHandlerParams<TState = unknown> = {
+    env: Environment;
+    identity: IdentityConfig<TState>;
+    api: {
+        credentials: ApiCredentials;
+        getClient: () => TimebackClient;
+    };
+};
+/**
+ * Create identity route handlers (full SDK).
+ *
+ * @param params - Handler configuration
+ * @returns Identity handlers
+ */
+export declare function createIdentityHandlers<TState = unknown>(params: FullIdentityHandlerParams<TState>): {
+    signIn: (req: Request) => Promise<Response>;
+    callback: (req: Request) => Promise<Response>;
+    signOut: () => Response;
+};
+export {};
+//# sourceMappingURL=identity-full.d.ts.map

package/dist/server/handlers/identity-full.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-full.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/identity-full.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EACX,cAAc,EAGd,WAAW,EACX,cAAc,EAEd,MAAM,UAAU,CAAA;AAEjB,KAAK,yBAAyB,CAAC,MAAM,GAAG,OAAO,IAAI;IAClD,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,CAAA;AAwQD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAG,OAAO,EACtD,MAAM,EAAE,yBAAyB,CAAC,MAAM,CAAC,GACvC;IACF,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,CAQA"}

package/dist/server/handlers/identity-only.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Identity Handlers (identity-only)
+ *
+ * This module is intentionally minimal and does NOT import Timeback API client code.
+ * It is safe to include in edge runtimes (e.g. Cloudflare Workers / workerd).
+ */
+import type { Environment, IdentityOnlyCallbackSuccessContext, SsoIdentityConfig } from '../types';
+/**
+ * Create identity route handlers (identity-only mode).
+ *
+ * @param params - Handler configuration
+ * @returns Identity-only handlers
+ */
+export declare function createIdentityOnlyHandlers<TState = unknown>(params: {
+    env: Environment;
+    identity: SsoIdentityConfig<TState, IdentityOnlyCallbackSuccessContext<TState>>;
+}): {
+    signIn: (req: Request) => Promise<Response>;
+    callback: (req: Request) => Promise<Response>;
+    signOut: () => Response;
+};
+//# sourceMappingURL=identity-only.d.ts.map

package/dist/server/handlers/identity-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-only.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/identity-only.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAEX,WAAW,EACX,kCAAkC,EAClC,iBAAiB,EACjB,MAAM,UAAU,CAAA;AAuPjB;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,EAAE;IACpE,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,iBAAiB,CAAC,MAAM,EAAE,kCAAkC,CAAC,MAAM,CAAC,CAAC,CAAA;CAC/E;;;;EAYA"}

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

@@ -3,7 +3,7 @@
  *
  * Route handlers for Timeback server operations.
  */
-export { createIdentityHandlers } from './identity';
+export { createIdentityHandlers } from './identity-full';
 export { createActivityHandler } from './activity';
 export { createUserHandler } 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,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,iBAAiB,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,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA"}

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

@@ -10,7 +10,7 @@ import type { ApiCredentials, Environment, IdentityConfig } from '../types';
 interface UserHandlerConfig {
     env: Environment;
     identity: IdentityConfig;
-    apiCredentials: ApiCredentials;
+    api: ApiCredentials;
 }
 /**
  * User handler type.

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;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAE3E;;GAEG;AACH,UAAU,iBAAiB;IAC1B,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,cAAc,EAAE,cAAc,CAAA;CAC9B;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,CA4BxE"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/user.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAE3E;;GAEG;AACH,UAAU,iBAAiB;IAC1B,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,GAAG,EAAE,cAAc,CAAA;CACnB;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,CA4BxE"}

package/dist/server/index.d.ts

@@ -3,8 +3,7 @@
  *
  * Server-side exports for the Timeback SDK.
  */
-export { createServer, createIdentityServer } from './timeback';
-export type { TimebackConfig, TimebackInstance, Environment, ApiCredentials, IdentityConfig, SsoIdentityConfig, CustomIdentityConfig, Handlers, IdentityOnlyConfig, IdentityOnlyInstance, IdentityOnlyHandlers, BuildStateContext, CallbackSuccessContext, CallbackErrorContext, OIDCTokens, OIDCUserInfo, } from './types';
-export type { CallbackSuccessContext as IdentityCallbackSuccess } from './types';
-export type { CallbackErrorContext as IdentityCallbackError } from './types';
+export { createTimeback } from './timeback';
+export { createTimebackIdentity } from './timeback-identity';
+export type { TimebackConfig, TimebackInstance, Environment, ApiCredentials, IdentityConfig, SsoIdentityConfig, CustomIdentityConfig, Handlers, IdentityOnlyConfig, IdentityOnlyInstance, IdentityOnlyHandlers, BuildStateContext, CallbackSuccessContext, IdentityOnlyCallbackSuccessContext, CallbackErrorContext, OIDCTokens, OIDCUserInfo, IdpData, TimebackUserResolutionErrorCode, } 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,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAC/D,YAAY,EAEX,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,QAAQ,EAER,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EAEpB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,UAAU,EACV,YAAY,GACZ,MAAM,SAAS,CAAA;AAEhB,YAAY,EAAE,sBAAsB,IAAI,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAChF,YAAY,EAAE,oBAAoB,IAAI,qBAAqB,EAAE,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,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"}

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

@@ -4,6 +4,7 @@
  * Internal utilities for the server SDK.
  */
 export { getIssuer, buildAuthorizationUrl, exchangeCodeForTokens, getUserInfo } from './oidc';
-export { jsonResponse, redirectResponse, encodeBase64Url, decodeBase64Url } from './utils';
+export { jsonResponse, redirectResponse, encodeBase64Url, decodeBase64Url, mapEnvForApi, } from './utils';
 export { ssoLog, oidcLog, createScopedLogger } from './logger';
+export { resolveTimebackUserByEmail, TimebackUserResolutionError } from './resolve-timeback-user';
 //# 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,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC1F,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,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,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/server/lib/resolve-timeback-user.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Timeback User Resolution
+ *
+ * Resolves the Timeback user by email using server credentials.
+ */
+import { TimebackClient } from '@timeback/core';
+import type { TimebackAuthUser } from '../../shared/types';
+import type { ApiCredentials, 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);
+}
+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 to use (e.g. `timeback.api`).
+     *
+     * When provided, this function will use it and will NOT close it.
+     */
+    client?: TimebackClient;
+}
+/**
+ * Resolve a TimebackAuthUser by looking up the Timeback user via email.
+ *
+ * Uses server API credentials to query OneRoster for a user matching the IdP email.
+ * Strict mode: fails if no user found or if multiple users match (ambiguous).
+ *
+ * @param params - Resolution parameters
+ * @returns Resolved TimebackAuthUser with Timeback profile and IdP claims
+ * @throws {TimebackUserResolutionError} If resolution fails
+ */
+export declare function resolveTimebackUserByEmail(params: ResolveTimebackUserByEmailParams): Promise<TimebackAuthUser>;
+export {};
+//# sourceMappingURL=resolve-timeback-user.d.ts.map

package/dist/server/lib/resolve-timeback-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-timeback-user.d.ts","sourceRoot":"","sources":["../../../src/server/lib/resolve-timeback-user.ts"],"names":[],"mappings":"AAAA;;;;GAIG;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;AAIjB;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;aAGpC,IAAI,EAAE,+BAA+B;IAFtD,YACC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,+BAA+B,EAIrD;CACD;AAED,UAAU,gCAAgC;IACzC,uCAAuC;IACvC,GAAG,EAAE,WAAW,CAAA;IAChB,uCAAuC;IACvC,cAAc,EAAE,cAAc,CAAA;IAC9B,kCAAkC;IAClC,QAAQ,EAAE,YAAY,CAAA;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAA;CACvB;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC/C,MAAM,EAAE,gCAAgC,GACtC,OAAO,CAAC,gBAAgB,CAAC,CAiG3B"}

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

@@ -3,6 +3,21 @@
  *
  * Internal utility functions for the server SDK.
  */
+import type { Environment } from '../types';
+/**
+ * Map SDK environment to the environment used for outbound Timeback API calls.
+ *
+ * The SDK's `env` config controls runtime mode, but for outbound service calls
+ * (OneRoster, Caliper, etc.) we need a real Timeback environment:
+ *
+ *   - `local`      → `staging` (local dev uses staging services)
+ *   - `staging`    → `staging`
+ *   - `production` → `production`
+ *
+ * @param env - SDK environment setting
+ * @returns Environment to use for TimebackClient
+ */
+export declare function mapEnvForApi(env: Environment): 'staging' | 'production';
 /**
  * Create a JSON 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;AAEH;;;;;;;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;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,YAAY,CAMvE;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"}

package/dist/server/timeback-identity.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Timeback Server SDK (Identity-only)
+ *
+ * This file is intentionally Node-free so it can be used in edge runtimes
+ * (e.g. Cloudflare Workers / workerd) without pulling in Node-only deps
+ * like `jiti`, `fs`, etc.
+ */
+import type { IdentityOnlyConfig, IdentityOnlyInstance } from './types';
+/**
+ * Create an identity-only Timeback server instance.
+ *
+ * Use this when you only need SSO authentication without activity tracking
+ * or Timeback API integration. Does not require `timeback.config.ts`.
+ *
+ * @param config - Identity-only configuration
+ * @returns Identity-only Timeback server instance
+ */
+export declare function createTimebackIdentity<TState = unknown>(config: IdentityOnlyConfig<TState>): IdentityOnlyInstance<TState>;
+//# sourceMappingURL=timeback-identity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeback-identity.d.ts","sourceRoot":"","sources":["../../src/server/timeback-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAG,OAAO,EACtD,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAChC,oBAAoB,CAAC,MAAM,CAAC,CAY9B"}

package/dist/server/timeback.d.ts

@@ -3,83 +3,66 @@
  *
  * Factory functions to create Timeback server instances.
  */
-import type { IdentityOnlyConfig, IdentityOnlyInstance, TimebackConfig, TimebackInstance } from './types';
+import type { TimebackConfig, TimebackInstance } from './types';
 /**
  * Create a Timeback server instance.
  *
  * Returns a framework-agnostic instance with raw handlers.
+ *
  * Use an adapter to integrate with your framework:
  * - `toNextjsHandler()` for Next.js App Router
  * - `toHonoApp()` / `toHonoMiddleware()` for Hono
  * - `toExpressMiddleware()` / `mountExpressRoutes()` for Express
  *
+ * When using SSO mode, the callback receives an enriched `TimebackAuthUser` with
+ * `user.id` being the canonical Timeback user ID (timebackId).
+ *
  * @param config - Server configuration
  * @returns Timeback instance with handlers
  *
- * @example
+ * @example SSO mode
  * ```typescript
- * import { createServer } from 'timeback'
+ * import { createTimeback } from 'timeback'
  * import { toNextjsHandler } from 'timeback/nextjs'
  *
- * const timeback = await createServer({
+ * const timeback = await createTimeback({
  *   env: 'production',
  *   api: {
  *     clientId: process.env.TIMEBACK_API_CLIENT_ID!,
  *     clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
  *   },
  *   identity: {
- *     mode: 'custom',
- *     getUser: async (req) => {
- *       const session = await getSession(req)
- *       return {
- *         id: session.userId,
- *         email: session.user.email,
- *         name: session.user.name,
- *       }
+ *     mode: 'sso',
+ *     clientId: process.env.AWS_COGNITO_CLIENT_ID!,
+ *     clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
+ *     onCallbackSuccess: async ({ user, state, redirect }) => {
+ *       // user.id is the timebackId (canonical stable identifier)
+ *       await setSession({ id: user.id, email: user.email })
+ *       return redirect(state.returnTo ?? '/')
  *     },
+ *     onCallbackError: ({ error, redirect }) => redirect('/?error=sso_failed'),
+ *     getUser: (req) => getSessionUser(req),
  *   },
  * })
  *
  * // For Next.js App Router
  * export const { GET, POST } = toNextjsHandler(timeback)
  * ```
- */
-export declare function createServer(config: TimebackConfig): Promise<TimebackInstance>;
-/**
- * Create an identity-only Timeback server instance.
- *
- * Use this when you only need SSO authentication without activity tracking
- * or Timeback API integration. Does not require `timeback.config.ts`.
- *
- * @param config - Identity-only configuration
- * @returns Identity-only instance with SSO handlers
  *
- * @example
+ * @example Custom identity mode (bring your own auth)
  * ```typescript
- * import { createIdentityServer } from 'timeback'
- * import { toNextjsHandler } from 'timeback/nextjs'
- *
- * const timeback = createIdentityServer({
+ * const timeback = await createTimeback({
  *   env: 'production',
+ *   api: { ... },
  *   identity: {
- *     mode: 'sso',
- *     clientId: process.env.AWS_COGNITO_CLIENT_ID!,
- *     clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
- *     onCallbackSuccess: ({ user, redirect }) => {
- *       // Set session, then redirect
- *       return redirect('/')
- *     },
- *     onCallbackError: ({ error, redirect }) => {
- *       console.error('SSO Error:', error)
- *       return redirect('/?error=sso_failed')
+ *     mode: 'custom',
+ *     getUser: async (req) => {
+ *       const session = await getSession(req)
+ *       return session ? { id: session.userId, email: session.email } : undefined
  *     },
- *     getUser: (req) => getSession(req),
  *   },
  * })
- *
- * // For Next.js App Router
- * export const { GET, POST } = toNextjsHandler(timeback)
  * ```
  */
-export declare function createIdentityServer<TState = unknown>(config: IdentityOnlyConfig<TState>): IdentityOnlyInstance<TState>;
+export declare function createTimeback<TState = unknown>(config: TimebackConfig<TState>): Promise<TimebackInstance<TState>>;
 //# sourceMappingURL=timeback.d.ts.map

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;AAMH,OAAO,KAAK,EAEX,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwCpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,GAAG,OAAO,EACpD,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAChC,oBAAoB,CAAC,MAAM,CAAC,CAY9B"}
+{"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,CAgEnC"}

package/dist/server/types.d.ts

@@ -3,11 +3,16 @@
  *
  * Configuration and internal types for the server SDK.
  */
-import type { TimebackUser } from '../shared/types';
+import type { TimebackClient } from '@timeback/core';
+import type { TimebackAuthUser, TimebackIdentity } from '../shared/types';
 /**
  * Environment configuration.
  */
 export type Environment = 'local' | 'staging' | 'production';
+/**
+ * Error codes for Timeback user resolution failures.
+ */
+export type TimebackUserResolutionErrorCode = 'missing_email' | 'timeback_user_not_found' | 'timeback_user_ambiguous' | 'timeback_user_lookup_failed';
 /**
  * API credentials for Timeback API calls.
  */
@@ -82,15 +87,48 @@ export interface BuildStateContext {
     url: URL;
 }
 /**
- * Context passed to onCallbackSuccess hook.
+ * Raw identity provider data (tokens and user info claims).
+ */
+export interface IdpData {
+    /** OIDC tokens from the identity provider */
+    tokens: OIDCTokens;
+    /** User info claims from the identity provider */
+    userInfo: OIDCUserInfo;
+}
+/**
+ * Context passed to onCallbackSuccess hook for full SDK (createTimeback).
+ *
+ * When using `createTimeback()` with SSO mode, the `user` field contains the
+ * enriched `TimebackAuthUser` with `timebackId` as the canonical identifier. Raw IdP
+ * data is available under `idp`.
  */
 export interface CallbackSuccessContext<TState = unknown> {
+    /** Authenticated user with Timeback profile and IdP claims */
+    user: TimebackAuthUser;
+    /** Raw identity provider data (tokens and user info) */
+    idp: IdpData;
+    /** State data from buildState (if provided) */
+    state: TState | undefined;
+    /** The incoming callback request */
+    req: Request;
+    /** Helper to create a redirect response */
+    redirect: (url: string, headers?: HeadersInit) => Response;
+    /** Helper to create a JSON response */
+    json: <T>(data: T, status?: number, headers?: HeadersInit) => Response;
+}
+/**
+ * Context passed to onCallbackSuccess hook for identity-only SDK (createTimebackIdentity).
+ *
+ * When using `createTimebackIdentity()`, the `user` field contains raw OIDC user info
+ * claims (no Timeback profile enrichment).
+ */
+export interface IdentityOnlyCallbackSuccessContext<TState = unknown> {
     /** OIDC tokens from the identity provider */
     tokens: OIDCTokens;
     /** User info claims from the identity provider */
     user: OIDCUserInfo;
     /** State data from buildState (if provided) */
-    state: TState;
+    state: TState | undefined;
     /** The incoming callback request */
     req: Request;
     /** Helper to create a redirect response */
@@ -116,11 +154,9 @@ export interface CallbackErrorContext<TState = unknown> {
     json: <T>(data: T, status?: number, headers?: HeadersInit) => Response;
 }
 /**
- * SSO identity configuration.
- *
- * Provides full control over the OIDC flow without managing user sessions.
+ * Base SSO identity configuration fields (shared between full and identity-only).
  */
-export interface SsoIdentityConfig<TState = unknown> {
+interface BaseSsoIdentityConfig<TState = unknown> {
     mode: 'sso';
     /** OIDC client ID */
     clientId: string;
@@ -163,29 +199,6 @@ export interface SsoIdentityConfig<TState = unknown> {
      * ```
      */
     buildState?: (ctx: BuildStateContext) => TState;
-    /**
-     * Called after successful OIDC authentication.
-     *
-     * Use this to:
-     * 1. Upsert the user in your database
-     * 2. Set your own session cookie
-     * 3. Redirect to the appropriate page
-     *
-     * @param ctx - Context with tokens, user info, state, and helpers
-     * @returns Response (typically a redirect)
-     *
-     * @example
-     * ```typescript
-     * onCallbackSuccess: async ({ user, state, redirect }) => {
-     *   await db.user.upsert({ where: { email: user.email }, ... })
-     *   const session = await createSession(user)
-     *   return redirect(state.returnTo ?? '/', {
-     *     'Set-Cookie': `session=${session.id}; HttpOnly; Path=/`,
-     *   })
-     * }
-     * ```
-     */
-    onCallbackSuccess: (ctx: CallbackSuccessContext<TState>) => Promise<Response> | Response;
     /**
      * Called when OIDC authentication fails.
      *
@@ -200,7 +213,7 @@ export interface SsoIdentityConfig<TState = unknown> {
      * }
      * ```
      */
-    onCallbackError?: (ctx: CallbackErrorContext<TState>) => Promise<Response> | Response;
+    onCallbackError?(ctx: CallbackErrorContext<TState>): Promise<Response> | Response;
     /**
      * Get the current user from the request.
      *
@@ -223,7 +236,39 @@ export interface SsoIdentityConfig<TState = unknown> {
      * getUser: (req) => currentUser
      * ```
      */
-    getUser: (req: Request) => Promise<TimebackUser | undefined> | TimebackUser | undefined;
+    getUser(req: Request): Promise<TimebackIdentity | undefined> | TimebackIdentity | undefined;
+}
+/**
+ * SSO identity configuration for full SDK (createTimeback).
+ *
+ * When using `createTimeback()`, the SSO callback provides an enriched `TimebackAuthUser`
+ * with `timebackId` as the canonical identifier. The SDK resolves the Timeback
+ * user by email using server API credentials.
+ */
+export interface SsoIdentityConfig<TState = unknown, TSuccessContext = CallbackSuccessContext<TState>> extends BaseSsoIdentityConfig<TState> {
+    /**
+     * Called after successful OIDC authentication and Timeback user resolution.
+     *
+     * The `user` field contains the enriched `TimebackAuthUser` with:
+     * - `id`: Timeback user ID (canonical stable identifier)
+     * - `email`, `name`: User profile data
+     * - `claims`: Raw IdP claims (sub, firstName, lastName, pictureUrl)
+     *
+     * Raw IdP data (tokens, userInfo) is available under `idp`.
+     *
+     * @param ctx - Context with enriched user, IdP data, state, and helpers
+     * @returns Response (typically a redirect)
+     *
+     * @example
+     * ```typescript
+     * onCallbackSuccess: async ({ user, state, redirect }) => {
+     *   // user.id is the timebackId (canonical identifier)
+     *   await setSession({ id: user.id, email: user.email })
+     *   return redirect(state.returnTo ?? '/')
+     * }
+     * ```
+     */
+    onCallbackSuccess(ctx: TSuccessContext): Promise<Response> | Response;
 }
 /**
  * Custom identity configuration.
@@ -241,7 +286,7 @@ export interface CustomIdentityConfig {
      * @param req - The incoming request
      * @returns User object or undefined (sync or async)
      */
-    getUser: (req: Request) => Promise<TimebackUser | undefined> | TimebackUser | undefined;
+    getUser(req: Request): Promise<TimebackIdentity | undefined> | TimebackIdentity | undefined;
 }
 /**
  * Identity configuration (SSO or custom).
@@ -296,6 +341,25 @@ export interface TimebackInstance<TState = unknown> {
     config: TimebackConfig<TState>;
     /** Request handlers */
     handle: Handlers;
+    /**
+     * Direct access to the Timeback API client.
+     *
+     * This is an escape hatch for advanced use cases that need to call Timeback
+     * services (OneRoster, Edubridge, Caliper, QTI) beyond what the SDK handlers
+     * provide. The client is created lazily on first access.
+     *
+     * Note: For `env: 'local'`, outbound API calls use `staging` environment.
+     *
+     * @example
+     * ```typescript
+     * // List users from OneRoster
+     * const { data: users } = await timeback.api.oneroster.users.list({ limit: 10 })
+     *
+     * // Send a Caliper event
+     * await timeback.api.caliper.emit(event)
+     * ```
+     */
+    api: TimebackClient;
 }
 /**
  * Identity-only configuration.
@@ -307,7 +371,7 @@ export interface IdentityOnlyConfig<TState = unknown> {
     /** Environment */
     env: Environment;
     /** Identity configuration (SSO mode required for identity-only) */
-    identity: SsoIdentityConfig<TState>;
+    identity: SsoIdentityConfig<TState, IdentityOnlyCallbackSuccessContext<TState>>;
 }
 /**
  * Identity-only handlers.
@@ -326,7 +390,7 @@ export interface IdentityOnlyHandlers {
 /**
  * Identity-only SDK instance.
  *
- * Returned by `createIdentityServer()` for SSO-only integrations.
+ * Returned by `createTimebackIdentity()` for SSO-only integrations.
  */
 export interface IdentityOnlyInstance<TState = unknown> {
     /** Configuration */
@@ -334,4 +398,5 @@ export interface IdentityOnlyInstance<TState = unknown> {
     /** Request handlers (identity only) */
     handle: IdentityOnlyHandlers;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map