@playcademy/sdk 0.2.2 → 0.2.4

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import * as _playcademy_timeback_types from '@playcademy/timeback/types';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
 /**
@@ -8,22 +7,146 @@ import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 declare class PlaycademyError extends Error {
     constructor(message: string);
 }
+/**
+ * Error codes returned by the API.
+ * These map to specific error types and HTTP status codes.
+ */
+type ApiErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'ACCESS_DENIED' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'ALREADY_EXISTS' | 'GONE' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_FAILED' | 'TOO_MANY_REQUESTS' | 'RATE_LIMITED' | 'EXPIRED' | 'INTERNAL' | 'INTERNAL_ERROR' | 'NOT_IMPLEMENTED' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | string;
+/**
+ * Structure of error response bodies returned by API endpoints.
+ *
+ * @example
+ * ```json
+ * {
+ *   "error": {
+ *     "code": "NOT_FOUND",
+ *     "message": "Item not found",
+ *     "details": { "identifier": "abc123" }
+ *   }
+ * }
+ * ```
+ */
+interface ErrorResponseBody {
+    error?: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/**
+ * API error thrown when a request fails.
+ *
+ * Contains structured error information from the API response:
+ * - `status` - HTTP status code (e.g., 404)
+ * - `code` - API error code (e.g., "NOT_FOUND")
+ * - `message` - Human-readable error message
+ * - `details` - Optional additional error context
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.games.get('nonexistent')
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.log(error.status)   // 404
+ *     console.log(error.code)     // "NOT_FOUND"
+ *     console.log(error.message)  // "Game not found"
+ *     console.log(error.details)  // { identifier: "nonexistent" }
+ *   }
+ * }
+ * ```
+ */
 declare class ApiError extends Error {
-    status: number;
-    details: unknown;
-    constructor(status: number, message: string, details: unknown);
+    readonly status: number;
+    /**
+     * API error code (e.g., "NOT_FOUND", "VALIDATION_FAILED").
+     * Use this for programmatic error handling.
+     */
+    readonly code: ApiErrorCode;
+    /**
+     * Additional error context from the API.
+     * Structure varies by error type (e.g., validation errors include field details).
+     */
+    readonly details: unknown;
+    /**
+     * Raw response body for debugging.
+     * @internal
+     */
+    readonly rawBody: unknown;
+    constructor(
+    /** HTTP status code */
+    status: number, 
+    /** API error code */
+    code: ApiErrorCode, 
+    /** Human-readable error message */
+    message: string, 
+    /** Additional error context */
+    details?: unknown, 
+    /** Raw response body */
+    rawBody?: unknown);
+    /**
+     * Create an ApiError from an HTTP response.
+     * Parses the structured error response from the API.
+     *
+     * @internal
+     */
+    static fromResponse(status: number, statusText: string, body: unknown): ApiError;
+    /**
+     * Check if this is a specific error type.
+     *
+     * @example
+     * ```typescript
+     * if (error.is('NOT_FOUND')) {
+     *   // Handle not found
+     * } else if (error.is('VALIDATION_FAILED')) {
+     *   // Handle validation error
+     * }
+     * ```
+     */
+    is(code: ApiErrorCode): boolean;
+    /**
+     * Check if this is a client error (4xx).
+     */
+    isClientError(): boolean;
+    /**
+     * Check if this is a server error (5xx).
+     */
+    isServerError(): boolean;
+    /**
+     * Check if this error is retryable.
+     * Server errors and rate limits are typically retryable.
+     */
+    isRetryable(): boolean;
 }
 /**
- * Extract useful error information from an API error
- * Useful for displaying errors to users in a friendly way
+ * Extracted error information for display purposes.
  */
 interface ApiErrorInfo {
+    /** HTTP status code */
     status: number;
-    statusText: string;
-    error?: string;
-    message?: string;
+    /** API error code */
+    code: ApiErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error context */
     details?: unknown;
 }
+/**
+ * Extract useful error information from an API error.
+ * Useful for displaying errors to users in a friendly way.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.shop.purchase(itemId)
+ * } catch (error) {
+ *   const info = extractApiErrorInfo(error)
+ *   if (info) {
+ *     showToast(`Error: ${info.message}`)
+ *   }
+ * }
+ * ```
+ */
 declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
 
 /**
@@ -255,217 +378,151 @@ declare function parseOAuthState(state: string): {
     data?: Record<string, string>;
 };
 
-declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "user";
-    schema: undefined;
-    columns: {
-        id: drizzle_orm_pg_core.PgColumn<{
-            name: "id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: true;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        name: drizzle_orm_pg_core.PgColumn<{
-            name: "name";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        username: drizzle_orm_pg_core.PgColumn<{
-            name: "username";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        email: drizzle_orm_pg_core.PgColumn<{
-            name: "email";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        timebackId: drizzle_orm_pg_core.PgColumn<{
-            name: "timeback_id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        emailVerified: drizzle_orm_pg_core.PgColumn<{
-            name: "email_verified";
-            tableName: "user";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        image: drizzle_orm_pg_core.PgColumn<{
-            name: "image";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        role: drizzle_orm_pg_core.PgColumn<{
-            name: "role";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "admin" | "player" | "developer";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["admin", "player", "developer"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        developerStatus: drizzle_orm_pg_core.PgColumn<{
-            name: "developer_status";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "none" | "pending" | "approved";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["none", "pending", "approved"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        characterCreated: drizzle_orm_pg_core.PgColumn<{
-            name: "character_created";
-            tableName: "user";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        createdAt: drizzle_orm_pg_core.PgColumn<{
-            name: "created_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        updatedAt: drizzle_orm_pg_core.PgColumn<{
-            name: "updated_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: "pg";
-}>;
+/** Permitted HTTP verbs */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * User Types
+ *
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ *
+ * @module types/user
+ */
+type UserRoleEnumType = 'admin' | 'player' | 'developer';
+type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+interface UserEnrollment {
+    gameId?: string;
+    courseId: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
+}
+interface UserOrganization {
+    id: string;
+    name: string | null;
+    type: TimebackOrgType | string;
+    isPrimary: boolean;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+interface UserTimebackData extends TimebackStudentProfile {
+    id: string;
+    enrollments: UserEnrollment[];
+}
+/**
+ * OpenID Connect UserInfo claims (NOT a database row).
+ */
+interface UserInfo {
+    sub: string;
+    email: string;
+    name: string | null;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    issuer?: string;
+    lti_roles?: unknown;
+    lti_context?: unknown;
+    lti_resource_link?: unknown;
+    timeback_id?: string;
+}
+/**
+ * Authenticated user for API responses.
+ * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ */
+interface AuthenticatedUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+    username: string | null;
+    role: UserRoleEnumType;
+    developerStatus: DeveloperStatusEnumType;
+    characterCreated: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    hasTimebackAccount: boolean;
+    timeback?: UserTimebackData;
+}
+
+/**
+ * Valid Caliper subject values.
+ * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
+ */
+type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+
+/**
+ * TimeBack Client SDK DTOs
+ *
+ * Data transfer objects for the TimeBack client SDK including
+ * progress tracking, session management, and activity completion.
+ *
+ * Note: TimebackClientConfig lives in @playcademy/timeback as it's
+ * SDK configuration, not a DTO.
+ *
+ * @module types/timeback/client
+ */
+
+/**
+ * Activity data for ending an activity
+ */
+interface ActivityData {
+    /** Unique activity identifier (required) */
+    activityId: string;
+    /** Grade level for this activity (required for multi-grade course routing) */
+    grade: number;
+    /** Subject area (required for multi-grade course routing) */
+    subject: CaliperSubject;
+    /** Activity display name (optional) */
+    activityName?: string;
+    /** Course identifier (auto-filled from config if not provided) */
+    courseId?: string;
+    /** Course display name (auto-filled from config if not provided) */
+    courseName?: string;
+    /** Student email address (optional) */
+    studentEmail?: string;
+    /** Application name for Caliper events (defaults to 'Game') */
+    appName?: string;
+    /** Sensor URL for Caliper events (defaults to baseUrl) */
+    sensorUrl?: string;
+}
+/**
+ * Score data with optional XP override for ending an activity
+ */
+interface EndActivityScoreData {
+    /** Number of questions answered correctly */
+    correctQuestions: number;
+    /** Total number of questions */
+    totalQuestions: number;
+    /** Optional XP override - bypasses automatic XP calculation */
+    xpAwarded?: number;
+    /** Number of learning units mastered */
+    masteredUnits?: number;
+}
+
+/**
+ * TimeBack API Request/Response Types
+ *
+ * Types for TimeBack API endpoints including XP tracking,
+ * setup, verification, and activity completion.
+ *
+ * @module types/timeback/api
+ */
+
+interface EndActivityResponse {
+    status: 'ok';
+    courseId: string;
+    xpAwarded: number;
+    masteredUnits?: number;
+    pctCompleteApp?: number;
+    scoreStatus?: string;
+    inProgress?: string;
+}
+
 declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "items";
     schema: undefined;
@@ -560,7 +617,7 @@ declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "items";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            data: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -735,108 +792,13 @@ declare const inventoryItems: drizzle_orm_pg_core.PgTableWithColumns<{
     };
     dialect: "pg";
 }>;
-type Item = typeof items.$inferSelect;
-type InventoryItem = typeof inventoryItems.$inferSelect;
 
-type User = typeof users.$inferSelect;
-/**
- * TimeBack enrollment information for a game.
- */
-type UserEnrollment = {
-    gameId?: string;
-    courseId: string;
-    grade: number;
-    subject: string;
-    orgId?: string;
-};
-/**
- * TimeBack user role (matches OneRoster spec).
- */
-type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
-/**
- * Organization type (matches OneRoster spec).
- */
-type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
-/**
- * TimeBack organization data for a user.
- * Represents schools, districts, or other educational organizations.
- */
-type UserOrganization = {
-    /** Organization ID (OneRoster sourcedId) */
-    id: string;
-    /** Organization name */
-    name: string | null;
-    /** Organization type (school, district, etc.) */
-    type: TimebackOrgType | string;
-    /** Whether this is the user's primary organization */
-    isPrimary: boolean;
-};
-/**
- * TimeBack student profile (role + organizations).
- * Subset of UserTimebackData returned by OneRoster API.
- */
-type TimebackStudentProfile = {
-    /** User's primary role in TimeBack (student, parent, teacher, etc.) */
-    role: TimebackUserRole;
-    /** User's organizations (schools/districts) */
-    organizations: UserOrganization[];
-};
-/**
- * TimeBack-related data for a user.
- */
-type UserTimebackData = TimebackStudentProfile & {
-    /** User's TimeBack ID (sourcedId) */
-    id: string;
-    /** Course enrollments */
-    enrollments: UserEnrollment[];
-};
-/**
- * User data with authentication provider information.
- * Returned by the /users/me endpoint with additional auth context.
- */
-type AuthenticatedUser = Omit<User, 'timebackId'> & {
-    /** Whether the user authenticated via Timeback SSO */
-    hasTimebackAccount: boolean;
-    /** TimeBack data (id, role, enrollments, organizations) - only present if user has a timeback account */
-    timeback?: UserTimebackData;
-};
-/**
- * Basic user information in the shape of the claims from identity providers
- */
-interface UserInfo {
-    /** Unique user identifier (sub claim from JWT) */
-    sub: string;
-    /** User's email address */
-    email: string;
-    /** User's display name */
-    name: string;
-    /** Whether the email has been verified */
-    email_verified: boolean;
-    /** Optional given name (first name) */
-    given_name?: string;
-    /** Optional family name (last name) */
-    family_name?: string;
-    /** TimeBack student ID (if user has TimeBack integration) */
-    timeback_id?: string;
-    /** Additional user attributes from the identity provider */
-    [key: string]: unknown;
-}
-type InventoryItemWithItem = Omit<InventoryItem, 'itemId'> & {
-    item: Item;
-};
-type EndActivityResponse = {
-    status: 'ok';
-    courseId: string;
-    xpAwarded: number;
-    masteredUnits?: number;
-    pctCompleteApp?: number;
-    scoreStatus?: string;
-    inProgress?: string;
+type ItemRow = typeof items.$inferSelect;
+type InventoryItemRow = typeof inventoryItems.$inferSelect;
+type InventoryItemWithItem = InventoryItemRow & {
+    item: ItemRow;
 };
 
-/** Permitted HTTP verbs */
-type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-
 /**
  * Auto-initializes a PlaycademyClient with context from the environment.
  * Works in both iframe mode (production/development) and standalone mode (local dev).
@@ -1036,9 +998,6 @@ declare abstract class PlaycademyBaseClient {
      * Initializes connection monitoring if enabled.
      */
     private _initializeConnectionMonitor;
-    /**
-     * Initializes an internal game session for automatic session management.
-     */
     private _initializeInternalSession;
     /**
      * Current user data and inventory management.
@@ -1082,8 +1041,8 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     runtime: {
         getGameToken: (gameId: string, options?: {
-            apply?: boolean;
-        }) => Promise<GameTokenResponse>;
+            apply?: boolean | undefined;
+        } | undefined) => Promise<GameTokenResponse>;
         exit: () => Promise<void>;
         onInit: (handler: (context: GameContextPayload) => void) => void;
         onTokenRefresh: (handler: (data: {
@@ -1107,7 +1066,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
         getListenerCounts: () => Record<string, number>;
         assets: {
             url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-            fetch: (path: string, options?: RequestInit) => Promise<Response>;
+            fetch: (path: string, options?: RequestInit | undefined) => Promise<Response>;
             json: <T = unknown>(path: string) => Promise<T>;
             blob: (path: string) => Promise<Blob>;
             text: (path: string) => Promise<string>;
@@ -1130,10 +1089,10 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     timeback: {
         readonly user: TimebackUser;
-        startActivity: (metadata: _playcademy_timeback_types.ActivityData) => void;
+        startActivity: (metadata: ActivityData) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
-        endActivity: (data: _playcademy_timeback_types.EndActivityScoreData) => Promise<EndActivityResponse>;
+        endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
     };
     /**
      * Playcademy Credits (platform currency) management.
@@ -1150,7 +1109,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `submit(gameId, score, metadata?)` - Record a game score
      */
     scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
+        submit: (gameId: string, score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
     };
     /**
      * Realtime multiplayer authentication.
@@ -1167,13 +1126,13 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
      */
     backend: {
-        get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
-        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
-        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
+        get<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
+        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
+        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
+        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
+        delete<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
+        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
+        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<Response>;
         url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
     };
     /** Auto-initializes a PlaycademyClient with context from the environment */
@@ -1189,8 +1148,8 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
 /**
  * Type definitions for the game timeback namespace.
  *
- * Re-exports core types from @playcademy/data for SDK consumers,
- * plus SDK-specific types like TimebackInitContext.
+ * SDK-specific types like TimebackInitContext that wrap the core types
+ * from @playcademy/types/user (which are re-exported via types/data.ts).
  */
 
 /**
@@ -1501,6 +1460,8 @@ type DevUploadEvent = {
 } | {
     type: 'finalizeStatus';
     message: string;
+} | {
+    type: 'complete';
 } | {
     type: 'close';
 };
@@ -2248,4 +2209,4 @@ declare class PlaycademyMessaging {
 declare const messaging: PlaycademyMessaging;
 
 export { ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
-export type { ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload };
+export type { ApiErrorCode, ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody };