@playcademy/sdk 0.0.1-beta.15 → 0.0.1-beta.17

package/README.md

@@ -158,6 +158,10 @@ All methods returning data are strongly typed.
 - **`dev.keys`**: Create, list, revoke API keys for games.
 - **`admin.games`**: Pause/resume games.
 - **`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,38 +1,108 @@
 import { type Method } from './request';
-import type { Game, GameWithManifest, UpsertGameMetadataInput, InsertItem, UpdateItem, InsertCurrency, UpdateCurrency, InsertShopListing, UpdateShopListing } from '@playcademy/types';
-import type { GameState, InventoryItemWithItem, ClientConfig, ClientEvents, LoginResponse, GameTokenResponse, StartSessionResponse, InventoryMutationResponse, DeveloperStatusValue, ShopViewResponse } 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;
@@ -47,19 +117,20 @@ export declare class PlaycademyClient {
             developerStatus: "none" | "pending" | "approved";
         }>;
         inventory: {
-            get: () => Promise<InventoryItemWithItem[]>;
-            add: (itemId: string, qty: number) => Promise<InventoryMutationResponse>;
-            spend: (itemId: 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,6 +151,7 @@ export declare class PlaycademyClient {
             revokeKey: (keyId: string) => Promise<void>;
         };
     };
+    /** Map methods (elements) */
     maps: {
         elements: (mapId: string) => Promise<{
             id: string;
@@ -95,13 +167,14 @@ export declare class PlaycademyClient {
             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>;
         };
         items: {
-            createItem: (props: InsertItem) => Promise<{
+            create: (props: import("@playcademy/types").InsertItem) => Promise<{
                 id: string;
                 displayName: string;
                 metadata: unknown;
@@ -111,7 +184,7 @@ export declare class PlaycademyClient {
                 type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 imageUrl: string | null;
             }>;
-            getItem: (itemId: string) => Promise<{
+            get: (itemId: string) => Promise<{
                 id: string;
                 displayName: string;
                 metadata: unknown;
@@ -121,7 +194,7 @@ export declare class PlaycademyClient {
                 type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 imageUrl: string | null;
             }>;
-            listItems: () => Promise<{
+            list: () => Promise<{
                 id: string;
                 displayName: string;
                 metadata: unknown;
@@ -131,7 +204,7 @@ export declare class PlaycademyClient {
                 type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 imageUrl: string | null;
             }[]>;
-            updateItem: (itemId: string, props: UpdateItem) => Promise<{
+            update: (itemId: string, props: import("@playcademy/types").UpdateItem) => Promise<{
                 id: string;
                 displayName: string;
                 metadata: unknown;
@@ -141,10 +214,10 @@ export declare class PlaycademyClient {
                 type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 imageUrl: string | null;
             }>;
-            deleteItem: (itemId: string) => Promise<void>;
+            delete: (itemId: string) => Promise<void>;
         };
         currencies: {
-            createCurrency: (props: InsertCurrency) => Promise<{
+            create: (props: import("@playcademy/types").InsertCurrency) => Promise<{
                 symbol: string | null;
                 id: string;
                 createdAt: Date;
@@ -152,7 +225,7 @@ export declare class PlaycademyClient {
                 itemId: string;
                 isPrimary: boolean;
             }>;
-            getCurrency: (currencyId: string) => Promise<{
+            get: (currencyId: string) => Promise<{
                 symbol: string | null;
                 id: string;
                 createdAt: Date;
@@ -160,7 +233,7 @@ export declare class PlaycademyClient {
                 itemId: string;
                 isPrimary: boolean;
             }>;
-            listCurrencies: () => Promise<{
+            list: () => Promise<{
                 symbol: string | null;
                 id: string;
                 createdAt: Date;
@@ -168,7 +241,7 @@ export declare class PlaycademyClient {
                 itemId: string;
                 isPrimary: boolean;
             }[]>;
-            updateCurrency: (currencyId: string, props: UpdateCurrency) => Promise<{
+            update: (currencyId: string, props: import("@playcademy/types").UpdateCurrency) => Promise<{
                 symbol: string | null;
                 id: string;
                 createdAt: Date;
@@ -176,70 +249,74 @@ export declare class PlaycademyClient {
                 itemId: string;
                 isPrimary: boolean;
             }>;
-            deleteCurrency: (currencyId: string) => Promise<void>;
+            delete: (currencyId: string) => Promise<void>;
         };
         shopListings: {
-            createListing: (props: InsertShopListing) => Promise<{
+            create: (props: import("@playcademy/types").InsertShopListing) => Promise<{
                 id: string;
                 createdAt: Date;
                 updatedAt: Date | null;
                 itemId: string;
                 currencyId: string;
-                priceAmountMinor: number;
+                price: number;
                 sellBackPercentage: number | null;
                 stock: number | null;
                 isActive: boolean;
                 availableFrom: Date | null;
                 availableUntil: Date | null;
             }>;
-            getListing: (listingId: string) => Promise<{
+            get: (listingId: string) => Promise<{
                 id: string;
                 createdAt: Date;
                 updatedAt: Date | null;
                 itemId: string;
                 currencyId: string;
-                priceAmountMinor: number;
+                price: number;
                 sellBackPercentage: number | null;
                 stock: number | null;
                 isActive: boolean;
                 availableFrom: Date | null;
                 availableUntil: Date | null;
             }>;
-            listListings: () => Promise<{
+            list: () => Promise<{
                 id: string;
                 createdAt: Date;
                 updatedAt: Date | null;
                 itemId: string;
                 currencyId: string;
-                priceAmountMinor: number;
+                price: number;
                 sellBackPercentage: number | null;
                 stock: number | null;
                 isActive: boolean;
                 availableFrom: Date | null;
                 availableUntil: Date | null;
             }[]>;
-            updateListing: (listingId: string, props: UpdateShopListing) => Promise<{
+            update: (listingId: string, props: import("@playcademy/types").UpdateShopListing) => Promise<{
                 id: string;
                 createdAt: Date;
                 updatedAt: Date | null;
                 itemId: string;
                 currencyId: string;
-                priceAmountMinor: number;
+                price: number;
                 sellBackPercentage: number | null;
                 stock: number | null;
                 isActive: boolean;
                 availableFrom: Date | null;
                 availableUntil: Date | null;
             }>;
-            deleteListing: (listingId: string) => Promise<void>;
+            delete: (listingId: string) => Promise<void>;
         };
     };
+    /** Shop methods (view) */
     shop: {
-        view: () => Promise<ShopViewResponse>;
+        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;
 }