@playcademy/sdk 0.0.8 → 0.1.0

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import * as _playcademy_realtime_server_types from '@playcademy/realtime/server/types';
+import { InferSelectModel } from 'drizzle-orm';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import * as drizzle_zod from 'drizzle-zod';
 import { z } from 'zod';
+import { OrganizationConfig, CourseConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
 
 declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "user";
@@ -1848,8 +1850,402 @@ declare const playerCharacterAccessories: drizzle_orm_pg_core.PgTableWithColumns
     };
     dialect: "pg";
 }>;
+declare const gameTimebackIntegrations: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "game_timeback_integrations";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "game_timeback_integrations";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        gameId: drizzle_orm_pg_core.PgColumn<{
+            name: "game_id";
+            tableName: "game_timeback_integrations";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        courseId: drizzle_orm_pg_core.PgColumn<{
+            name: "course_id";
+            tableName: "game_timeback_integrations";
+            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;
+        }, {}, {}>;
+        lastVerifiedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "last_verified_at";
+            tableName: "game_timeback_integrations";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "game_timeback_integrations";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "game_timeback_integrations";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 
-declare const achievementIntervalEnum: drizzle_orm_pg_core.PgEnum<["daily", "weekly"]>;
+declare const achievementScopeEnum: drizzle_orm_pg_core.PgEnum<["daily", "weekly", "monthly", "yearly", "game", "global", "map", "level", "event"]>;
+declare const notifications: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "notifications";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "notifications";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: drizzle_orm_pg_core.PgColumn<{
+            name: "user_id";
+            tableName: "notifications";
+            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;
+        }, {}, {}>;
+        type: drizzle_orm_pg_core.PgColumn<{
+            name: "type";
+            tableName: "notifications";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 50;
+        }>;
+        title: drizzle_orm_pg_core.PgColumn<{
+            name: "title";
+            tableName: "notifications";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 255;
+        }>;
+        message: drizzle_orm_pg_core.PgColumn<{
+            name: "message";
+            tableName: "notifications";
+            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;
+        }, {}, {}>;
+        data: drizzle_orm_pg_core.PgColumn<{
+            name: "data";
+            tableName: "notifications";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        priority: drizzle_orm_pg_core.PgColumn<{
+            name: "priority";
+            tableName: "notifications";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "low" | "normal" | "high" | "urgent";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["low", "normal", "high", "urgent"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: drizzle_orm_pg_core.PgColumn<{
+            name: "status";
+            tableName: "notifications";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "pending" | "delivered" | "seen" | "clicked" | "dismissed" | "expired";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["pending", "delivered", "seen", "clicked", "dismissed", "expired"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "notifications";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deliveredAt: drizzle_orm_pg_core.PgColumn<{
+            name: "delivered_at";
+            tableName: "notifications";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        seenAt: drizzle_orm_pg_core.PgColumn<{
+            name: "seen_at";
+            tableName: "notifications";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        clickedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "clicked_at";
+            tableName: "notifications";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        expiresAt: drizzle_orm_pg_core.PgColumn<{
+            name: "expires_at";
+            tableName: "notifications";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        method: drizzle_orm_pg_core.PgColumn<{
+            name: "method";
+            tableName: "notifications";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 50;
+        }>;
+        clickUrl: drizzle_orm_pg_core.PgColumn<{
+            name: "click_url";
+            tableName: "notifications";
+            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;
+        }, {}, {}>;
+        metadata: drizzle_orm_pg_core.PgColumn<{
+            name: "metadata";
+            tableName: "notifications";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 declare const DeveloperStatusResponseSchema: z.ZodObject<{
     status: z.ZodEnum<["none", "pending", "approved"]>;
 }, "strip", z.ZodTypeAny, {
@@ -2247,11 +2643,82 @@ declare const UpdateShopListingSchema: z.ZodObject<{
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
 }>;
+
+declare enum AchievementCompletionType {
+    TIME_PLAYED_SESSION = "time_played_session",
+    INTERACTION = "interaction",
+    LEADERBOARD_RANK = "leaderboard_rank",
+    FIRST_SCORE = "first_score",
+    PERSONAL_BEST = "personal_best"
+}
+type AchievementScopeType = (typeof achievementScopeEnum.enumValues)[number];
 /**
- * Achievement Completion Types
+ * Current-scope achievement with computed status and window metadata
  */
-declare const ACHIEVEMENT_COMPLETION_TYPES: readonly ["time_played_session", "interaction", "leaderboard_rank"];
-type AchievementCompletionType = (typeof ACHIEVEMENT_COMPLETION_TYPES)[number];
+interface AchievementCurrent {
+    id: string;
+    title: string;
+    description?: string | null;
+    scope: AchievementScopeType;
+    rewardCredits: number;
+    limit: number;
+    completionType: AchievementCompletionType;
+    completionConfig: Record<string, unknown>;
+    target: Record<string, unknown>;
+    active: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+    status: 'available' | 'completed';
+    scopeKey: string;
+    windowStart: string;
+    windowEnd: string;
+}
+/**
+ * Achievement claim history entry
+ * Used in GET /api/achievements/history
+ */
+interface AchievementHistoryEntry {
+    achievementId: string;
+    title: string;
+    rewardCredits: number;
+    createdAt: string;
+    scopeKey: string;
+}
+/**
+ * Achievement progress submission response
+ * Used in POST /api/achievements/progress
+ */
+interface AchievementProgressResponse {
+    achievementId: string;
+    status: 'completed' | 'already_completed';
+    rewardCredits: number;
+    scopeKey: string;
+    createdAt: string;
+}
+
+declare enum NotificationType {
+    ACHIEVEMENT = "achievement",
+    SYSTEM = "system",
+    PROMO = "promo"
+}
+declare enum NotificationStatus {
+    PENDING = "pending",
+    DELIVERED = "delivered",
+    SEEN = "seen",
+    CLICKED = "clicked",
+    DISMISSED = "dismissed",
+    EXPIRED = "expired"
+}
+type Notification = InferSelectModel<typeof notifications>;
+interface NotificationStats {
+    total: number;
+    delivered: number;
+    seen: number;
+    clicked: number;
+    dismissed: number;
+    expired: number;
+    clickThroughRate: number;
+}
 
 type CharacterComponent = typeof characterComponents.$inferSelect;
 type PlayerCharacter = typeof playerCharacters.$inferSelect & {
@@ -2273,6 +2740,17 @@ type ExternalGame = BaseGame & {
 type Game = HostedGame | ExternalGame;
 type GameStateData = Record<string, unknown>;
 type UpsertGameMetadataInput = z.infer<typeof UpsertGameMetadataSchema>;
+/**
+ * Response from backend deployment API
+ */
+interface BackendDeploymentResponse {
+    /** Unique deployment ID */
+    deploymentId: string;
+    /** Backend API URL */
+    url: string;
+    /** Deployment timestamp */
+    deployedAt: string;
+}
 type Item = typeof items.$inferSelect;
 type InventoryItem = typeof inventoryItems.$inferSelect;
 type ShopListing = typeof shopListings.$inferSelect;
@@ -2341,6 +2819,8 @@ interface UserInfo {
     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;
 }
@@ -2527,6 +3007,7 @@ interface SpriteTemplateData {
         };
     };
 }
+type GameTimebackIntegration = typeof gameTimebackIntegrations.$inferSelect;
 type TodayXpResponse = {
     xp: number;
     date: string;
@@ -2540,49 +3021,158 @@ type XpHistoryResponse = {
         xp: number;
     }>;
 };
-
-type AchievementIntervalType = (typeof achievementIntervalEnum.enumValues)[number];
-/**
- * Current-interval achievement with computed status and window metadata
- */
-interface AchievementCurrent {
-    id: string;
-    title: string;
-    description?: string | null;
-    intervalType: AchievementIntervalType;
-    rewardCredits: number;
-    limitPerInterval: number;
-    completionType: AchievementCompletionType;
-    completionConfig: Record<string, unknown>;
-    scope: Record<string, unknown>;
-    active: boolean;
-    createdAt?: Date;
-    updatedAt?: Date;
-    status: 'available' | 'completed';
-    intervalKey: string;
-    windowStart: string;
-    windowEnd: string;
-}
-/**
- * Historical entry representing a prior claim within an interval
- */
-interface AchievementHistoryEntry {
-    achievementId: string;
-    title: string;
-    rewardCredits: number;
-    createdAt: string;
-    intervalKey: string;
-}
-/**
- * Response returned when submitting achievement progress
- */
-interface AchievementProgressResponse {
-    achievementId: string;
-    status: 'completed' | 'already_completed';
-    rewardCredits: number;
-    intervalKey: string;
-    createdAt: string;
-}
+type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+type TimebackSetupRequest = {
+    gameId: string;
+    config: {
+        organization: {
+            name: string;
+            type: string;
+            identifier: string;
+        };
+        course: {
+            title: string;
+            subjects: string[];
+            grades: number[];
+            courseCode: string;
+            level: string;
+            gradingScheme: string;
+            metadata?: Record<string, unknown>;
+        };
+        component: {
+            title: string;
+            sortOrder: number;
+            prerequisites: string[];
+            prerequisiteCriteria: string;
+        };
+        resource: {
+            title: string;
+            vendorResourceId: string;
+            vendorId: string;
+            applicationId: string;
+            roles: string[];
+            importance: string;
+            metadata: {
+                type?: string;
+                launchUrl?: string;
+                toolProvider?: string;
+                instructionalMethod?: string;
+                subject?: string;
+                grades?: number[];
+                language?: string;
+                xp?: number;
+                [key: string]: unknown;
+            };
+        };
+        componentResource: {
+            title: string;
+            sortOrder: number;
+            lessonType: string | null;
+        };
+    };
+    verbose?: boolean;
+};
+type TimebackSetupResponse = {
+    integration: GameTimebackIntegration;
+    courseId: string;
+    verbose?: {
+        course: unknown;
+        component: unknown;
+        resource: unknown;
+        componentResource: unknown;
+    };
+};
+type TimebackVerifyResponse = {
+    status: 'success' | 'error';
+    integration: GameTimebackIntegration;
+    resources: {
+        course: {
+            found: boolean;
+            data?: unknown;
+        };
+        component: {
+            found: boolean;
+            data?: unknown;
+        };
+        resource: {
+            found: boolean;
+            data?: unknown;
+        };
+        componentResource: {
+            found: boolean;
+            data?: unknown;
+        };
+    };
+    errors?: string[];
+};
+type RecordProgressRequest = {
+    gameId: string;
+    studentId: string;
+    progressData: {
+        sensorUrl?: string;
+        subject?: TimebackSubject;
+        appName?: string;
+        score?: number;
+        totalQuestions?: number;
+        correctQuestions?: number;
+        xpEarned?: number;
+        masteredUnits?: number;
+        attemptNumber?: number;
+        activityId?: string;
+        activityName?: string;
+        courseId?: string;
+        classId?: string;
+        courseName?: string;
+        studentEmail?: string;
+    };
+};
+type RecordProgressResponse = {
+    status: 'ok';
+    courseId: string;
+};
+type RecordSessionEndRequest = {
+    gameId: string;
+    studentId: string;
+    sessionData: {
+        sensorUrl?: string;
+        subject?: TimebackSubject;
+        appName?: string;
+        activeTimeSeconds: number;
+        inactiveTimeSeconds?: number;
+        wasteTimeSeconds?: number;
+        activityId?: string;
+        activityName?: string;
+        courseId?: string;
+        courseName?: string;
+        studentEmail?: string;
+    };
+};
+type RecordSessionEndResponse = {
+    status: 'ok';
+    courseId: string;
+};
+type AwardXpRequest = {
+    gameId: string;
+    studentId: string;
+    xpAmount: number;
+    metadata: {
+        sensorUrl: string;
+        subject: TimebackSubject;
+        appName: string;
+        reason: string;
+        activityId?: string;
+        activityName?: string;
+        courseId?: string;
+        courseName?: string;
+        studentEmail?: string;
+        bonusType?: string;
+    };
+};
+type AwardXpResponse = {
+    status: 'ok';
+    courseId: string;
+    xpAwarded: number;
+};
 
 /**
  * SDK Constants
@@ -2602,9 +3192,81 @@ declare const AuthProvider: {
     readonly TIMEBACK: "TIMEBACK";
 };
 
+/**
+ * @fileoverview Server SDK Type Definitions
+ *
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
+ */
+
+/**
+ * TimeBack integration configuration for Playcademy config file
+ */
+interface TimebackIntegrationConfig {
+    /** Organization overrides */
+    organization?: Partial<OrganizationConfig>;
+    /** Course configuration (subjects and grades REQUIRED) */
+    course: CourseConfig;
+    /** Component overrides */
+    component?: Partial<ComponentConfig>;
+    /** Resource overrides */
+    resource?: Partial<ResourceConfig>;
+    /** Component-Resource link overrides */
+    componentResource?: Partial<ComponentResourceConfig>;
+}
+/**
+ * Integrations configuration
+ */
+interface IntegrationsConfig {
+    /** TimeBack integration (optional) */
+    timeback?: TimebackIntegrationConfig;
+}
+/**
+ * Unified Playcademy configuration
+ * Used for playcademy.config.{js,json}
+ */
+interface PlaycademyConfig {
+    /** Game name */
+    name: string;
+    /** Game description */
+    description?: string;
+    /** Game emoji icon */
+    emoji?: string;
+    /** Build command to run before deployment */
+    buildCommand?: string[];
+    /** Path to build output */
+    buildPath?: string;
+    /** Game type */
+    gameType?: 'hosted' | 'external';
+    /** External URL (for external games) */
+    externalUrl?: string;
+    /** Game platform */
+    platform?: 'web' | 'unity' | 'godot';
+    /** Backend configuration */
+    backend?: {
+        /** Custom API routes directory (defaults to 'api') */
+        directory?: string;
+    };
+    /** External integrations */
+    integrations?: IntegrationsConfig;
+}
+
+/**
+ * Backend deployment bundle for uploading to Playcademy platform
+ */
+interface BackendDeploymentBundle {
+    /** Bundled JavaScript code ready for deployment */
+    code: string;
+    /** Game configuration */
+    config: PlaycademyConfig;
+}
+
+type TokenType = 'session' | 'apiKey' | 'gameJwt';
 interface ClientConfig {
     baseUrl: string;
+    gameUrl?: string;
     token?: string;
+    tokenType?: TokenType;
     gameId?: string;
     autoStartSession?: boolean;
 }
@@ -2767,6 +3429,32 @@ type DevUploadHooks = {
     onEvent?: (e: DevUploadEvent) => void;
     onClose?: () => void;
 };
+/**
+ * Better-auth API key creation response
+ */
+interface BetterAuthApiKeyResponse {
+    apiKey: string;
+    key: {
+        id: string;
+        name: string | null;
+        expiresAt: string | null;
+        createdAt: string;
+    };
+}
+/**
+ * Better-auth API key list item
+ */
+interface BetterAuthApiKey {
+    id: string;
+    name: string | null;
+    start: string;
+    enabled: boolean;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastRequest: string | null;
+    requestCount: number;
+}
 
 /**
  * OAuth 2.0 implementation for the Playcademy SDK
@@ -2934,8 +3622,9 @@ type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  * Provides namespaced access to all platform features including games, users, inventory, and more.
  */
 declare class PlaycademyClient {
-    private baseUrl;
-    private token?;
+    baseUrl: string;
+    gameUrl?: string;
+    private authStrategy;
     private gameId?;
     private config;
     private listeners;
@@ -2946,8 +3635,9 @@ declare class PlaycademyClient {
      * Creates a new PlaycademyClient instance.
      *
      * @param config - Optional configuration object
-     * @param config.baseUrl - Base URL for API requests (defaults to '/api')
+     * @param config.baseUrl - Base URL (e.g., 'https://hub.playcademy.com' or '/'). SDK automatically appends /api
      * @param config.token - Authentication token
+     * @param config.tokenType - Optional token type (auto-detected if not provided)
      * @param config.gameId - Game ID for automatic session management
      * @param config.autoStartSession - Automatically start a game session?
      */
@@ -2955,10 +3645,19 @@ declare class PlaycademyClient {
     /**
      * Gets the effective base URL for API requests.
      * Converts relative URLs to absolute URLs in browser environments.
+     * Note: baseUrl already includes /api suffix from constructor.
      *
-     * @returns The complete base URL for API requests
+     * @returns The complete base URL for API requests (with /api suffix)
      */
     getBaseUrl(): string;
+    /**
+     * Gets the effective game backend URL for integration requests.
+     * Throws if gameUrl is not configured.
+     *
+     * @returns The complete game backend URL for API requests (with /api suffix)
+     * @throws PlaycademyError if gameUrl is not set
+     */
+    private getGameBackendUrl;
     /**
      * Simple ping method for testing connectivity.
      *
@@ -2970,8 +3669,15 @@ declare class PlaycademyClient {
      * Emits an 'authChange' event when the token changes.
      *
      * @param token - The authentication token, or null to clear
+     * @param tokenType - Optional token type (auto-detected if not provided)
      */
-    setToken(token: string | null): void;
+    setToken(token: string | null, tokenType?: TokenType): void;
+    /**
+     * Gets the current token type.
+     *
+     * @returns The token type
+     */
+    getTokenType(): TokenType;
     /**
      * Gets the current authentication token.
      *
@@ -3039,7 +3745,7 @@ declare class PlaycademyClient {
      */
     private emit;
     /**
-     * Makes an authenticated HTTP request to the API.
+     * Makes an authenticated HTTP request to the platform API.
      *
      * @param path - API endpoint path
      * @param method - HTTP method
@@ -3048,6 +3754,17 @@ declare class PlaycademyClient {
      * @returns Promise resolving to the response data
      */
     protected request<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /**
+     * Makes an authenticated HTTP request to the game's backend Worker.
+     * Uses gameUrl if set, otherwise falls back to platform API.
+     *
+     * @param path - API endpoint path
+     * @param method - HTTP method
+     * @param body - Request body (optional)
+     * @param headers - Additional headers (optional)
+     * @returns Promise resolving to the response data
+     */
+    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
     /**
      * Ensures a gameId is available, throwing an error if not.
      *
@@ -3076,9 +3793,23 @@ declare class PlaycademyClient {
         }) => Promise<{
             success: boolean;
             token?: string;
+            user?: {
+                id: string;
+                email: string;
+            };
+            expiresAt?: string;
             error?: string;
         }>;
         logout: () => Promise<void>;
+        apiKeys: {
+            create: (options?: {
+                name?: string;
+                expiresIn?: number | null;
+                permissions?: Record<string, string[]>;
+            }) => Promise<BetterAuthApiKeyResponse>;
+            list: () => Promise<BetterAuthApiKey[]>;
+            revoke: (keyId: string) => Promise<void>;
+        };
     };
     /** Identity provider connection methods (connect external accounts) */
     identity: {
@@ -3129,7 +3860,7 @@ declare class PlaycademyClient {
         };
         leaderboard: {
             get: (gameId: string, options?: {
-                limit? /** Runtime methods (getGameToken, exit) */: number;
+                limit?: number;
                 offset?: number;
             }) => Promise<LeaderboardEntry[]>;
         };
@@ -3161,27 +3892,13 @@ declare class PlaycademyClient {
             get: () => Promise<DeveloperStatusValue>;
         };
         games: {
-            upsert: (slug: string, metadata: UpsertGameMetadataInput, file: File | Blob | null, hooks?: DevUploadHooks) => Promise<Game>;
-            update: (gameId: string, props: Partial<Game>) => Promise<void>;
+            deploy: {
+                frontend: (slug: string, metadata: UpsertGameMetadataInput, file: File | Blob | null, hooks?: DevUploadHooks) => Promise<Game>;
+                backend: (slug: string, bundle: BackendDeploymentBundle) => Promise<BackendDeploymentResponse>;
+            };
+            upsert: (slug: string, metadata: UpsertGameMetadataInput) => Promise<Game>;
             delete: (gameId: string) => Promise<void>;
         };
-        keys: {
-            create: (label?: string) => Promise<{
-                id: string;
-                createdAt: Date;
-                userId: string;
-                label: string | null;
-                keyHash: string;
-            }>;
-            list: () => Promise<{
-                id: string;
-                createdAt: Date;
-                userId: string;
-                label: string | null;
-                keyHash: string;
-            }[]>;
-            revoke: (keyId: string) => Promise<void>;
-        };
         items: {
             create: (gameId: string, slug: string, itemData: Omit<InsertItemInput, "slug" | "gameId">) => Promise<Item>;
             update: (gameId: string, itemId: string, updates: UpdateItemInput) => Promise<Item>;
@@ -3201,8 +3918,8 @@ declare class PlaycademyClient {
     };
     /** Map methods (elements) */
     maps: {
-        get: (identifier: string) => Promise<MapData>;
-        elements: (mapId: string) => Promise<MapElementWithGame[]>;
+        get: (identifier: string, options?: TTLCacheConfig) => Promise<MapData>;
+        elements: (mapId: string, options?: TTLCacheConfig) => Promise<MapElementWithGame[]>;
         objects: {
             list: (mapId: string) => Promise<MapObjectWithItem[]>;
             create: (mapId: string, objectData: CreateMapObjectData) => Promise<MapObjectWithItem>;
@@ -3377,6 +4094,16 @@ declare class PlaycademyClient {
     };
     /** TimeBack XP methods (today, total, history) */
     timeback: {
+        recordProgress: (progressData: RecordProgressRequest["progressData"]) => Promise<RecordProgressResponse>;
+        recordSessionEnd: (sessionData: RecordSessionEndRequest["sessionData"]) => Promise<RecordSessionEndResponse>;
+        awardXP: (xpAmount: number, metadata: AwardXpRequest["metadata"]) => Promise<AwardXpResponse>;
+        management: {
+            setup: (request: TimebackSetupRequest) => Promise<TimebackSetupResponse>;
+            verify: (gameId: string) => Promise<TimebackVerifyResponse>;
+            cleanup: (gameId: string) => Promise<void>;
+            get: (gameId: string) => Promise<GameTimebackIntegration | null>;
+            getConfig: (gameId: string) => Promise<TimebackSetupRequest["config"]>;
+        };
         xp: {
             today: (options?: {
                 date?: string;
@@ -3458,6 +4185,33 @@ declare class PlaycademyClient {
             submit: (achievementId: string) => Promise<AchievementProgressResponse>;
         };
     };
+    /** Notifications methods (list, update status, stats) */
+    notifications: {
+        list: (queryOptions?: {
+            status?: NotificationStatus;
+            type?: NotificationType;
+            limit?: number;
+            offset?: number;
+        }, cacheOptions?: TTLCacheConfig) => Promise<Notification[]>;
+        markAsSeen: (notificationId: string) => Promise<Notification>;
+        markAsClicked: (notificationId: string) => Promise<Notification>;
+        dismiss: (notificationId: string) => Promise<Notification>;
+        stats: {
+            get: (queryOptions?: {
+                from?: string;
+                to?: string;
+            }, cacheOptions?: TTLCacheConfig) => Promise<NotificationStats>;
+        };
+    };
+    /** Backend methods for calling custom game API routes */
+    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>;
+    };
     /** Auto-initializes a PlaycademyClient with context from the environment */
     static init: typeof init;
     /** Authenticates a user with email and password */