@playcademy/sdk 0.0.1-beta.2 → 0.0.1-beta.20

package/README.md

@@ -64,7 +64,7 @@ async function initializeAndUseClient() {
 
     // If the token has appropriate permissions, you can access all namespaces:
     // client.dev.games.upsert(...)
-    // client.admin.rewards.createReward(...)
+    // client.admin.items.createItem(...)
     // Calling a method without sufficient token permissions will result in a server error.
 
     // Example: Listen for auth changes (e.g., if token is refreshed or cleared by logout)
@@ -93,9 +93,9 @@ async function runGame() {
         const { sessionId } = await client.games.startSession()
         console.log('Session started:', sessionId)
 
-        // 2) Fetch player's inventory/rewards
-        const rewards = await client.users.inventory.get()
-        console.log('Player inventory:', rewards)
+        // 2) Fetch player's inventory/items
+        const items = await client.users.inventory.get()
+        console.log('Player inventory:', items)
 
         // 3) Save game state (uses client.gameId implicitly)
         await client.games.saveState({
@@ -136,8 +136,8 @@ All methods returning data are strongly typed.
     - `me()`: Fetch current user details.
     - **`inventory`**:
         - `get()`: Get player inventory.
-        - `add(rewardId, qty)`: Add item to player inventory.
-        - `spend(rewardId, qty)`: Spend item from player inventory.
+        - `add(itemId, qty)`: Add item to player inventory.
+        - `spend(itemId, qty)`: Spend item from player inventory.
     - **`progress`**: Manages persistent progress data for a game (e.g., levels completed, scores, collectibles).
         - `get(gameId?)`: Get the entire progress state for a game. `gameId` is optional and defaults to the client's current game context.
         - `update(data, gameId?)`: Update the progress state for a game. `gameId` is optional. The `data` object can be structured to hold progress for various internal nodes or aspects of the game.
@@ -157,7 +157,11 @@ All methods returning data are strongly typed.
 - **`dev.games`**: Upsert, update, delete games.
 - **`dev.keys`**: Create, list, revoke API keys for games.
 - **`admin.games`**: Pause/resume games.
-- **`admin.rewards`**: CRUD operations for rewards.
+- **`admin.items`**: CRUD operations for items.
+- **`admin.currencies`**: CRUD operations for currencies.
+- **`admin.shopListings`**: CRUD operations for shop listings.
+- **`shop`**: Player-facing shop operations.
+    - `view()`: Get shop items and currency information.
 - **`telemetry`**: Push metrics.
 
 ## Contributing

package/dist/core/client.d.ts

@@ -1,41 +1,113 @@
 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';
+/**
+ * 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("..").GameTokenResponse>;
         exit: () => Promise<void>;
     };
+    /** Game management methods (fetch, list, saveState, loadState, sessions) */
     games: {
-        fetch: (gameIdOrSlug: string) => Promise<GameWithManifest>;
-        list: () => Promise<Array<Game>>;
+        fetch: (gameIdOrSlug: string) => Promise<import("@playcademy/types").GameWithManifest>;
+        list: () => Promise<Array<import("@playcademy/types").Game>>;
         saveState: (state: Record<string, unknown>) => Promise<void>;
-        loadState: () => Promise<GameState>;
-        startSession: (gameId?: string) => Promise<StartSessionResponse>;
+        loadState: () => Promise<import("..").GameState>;
+        startSession: (gameId?: string) => Promise<import("..").StartSessionResponse>;
         endSession: (sessionId: string, gameId?: string) => Promise<void>;
     };
+    /** User methods (me, inventory management) */
     users: {
         me: () => Promise<{
             id: string;
+            createdAt: Date;
+            updatedAt: Date;
             name: string;
             username: string | null;
             email: string;
@@ -43,23 +115,22 @@ export declare class PlaycademyClient {
             image: string | null;
             role: "admin" | "player" | "developer";
             developerStatus: "none" | "pending" | "approved";
-            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/types").InventoryItemWithItem[]>;
+            add: (itemId: string, qty: number) => Promise<import("..").InventoryMutationResponse>;
+            spend: (itemId: string, qty: number) => Promise<import("..").InventoryMutationResponse>;
         };
     };
+    /** Developer tools (auth, games, keys management) */
     dev: {
         auth: {
             applyForDeveloper: () => Promise<void>;
-            getDeveloperStatus: () => Promise<DeveloperStatusValue>;
+            getDeveloperStatus: () => Promise<import("..").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/types").UpsertGameMetadataInput, file: File | Blob) => Promise<import("@playcademy/types").Game>;
+            update: (gameId: string, props: Partial<import("@playcademy/types").Game>) => Promise<void>;
             delete: (gameId: string) => Promise<void>;
         };
         keys: {
@@ -80,12 +151,10 @@ export declare class PlaycademyClient {
             revokeKey: (keyId: string) => Promise<void>;
         };
     };
+    /** 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;
@@ -93,52 +162,161 @@ export declare class PlaycademyClient {
                 [k: string]: unknown;
             }) | null;
             gameId: string | null;
+            mapId: string | null;
+            elementSlug: string;
+            interactionType: "game_entry" | "game_registry" | "info" | "teleport" | "door_in" | "door_out" | "npc_interaction" | "quest_trigger";
         }[]>;
     };
+    /** 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/types").InsertItem) => Promise<{
                 id: string;
-                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
                 displayName: string;
-                description: string | null;
                 metadata: unknown;
+                createdAt: Date;
                 internalName: string;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+                imageUrl: string | null;
             }>;
-            getReward: (rewardId: string) => Promise<{
+            get: (itemId: string) => Promise<{
                 id: string;
-                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
                 displayName: string;
-                description: string | null;
                 metadata: unknown;
+                createdAt: Date;
                 internalName: string;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+                imageUrl: string | null;
             }>;
-            listRewards: () => Promise<{
+            list: () => Promise<{
                 id: string;
-                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
                 displayName: string;
-                description: string | null;
                 metadata: unknown;
+                createdAt: Date;
                 internalName: string;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+                imageUrl: string | null;
             }[]>;
-            updateReward: (rewardId: string, props: UpdateReward) => Promise<{
+            update: (itemId: string, props: import("@playcademy/types").UpdateItem) => Promise<{
                 id: string;
-                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
                 displayName: string;
-                description: string | null;
                 metadata: unknown;
+                createdAt: Date;
                 internalName: string;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+                imageUrl: string | null;
             }>;
-            deleteReward: (rewardId: string) => Promise<void>;
+            delete: (itemId: string) => Promise<void>;
         };
+        currencies: {
+            create: (props: import("@playcademy/types").InsertCurrency) => 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/types").UpdateCurrency) => 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/types").InsertShopListing) => 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/types").UpdateShopListing) => 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("..").ShopViewResponse>;
     };
+    /** Telemetry methods (pushMetrics) */
     telemetry: {
         pushMetrics: (metrics: Record<string, number>) => Promise<void>;
     };
-    ping(): string;
-    static login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+    /** Auto-initializes a PlaycademyClient with context from the environment */
+    static init: typeof init;
+    /** Authenticates a user with email and password */
+    static login: typeof login;
 }