@playcademy/sdk 0.0.1-beta.16 → 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,10 +249,10 @@ 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;
@@ -192,7 +265,7 @@ export declare class PlaycademyClient {
                 availableFrom: Date | null;
                 availableUntil: Date | null;
             }>;
-            getListing: (listingId: string) => Promise<{
+            get: (listingId: string) => Promise<{
                 id: string;
                 createdAt: Date;
                 updatedAt: Date | null;
@@ -205,7 +278,7 @@ export declare class PlaycademyClient {
                 availableFrom: Date | null;
                 availableUntil: Date | null;
             }>;
-            listListings: () => Promise<{
+            list: () => Promise<{
                 id: string;
                 createdAt: Date;
                 updatedAt: Date | null;
@@ -218,7 +291,7 @@ export declare class PlaycademyClient {
                 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;
@@ -231,15 +304,19 @@ export declare class PlaycademyClient {
                 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;
 }

package/dist/core/namespaces/admin.d.ts

@@ -0,0 +1,377 @@
+import type { PlaycademyClient } from '../client';
+import type { InsertItem, UpdateItem, InsertCurrency, UpdateCurrency, InsertShopListing, UpdateShopListing } from '../../types';
+/**
+ * Creates the admin namespace for the PlaycademyClient.
+ * Provides administrative methods for managing games, items, currencies, and shop listings.
+ * Requires admin privileges to access these endpoints.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Admin namespace with game, item, currency, and shop listing management methods
+ */
+export declare function createAdminNamespace(client: PlaycademyClient): {
+    /**
+     * Game administration methods.
+     */
+    games: {
+        /**
+         * Pauses a game, preventing new sessions from starting.
+         *
+         * @param gameId - The ID of the game to pause
+         * @returns Promise that resolves when game is paused
+         *
+         * @example
+         * ```typescript
+         * await client.admin.games.pauseGame('game-123')
+         * console.log('Game paused for maintenance')
+         * ```
+         */
+        pauseGame: (gameId: string) => Promise<void>;
+        /**
+         * Resumes a paused game, allowing new sessions to start.
+         *
+         * @param gameId - The ID of the game to resume
+         * @returns Promise that resolves when game is resumed
+         *
+         * @example
+         * ```typescript
+         * await client.admin.games.resumeGame('game-123')
+         * console.log('Game resumed')
+         * ```
+         */
+        resumeGame: (gameId: string) => Promise<void>;
+    };
+    /**
+     * Item management methods for administrators.
+     */
+    items: {
+        /**
+         * Creates a new item in the system.
+         *
+         * @param props - Item properties for creation
+         * @returns Promise resolving to the created item
+         *
+         * @example
+         * ```typescript
+         * const item = await client.admin.items.create({
+         *   name: 'Magic Sword',
+         *   description: 'A powerful weapon',
+         *   rarity: 'legendary'
+         * })
+         * ```
+         */
+        create: (props: InsertItem) => Promise<{
+            id: string;
+            displayName: string;
+            metadata: unknown;
+            createdAt: Date;
+            internalName: string;
+            description: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            imageUrl: string | null;
+        }>;
+        /**
+         * Retrieves a specific item by ID.
+         *
+         * @param itemId - The ID of the item to retrieve
+         * @returns Promise resolving to the item data
+         *
+         * @example
+         * ```typescript
+         * const item = await client.admin.items.get('item-123')
+         * console.log('Item name:', item.name)
+         * ```
+         */
+        get: (itemId: string) => Promise<{
+            id: string;
+            displayName: string;
+            metadata: unknown;
+            createdAt: Date;
+            internalName: string;
+            description: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            imageUrl: string | null;
+        }>;
+        /**
+         * Lists all items in the system.
+         *
+         * @returns Promise resolving to array of all items
+         *
+         * @example
+         * ```typescript
+         * const items = await client.admin.items.list()
+         * console.log(`Found ${items.length} items`)
+         * ```
+         */
+        list: () => Promise<{
+            id: string;
+            displayName: string;
+            metadata: unknown;
+            createdAt: Date;
+            internalName: string;
+            description: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            imageUrl: string | null;
+        }[]>;
+        /**
+         * Updates an existing item.
+         *
+         * @param itemId - The ID of the item to update
+         * @param props - Properties to update
+         * @returns Promise resolving to the updated item
+         *
+         * @example
+         * ```typescript
+         * const updatedItem = await client.admin.items.update('item-123', {
+         *   name: 'Enhanced Magic Sword'
+         * })
+         * ```
+         */
+        update: (itemId: string, props: UpdateItem) => Promise<{
+            id: string;
+            displayName: string;
+            metadata: unknown;
+            createdAt: Date;
+            internalName: string;
+            description: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            imageUrl: string | null;
+        }>;
+        /**
+         * Deletes an item from the system.
+         *
+         * @param itemId - The ID of the item to delete
+         * @returns Promise that resolves when item is deleted
+         *
+         * @example
+         * ```typescript
+         * await client.admin.items.delete('item-123')
+         * console.log('Item deleted')
+         * ```
+         */
+        delete: (itemId: string) => Promise<void>;
+    };
+    /**
+     * Currency management methods for administrators.
+     */
+    currencies: {
+        /**
+         * Creates a new currency in the system.
+         *
+         * @param props - Currency properties for creation
+         * @returns Promise resolving to the created currency
+         *
+         * @example
+         * ```typescript
+         * const currency = await client.admin.currencies.create({
+         *   name: 'Gold Coins',
+         *   symbol: 'GC',
+         *   decimals: 0
+         * })
+         * ```
+         */
+        create: (props: InsertCurrency) => Promise<{
+            symbol: string | null;
+            id: string;
+            createdAt: Date;
+            updatedAt: Date | null;
+            itemId: string;
+            isPrimary: boolean;
+        }>;
+        /**
+         * Retrieves a specific currency by ID.
+         *
+         * @param currencyId - The ID of the currency to retrieve
+         * @returns Promise resolving to the currency data
+         *
+         * @example
+         * ```typescript
+         * const currency = await client.admin.currencies.get('currency-123')
+         * console.log('Currency symbol:', currency.symbol)
+         * ```
+         */
+        get: (currencyId: string) => Promise<{
+            symbol: string | null;
+            id: string;
+            createdAt: Date;
+            updatedAt: Date | null;
+            itemId: string;
+            isPrimary: boolean;
+        }>;
+        /**
+         * Lists all currencies in the system.
+         *
+         * @returns Promise resolving to array of all currencies
+         *
+         * @example
+         * ```typescript
+         * const currencies = await client.admin.currencies.list()
+         * currencies.forEach(c => console.log(`${c.name}: ${c.symbol}`))
+         * ```
+         */
+        list: () => Promise<{
+            symbol: string | null;
+            id: string;
+            createdAt: Date;
+            updatedAt: Date | null;
+            itemId: string;
+            isPrimary: boolean;
+        }[]>;
+        /**
+         * Updates an existing currency.
+         *
+         * @param currencyId - The ID of the currency to update
+         * @param props - Properties to update
+         * @returns Promise resolving to the updated currency
+         *
+         * @example
+         * ```typescript
+         * const updatedCurrency = await client.admin.currencies.update('currency-123', {
+         *   name: 'Premium Gold Coins'
+         * })
+         * ```
+         */
+        update: (currencyId: string, props: UpdateCurrency) => Promise<{
+            symbol: string | null;
+            id: string;
+            createdAt: Date;
+            updatedAt: Date | null;
+            itemId: string;
+            isPrimary: boolean;
+        }>;
+        /**
+         * Deletes a currency from the system.
+         *
+         * @param currencyId - The ID of the currency to delete
+         * @returns Promise that resolves when currency is deleted
+         *
+         * @example
+         * ```typescript
+         * await client.admin.currencies.delete('currency-123')
+         * console.log('Currency deleted')
+         * ```
+         */
+        delete: (currencyId: string) => Promise<void>;
+    };
+    /**
+     * Shop listing management methods for administrators.
+     */
+    shopListings: {
+        /**
+         * Creates a new shop listing.
+         *
+         * @param props - Shop listing properties for creation
+         * @returns Promise resolving to the created shop listing
+         *
+         * @example
+         * ```typescript
+         * const listing = await client.admin.shopListings.create({
+         *   itemId: 'item-123',
+         *   price: 100,
+         *   currencyId: 'currency-456'
+         * })
+         * ```
+         */
+        create: (props: 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;
+        }>;
+        /**
+         * Retrieves a specific shop listing by ID.
+         *
+         * @param listingId - The ID of the shop listing to retrieve
+         * @returns Promise resolving to the shop listing data
+         *
+         * @example
+         * ```typescript
+         * const listing = await client.admin.shopListings.get('listing-123')
+         * console.log('Listing price:', listing.price)
+         * ```
+         */
+        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;
+        }>;
+        /**
+         * Lists all shop listings in the system.
+         *
+         * @returns Promise resolving to array of all shop listings
+         *
+         * @example
+         * ```typescript
+         * const listings = await client.admin.shopListings.list()
+         * console.log(`Found ${listings.length} shop listings`)
+         * ```
+         */
+        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;
+        }[]>;
+        /**
+         * Updates an existing shop listing.
+         *
+         * @param listingId - The ID of the shop listing to update
+         * @param props - Properties to update
+         * @returns Promise resolving to the updated shop listing
+         *
+         * @example
+         * ```typescript
+         * const updatedListing = await client.admin.shopListings.update('listing-123', {
+         *   price: 150
+         * })
+         * ```
+         */
+        update: (listingId: string, props: 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;
+        }>;
+        /**
+         * Deletes a shop listing from the system.
+         *
+         * @param listingId - The ID of the shop listing to delete
+         * @returns Promise that resolves when shop listing is deleted
+         *
+         * @example
+         * ```typescript
+         * await client.admin.shopListings.delete('listing-123')
+         * console.log('Shop listing deleted')
+         * ```
+         */
+        delete: (listingId: string) => Promise<void>;
+    };
+};