timeback 0.1.1 → 0.1.3

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,5 +341,62 @@ 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.
+ *
+ * Use this when you only need SSO authentication without activity tracking
+ * or Timeback API integration.
+ */
+export interface IdentityOnlyConfig<TState = unknown> {
+    /** Environment */
+    env: Environment;
+    /** Identity configuration (SSO mode required for identity-only) */
+    identity: SsoIdentityConfig<TState, IdentityOnlyCallbackSuccessContext<TState>>;
+}
+/**
+ * Identity-only handlers.
+ */
+export interface IdentityOnlyHandlers {
+    /** Identity-related handlers */
+    identity: {
+        /** Initiate sign-in */
+        signIn: (req: Request) => Promise<Response>;
+        /** Handle OAuth callback */
+        callback: (req: Request) => Promise<Response>;
+        /** Sign out user */
+        signOut: () => Response;
+    };
+}
+/**
+ * Identity-only SDK instance.
+ *
+ * Returned by `createTimebackIdentity()` for SSO-only integrations.
+ */
+export interface IdentityOnlyInstance<TState = unknown> {
+    /** Configuration */
+    config: IdentityOnlyConfig<TState>;
+    /** Request handlers (identity only) */
+    handle: IdentityOnlyHandlers;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

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

@@ -11,17 +11,15 @@ export interface TimebackIdentity {
     email: string;
     name?: string;
 }
-/**
- * @deprecated Use TimebackIdentity instead
- */
-export type TimebackUser = TimebackIdentity;
 /**
  * Timeback user profile with enriched data from the Timeback API.
  */
 export interface TimebackProfile {
-    /** User identity */
+    /** Timeback user ID */
     id: string;
+    /** User's email address */
     email: string;
+    /** User's display name */
     name?: string;
     /** School information */
     school?: {
@@ -45,6 +43,52 @@ export interface TimebackProfile {
         dailyActiveMinutes?: number;
     };
 }
+/**
+ * Recommended minimal user payload to persist in a session.
+ *
+ * **User-facing note:** this type is part of the SDK’s developer experience.
+ * It exists to give you a “safe default” session shape that works well for
+ * cookie-based sessions (small payload) while still carrying enough Timeback
+ * context to power common UI affordances (e.g. showing a school name or grade).
+ *
+ * **What it is:** a minimal, serializable subset of `TimebackProfile`.
+ * **What it isn’t:** a guarantee that you’ll always have the full Timeback
+ * profile (courses, goals, xp, etc.) in-session. If you need richer data, fetch
+ * it from the API (e.g. `timeback.user.fetch()`) and cache/store it according
+ * to your app’s needs.
+ *
+ * **Stability:** this is still early and we’re actively iterating on identity
+ * and session ergonomics. We may rename, restructure, or remove this type from
+ * the public surface as the SDK evolves.
+ */
+export type TimebackSessionUser = Pick<TimebackProfile, 'id' | 'email' | 'name' | 'school' | 'grade'>;
+/**
+ * Claims from the identity provider (IdP).
+ *
+ * Normalized subset of OIDC UserInfo claims.
+ */
+export interface IdentityClaims {
+    /** Subject identifier (unique user ID from IdP) */
+    sub: string;
+    /** User's email address */
+    email: string;
+    /** User's first/given name */
+    firstName?: string;
+    /** User's last/family name */
+    lastName?: string;
+    /** User's profile picture URL */
+    pictureUrl?: string;
+}
+/**
+ * Authenticated user with Timeback profile and IdP claims.
+ *
+ * This is the primary user object returned during SSO callback when using
+ * `createTimeback()`. The `id` field is the canonical `timebackId` (stable identifier).
+ */
+export interface TimebackAuthUser extends TimebackProfile {
+    /** IdP claims (raw identity provider data) */
+    claims: IdentityClaims;
+}
 /**
  * Activity start parameters.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,yBAAyB;IACzB,MAAM,CAAC,EAAE;QACR,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;KACZ,CAAA;IAED,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,4BAA4B;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAA;IAEX,uBAAuB;IACvB,OAAO,CAAC,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACZ,CAAC,CAAA;IAEF,yBAAyB;IACzB,KAAK,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAC3B,CAAA;CACD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAA;IACV,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAA;IACV,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAA;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAA;IACjB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAA;IAChB,uBAAuB;IACvB,OAAO,EAAE,eAAe,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "timeback",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Timeback SDK for frontend and backend integration",
 	"type": "module",
 	"exports": {
@@ -12,6 +12,14 @@
 			"types": "./dist/client.d.ts",
 			"import": "./dist/client.js"
 		},
+		"./identity": {
+			"types": "./dist/identity.d.ts",
+			"import": "./dist/identity.js"
+		},
+		"./edge": {
+			"types": "./dist/edge.d.ts",
+			"import": "./dist/edge.js"
+		},
 		"./react": {
 			"types": "./dist/client/adapters/react/index.d.ts",
 			"import": "./dist/client/adapters/react/index.js"
@@ -69,6 +77,7 @@
 		"test": "bun test --no-env-file unit.test.ts"
 	},
 	"dependencies": {
+		"@timeback/core": "0.1.1",
 		"jiti": "^2.6.1",
 		"zod": "^4.2.1"
 	},

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

@@ -1,24 +0,0 @@
-/**
- * Identity Handlers
- *
- * Route handlers for SSO identity operations.
- * User session state is managed by your own auth system via the hooks.
- */
-import type { Environment, IdentityConfig } from '../types';
-interface IdentityHandlerParams {
-    env: Environment;
-    identity: IdentityConfig;
-}
-/**
-* Create identity route handlers.
- *
-* @param params - Handler configuration
-* @returns Identity handlers
-*/
-export declare function createIdentityHandlers(params: IdentityHandlerParams): {
-    signIn: (req: Request) => Promise<Response>;
-    callback: (req: Request) => Promise<Response>;
-    signOut: () => Response;
-};
-export {};
-//# sourceMappingURL=identity.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,OAAO,KAAK,EAGX,WAAW,EACX,cAAc,EAEd,MAAM,UAAU,CAAA;AAEjB,UAAU,qBAAqB;IAC9B,GAAG,EAAE,WAAW,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;CACxB;AAqPA;;;;;EAKE;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB;;;;EAQnE"}