@playcademy/sdk 0.0.1-beta.3 → 0.0.1-beta.31

package/dist/core/client.d.ts

@@ -1,38 +1,139 @@
-import { type Method } from './request';
-import { type Game, type GameWithManifest, type UpsertGameMetadataInput, type InsertReward, type UpdateReward } from '@playcademy/data/schemas';
-import type { GameState, InventoryItemWithReward, ClientConfig, ClientEvents, LoginResponse, GameTokenResponse, StartSessionResponse, InventoryMutationResponse, DeveloperStatusValue } from '../types';
+import { init, login } from './static';
+import type { ClientConfig, ClientEvents } from '../types';
+import type { Method } from './request';
+/**
+ * Main Playcademy SDK client for interacting with the platform API.
+ * Provides namespaced access to all platform features including games, users, inventory, and more.
+ */
 export declare class PlaycademyClient {
     private baseUrl;
     private token?;
     private gameId?;
     private listeners;
     private internalClientSessionId?;
-    constructor(config: ClientConfig);
-    private _initializeInternalSession;
+    /**
+     * Creates a new PlaycademyClient instance.
+     *
+     * @param config - Optional configuration object
+     * @param config.baseUrl - Base URL for API requests (defaults to '/api')
+     * @param config.token - Authentication token
+     * @param config.gameId - Game ID for automatic session management
+     */
+    constructor(config?: Partial<ClientConfig>);
+    /**
+     * Gets the effective base URL for API requests.
+     * Converts relative URLs to absolute URLs in browser environments.
+     *
+     * @returns The complete base URL for API requests
+     */
     getBaseUrl(): string;
-    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
-    private emit;
+    /**
+     * Simple ping method for testing connectivity.
+     *
+     * @returns 'pong' string response
+     */
+    ping(): string;
+    /**
+     * Sets the authentication token for API requests.
+     * Emits an 'authChange' event when the token changes.
+     *
+     * @param token - The authentication token, or null to clear
+     */
     setToken(token: string | null): void;
+    /**
+     * Registers a callback to be called when authentication state changes.
+     *
+     * @param callback - Function to call when auth state changes
+     */
     onAuthChange(callback: (token: string | null) => void): void;
+    /**
+     * Registers an event listener for client events.
+     *
+     * @param event - The event type to listen for
+     * @param callback - Function to call when the event is emitted
+     */
+    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
+    /**
+     * Emits an event to all registered listeners.
+     *
+     * @param event - The event type to emit
+     * @param payload - The event payload
+     */
+    private emit;
+    /**
+     * Makes an authenticated HTTP request to the 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 request<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /**
+     * Ensures a gameId is available, throwing an error if not.
+     *
+     * @returns The gameId
+     * @throws PlaycademyError if no gameId is configured
+     */
     private _ensureGameId;
+    /**
+     * Initializes an internal game session for automatic session management.
+     * Called automatically when a gameId is provided in the constructor.
+     */
+    private _initializeInternalSession;
+    /** Authentication methods (logout) */
     auth: {
         logout: () => Promise<void>;
     };
+    /** Runtime methods (getGameToken, exit) */
     runtime: {
         getGameToken: (gameId: string, options?: {
             apply?: boolean;
-        }) => Promise<GameTokenResponse>;
+        }) => Promise<import("../types").GameTokenResponse>;
         exit: () => Promise<void>;
+        onInit: (handler: (context: import("../types").GameContextPayload) => void) => void;
+        onTokenRefresh: (handler: (data: {
+            token: string;
+            exp: number;
+        }) => void) => void;
+        onPause: (handler: () => void) => void;
+        onResume: (handler: () => void) => void;
+        onForceExit: (handler: () => void) => void;
+        onOverlay: (handler: (isVisible: boolean) => void) => void;
+        ready: () => void;
+        sendTelemetry: (data: {
+            fps: number;
+            mem: number;
+        }) => void;
+        removeListener: (eventType: import("..").MessageEvents, handler: ((context: import("../types").GameContextPayload) => void) | ((data: {
+            token: string;
+            exp: number;
+        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
+        removeAllListeners: () => void;
+        getListenerCounts: () => Record<string, number>;
     };
+    /** Game management methods (fetch, list, saveState, loadState, sessions) */
     games: {
-        fetch: (gameIdOrSlug: string) => Promise<GameWithManifest>;
-        list: () => Promise<Array<Game>>;
+        fetch: (gameIdOrSlug: string) => Promise<import("@playcademy/data/types").GameWithManifest>;
+        list: () => Promise<Array<import("@playcademy/data/types").Game>>;
         saveState: (state: Record<string, unknown>) => Promise<void>;
-        loadState: () => Promise<GameState>;
-        startSession: (gameId?: string) => Promise<StartSessionResponse>;
+        loadState: () => Promise<import("@playcademy/data/types").GameStateData>;
+        startSession: (gameId?: string) => Promise<import("../types").StartSessionResponse>;
         endSession: (sessionId: string, gameId?: string) => Promise<void>;
+        token: {
+            create: (gameId: string, options?: {
+                apply?: boolean;
+            }) => Promise<import("../types").GameTokenResponse>;
+        };
+        leaderboard: {
+            get: (gameId: string, options?: {
+                limit?: number;
+                offset?: number;
+            }) => Promise<import("@playcademy/data/types").LeaderboardEntry[]>;
+        };
     };
+    /** User methods (me, inventory management) */
     users: {
         me: () => Promise<{
             id: string;
@@ -43,102 +144,299 @@ export declare class PlaycademyClient {
             image: string | null;
             role: "admin" | "player" | "developer";
             developerStatus: "none" | "pending" | "approved";
+            characterCreated: boolean;
             createdAt: Date;
             updatedAt: Date;
         }>;
         inventory: {
-            get: () => Promise<InventoryItemWithReward[]>;
-            add: (rewardId: string, qty: number) => Promise<InventoryMutationResponse>;
-            spend: (rewardId: string, qty: number) => Promise<InventoryMutationResponse>;
+            get: () => Promise<import("@playcademy/data/types").InventoryItemWithItem[]>;
+            add: (identifier: string, qty: number) => Promise<import("../types").InventoryMutationResponse>;
+            remove: (identifier: string, qty: number) => Promise<import("../types").InventoryMutationResponse>;
+            quantity: (identifier: string) => Promise<number>;
+            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
+        };
+        scores: {
+            get: (userIdOrOptions?: string | {
+                limit?: number;
+                gameId?: string;
+            }, options?: {
+                limit?: number;
+                gameId?: string;
+            }) => Promise<import("./namespaces/users").UserScore[]>;
         };
     };
+    /** Developer tools (auth, games, keys management) */
     dev: {
         auth: {
             applyForDeveloper: () => Promise<void>;
-            getDeveloperStatus: () => Promise<DeveloperStatusValue>;
+            getStatus: () => Promise<import("@playcademy/data/types").DeveloperStatusValue>;
         };
         games: {
-            upsert: (slug: string, metadata: UpsertGameMetadataInput, file: File | Blob) => Promise<Game>;
-            update: (gameId: string, props: Partial<Game>) => Promise<void>;
+            upsert: (slug: string, metadata: import("@playcademy/data/types").UpsertGameMetadataInput, file: File | Blob) => Promise<import("@playcademy/data/types").Game>;
+            update: (gameId: string, props: Partial<import("@playcademy/data/types").Game>) => Promise<void>;
             delete: (gameId: string) => Promise<void>;
         };
         keys: {
-            createKey: (gameId: string, label?: string) => Promise<{
+            create: (label?: string) => Promise<{
                 id: string;
                 createdAt: Date;
                 userId: string;
                 label: string | null;
                 keyHash: string;
             }>;
-            listKeys: (gameId: string) => Promise<{
+            list: () => Promise<{
                 id: string;
                 createdAt: Date;
                 userId: string;
                 label: string | null;
                 keyHash: string;
             }[]>;
-            revokeKey: (keyId: string) => Promise<void>;
+            revoke: (keyId: string) => Promise<void>;
+        };
+        items: {
+            create: (gameId: string, slug: string, itemData: Omit<import("@playcademy/data/types").InsertItemInput, "slug" | "gameId">) => Promise<import("@playcademy/data/types").Item>;
+            update: (gameId: string, itemId: string, updates: import("@playcademy/data/types").UpdateItemInput) => Promise<import("@playcademy/data/types").Item>;
+            list: (gameId: string) => Promise<Array<import("@playcademy/data/types").Item>>;
+            get: (gameId: string, slug: string) => Promise<import("@playcademy/data/types").Item>;
+            delete: (gameId: string, itemId: string) => Promise<void>;
+            shop: {
+                create: (gameId: string, itemId: string, listingData: Omit<import("@playcademy/data/types").InsertShopListingInput, "itemId">) => Promise<import("@playcademy/data/types").ShopListing>;
+                get: (gameId: string, itemId: string) => Promise<import("@playcademy/data/types").ShopListing | null>;
+                update: (gameId: string, itemId: string, updates: import("@playcademy/data/types").UpdateShopListingInput) => Promise<import("@playcademy/data/types").ShopListing>;
+                delete: (gameId: string, itemId: string) => Promise<void>;
+                list: (gameId: string) => Promise<Array<import("@playcademy/data/types").ShopListing & {
+                    item: import("@playcademy/data/types").Item;
+                }>>;
+            };
         };
     };
+    /** Map methods (elements) */
     maps: {
-        elements: (mapId: string) => Promise<{
-            id: string;
-            mapId: string | null;
-            elementSlug: string;
-            interactionType: "game_entry" | "game_registry" | "info" | "teleport" | "door_in" | "door_out" | "npc_interaction" | "quest_trigger";
-            metadata: ({
-                description?: string | undefined;
-                sourceTiledObjects?: Record<string, unknown>[] | undefined;
-            } & {
-                [k: string]: unknown;
-            }) | null;
-            gameId: string | null;
-        }[]>;
+        get: (identifier: string) => Promise<import("@playcademy/data/types").MapData>;
+        elements: (mapId: string) => Promise<import("@playcademy/data/types").MapElementWithGame[]>;
+        objects: {
+            list: (mapId: string) => Promise<import("@playcademy/data/types").MapObjectWithItem[]>;
+            create: (mapId: string, objectData: import("@playcademy/data/types").CreateMapObjectData) => Promise<import("@playcademy/data/types").MapObjectWithItem>;
+            delete: (mapId: string, objectId: string) => Promise<void>;
+        };
     };
+    /** Admin methods (games, items, currencies, shop listings) */
     admin: {
         games: {
             pauseGame: (gameId: string) => Promise<void>;
             resumeGame: (gameId: string) => Promise<void>;
         };
-        rewards: {
-            createReward: (props: InsertReward) => Promise<{
+        items: {
+            create: (props: import("@playcademy/data/types").InsertItemInput) => Promise<{
                 id: string;
-                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+                createdAt: Date;
+                slug: string;
                 displayName: string;
-                description: string | null;
                 metadata: unknown;
-                internalName: string;
+                gameId: string | null;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+                isPlaceable: boolean;
+                imageUrl: string | null;
             }>;
-            getReward: (rewardId: string) => Promise<{
+            get: (itemId: string) => Promise<{
                 id: string;
-                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+                createdAt: Date;
+                slug: string;
                 displayName: string;
-                description: string | null;
                 metadata: unknown;
-                internalName: string;
+                gameId: string | null;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+                isPlaceable: boolean;
+                imageUrl: string | null;
             }>;
-            listRewards: () => Promise<{
+            list: () => Promise<{
                 id: string;
-                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+                createdAt: Date;
+                slug: string;
                 displayName: string;
-                description: string | null;
                 metadata: unknown;
-                internalName: string;
+                gameId: string | null;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+                isPlaceable: boolean;
+                imageUrl: string | null;
             }[]>;
-            updateReward: (rewardId: string, props: UpdateReward) => Promise<{
+            update: (itemId: string, props: import("@playcademy/data/types").UpdateItemInput) => Promise<{
                 id: string;
-                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+                createdAt: Date;
+                slug: string;
                 displayName: string;
-                description: string | null;
                 metadata: unknown;
-                internalName: string;
+                gameId: string | null;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+                isPlaceable: boolean;
+                imageUrl: string | null;
             }>;
-            deleteReward: (rewardId: string) => Promise<void>;
+            delete: (itemId: string) => Promise<void>;
+        };
+        currencies: {
+            create: (props: import("@playcademy/data/types").InsertCurrencyInput) => Promise<{
+                symbol: string | null;
+                id: string;
+                createdAt: Date;
+                updatedAt: Date | null;
+                itemId: string;
+                isPrimary: boolean;
+            }>;
+            get: (currencyId: string) => Promise<{
+                symbol: string | null;
+                id: string;
+                createdAt: Date;
+                updatedAt: Date | null;
+                itemId: string;
+                isPrimary: boolean;
+            }>;
+            list: () => Promise<{
+                symbol: string | null;
+                id: string;
+                createdAt: Date;
+                updatedAt: Date | null;
+                itemId: string;
+                isPrimary: boolean;
+            }[]>;
+            update: (currencyId: string, props: import("@playcademy/data/types").UpdateCurrencyInput) => Promise<{
+                symbol: string | null;
+                id: string;
+                createdAt: Date;
+                updatedAt: Date | null;
+                itemId: string;
+                isPrimary: boolean;
+            }>;
+            delete: (currencyId: string) => Promise<void>;
+        };
+        shopListings: {
+            create: (props: import("@playcademy/data/types").InsertShopListingInput) => Promise<{
+                id: string;
+                createdAt: Date;
+                updatedAt: Date | null;
+                itemId: string;
+                currencyId: string;
+                price: number;
+                sellBackPercentage: number | null;
+                stock: number | null;
+                isActive: boolean;
+                availableFrom: Date | null;
+                availableUntil: Date | null;
+            }>;
+            get: (listingId: string) => Promise<{
+                id: string;
+                createdAt: Date;
+                updatedAt: Date | null;
+                itemId: string;
+                currencyId: string;
+                price: number;
+                sellBackPercentage: number | null;
+                stock: number | null;
+                isActive: boolean;
+                availableFrom: Date | null;
+                availableUntil: Date | null;
+            }>;
+            list: () => Promise<{
+                id: string;
+                createdAt: Date;
+                updatedAt: Date | null;
+                itemId: string;
+                currencyId: string;
+                price: number;
+                sellBackPercentage: number | null;
+                stock: number | null;
+                isActive: boolean;
+                availableFrom: Date | null;
+                availableUntil: Date | null;
+            }[]>;
+            update: (listingId: string, props: import("@playcademy/data/types").UpdateShopListingInput) => Promise<{
+                id: string;
+                createdAt: Date;
+                updatedAt: Date | null;
+                itemId: string;
+                currencyId: string;
+                price: number;
+                sellBackPercentage: number | null;
+                stock: number | null;
+                isActive: boolean;
+                availableFrom: Date | null;
+                availableUntil: Date | null;
+            }>;
+            delete: (listingId: string) => Promise<void>;
+        };
+    };
+    /** Shop methods (view) */
+    shop: {
+        view: () => Promise<import("@playcademy/data/types").ShopViewResponse>;
+    };
+    /** Level methods (levels) */
+    levels: {
+        get: () => Promise<import("@playcademy/data/types").UserLevel>;
+        progress: () => Promise<{
+            level: number;
+            currentXp: number;
+            xpToNextLevel: number;
+            totalXP: number;
+        }>;
+        addXP: (amount: number) => Promise<import("@playcademy/data/types").XPAddResult>;
+        config: {
+            list: () => Promise<import("@playcademy/data/types").LevelConfig[]>;
+            get: (level: number) => Promise<import("@playcademy/data/types").LevelConfig | null>;
         };
     };
+    /** Telemetry methods (pushMetrics) */
     telemetry: {
         pushMetrics: (metrics: Record<string, number>) => Promise<void>;
     };
-    ping(): string;
-    static login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+    /** Credits methods (credits management) */
+    credits: {
+        balance: () => Promise<number>;
+        add: (amount: number) => Promise<number>;
+        spend: (amount: number) => Promise<number>;
+    };
+    /** Platform-wide leaderboard methods (fetch, getUserRank) */
+    leaderboard: {
+        fetch: (options?: import("@playcademy/data/types").LeaderboardOptions) => Promise<import("@playcademy/data/types").GameLeaderboardEntry[]>;
+        getUserRank: (gameId: string, userId: string) => Promise<import("@playcademy/data/types").UserRankResponse>;
+    };
+    /** Platform-wide scores methods (submit, getUserScores) */
+    scores: {
+        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<import("./namespaces/scores").ScoreSubmission>;
+        getByUser: (gameId: string, userId: string, options?: {
+            limit?: number;
+        }) => Promise<import("@playcademy/data/types").UserScore[]>;
+    };
+    /** Character methods (get, create, update, components) */
+    character: {
+        get: (userId?: string) => Promise<import("@playcademy/data/types").PlayerCharacter | null>;
+        create: (characterData: import("./namespaces/character").CreateCharacterData) => Promise<import("@playcademy/data/types").PlayerCharacter>;
+        update: (updates: import("./namespaces/character").UpdateCharacterData) => Promise<import("@playcademy/data/types").PlayerCharacter>;
+        components: {
+            list: (options?: import("./namespaces/character").CharacterComponentsOptions & {
+                skipCache?: boolean;
+            }) => Promise<import("@playcademy/data/types").CharacterComponentWithSpriteUrl[]>;
+            clearCache: () => void;
+            getCacheKeys: () => string[];
+        };
+    };
+    /** Sprites methods (templates) */
+    sprites: {
+        templates: {
+            get: (slug: string) => Promise<import("@playcademy/data/types").SpriteTemplateData>;
+        };
+    };
+    /** Realtime methods (token) */
+    realtime: {
+        token: {
+            get: () => Promise<import("./namespaces/realtime").RealtimeTokenResponse>;
+        };
+        open(channel?: string): Promise<import("@playcademy/realtime/server/types").RealtimeChannel>;
+    };
+    /** Auto-initializes a PlaycademyClient with context from the environment */
+    static init: typeof init;
+    /** Authenticates a user with email and password */
+    static login: typeof login;
 }