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

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>;
+    };
+};

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

@@ -0,0 +1,23 @@
+import type { PlaycademyClient } from '../client';
+/**
+ * Creates the authentication namespace for the PlaycademyClient.
+ * Provides methods for managing user authentication state.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Authentication namespace with logout method
+ */
+export declare function createAuthNamespace(client: PlaycademyClient): {
+    /**
+     * Logs out the current user and clears the authentication token.
+     * Sends a logout request to the server and removes the token from the client.
+     *
+     * @returns Promise that resolves when logout is complete
+     *
+     * @example
+     * ```typescript
+     * await client.auth.logout()
+     * console.log('User logged out successfully')
+     * ```
+     */
+    logout: () => Promise<void>;
+};

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

@@ -0,0 +1,152 @@
+import type { PlaycademyClient } from '../client';
+import type { Game, UpsertGameMetadataInput } from '@playcademy/types';
+import type { DeveloperStatusValue } from '../../types';
+/**
+ * Creates the developer namespace for the PlaycademyClient.
+ * Provides methods for developer account management, game publishing, and API key management.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Developer namespace with auth, games, and keys methods
+ */
+export declare function createDevNamespace(client: PlaycademyClient): {
+    /**
+     * Developer authentication and status methods.
+     */
+    auth: {
+        /**
+         * Applies for developer status for the current user.
+         *
+         * @returns Promise that resolves when application is submitted
+         *
+         * @example
+         * ```typescript
+         * await client.dev.auth.applyForDeveloper()
+         * console.log('Developer application submitted')
+         * ```
+         */
+        applyForDeveloper: () => Promise<void>;
+        /**
+         * Gets the current developer status for the user.
+         *
+         * @returns Promise resolving to developer status value
+         *
+         * @example
+         * ```typescript
+         * const status = await client.dev.auth.getDeveloperStatus()
+         * if (status === 'approved') {
+         *   console.log('Developer access granted')
+         * }
+         * ```
+         */
+        getDeveloperStatus: () => Promise<DeveloperStatusValue>;
+    };
+    /**
+     * Game management methods for developers.
+     */
+    games: {
+        /**
+         * Creates or updates a game with metadata and asset bundle.
+         *
+         * @param slug - The game slug (URL-friendly identifier)
+         * @param metadata - Game metadata (title, description, etc.)
+         * @param file - Game asset bundle file (zip)
+         * @returns Promise resolving to the created/updated game
+         *
+         * @example
+         * ```typescript
+         * const gameFile = new File([zipData], 'game.zip')
+         * const game = await client.dev.games.upsert('my-game', {
+         *   title: 'My Awesome Game',
+         *   description: 'A fun puzzle game'
+         * }, gameFile)
+         * ```
+         */
+        upsert: (slug: string, metadata: UpsertGameMetadataInput, file: File | Blob) => Promise<Game>;
+        /**
+         * Updates specific properties of an existing game.
+         *
+         * @param gameId - The game ID to update
+         * @param props - Partial game properties to update
+         * @returns Promise that resolves when update is complete
+         *
+         * @example
+         * ```typescript
+         * await client.dev.games.update('game-123', {
+         *   title: 'Updated Game Title',
+         *   isPublic: true
+         * })
+         * ```
+         */
+        update: (gameId: string, props: Partial<Game>) => Promise<void>;
+        /**
+         * Deletes a game permanently.
+         *
+         * @param gameId - The game ID to delete
+         * @returns Promise that resolves when deletion is complete
+         *
+         * @example
+         * ```typescript
+         * await client.dev.games.delete('game-123')
+         * console.log('Game deleted successfully')
+         * ```
+         */
+        delete: (gameId: string) => Promise<void>;
+    };
+    /**
+     * API key management methods for developers.
+     */
+    keys: {
+        /**
+         * Creates a new API key for a game.
+         *
+         * @param gameId - The game ID to create a key for
+         * @param label - Optional label for the key
+         * @returns Promise resolving to the created API key
+         *
+         * @example
+         * ```typescript
+         * const key = await client.dev.keys.createKey('game-123', 'Production Key')
+         * console.log('API Key:', key.key)
+         * ```
+         */
+        createKey: (gameId: string, label?: string) => Promise<{
+            id: string;
+            createdAt: Date;
+            userId: string;
+            label: string | null;
+            keyHash: string;
+        }>;
+        /**
+         * Lists all API keys for a game.
+         *
+         * @param gameId - The game ID to list keys for
+         * @returns Promise resolving to array of API keys
+         *
+         * @example
+         * ```typescript
+         * const keys = await client.dev.keys.listKeys('game-123')
+         * keys.forEach(key => console.log(`${key.label}: ${key.key}`))
+         * ```
+         */
+        listKeys: (gameId: string) => Promise<{
+            id: string;
+            createdAt: Date;
+            userId: string;
+            label: string | null;
+            keyHash: string;
+        }[]>;
+        /**
+         * Revokes (deletes) an API key.
+         *
+         * @param keyId - The key ID to revoke
+         * @returns Promise that resolves when key is revoked
+         *
+         * @example
+         * ```typescript
+         * await client.dev.keys.revokeKey('key-456')
+         * console.log('API key revoked')
+         * ```
+         */
+        revokeKey: (keyId: string) => Promise<void>;
+    };
+};

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

@@ -0,0 +1,97 @@
+import type { PlaycademyClient } from '../client';
+import type { Game, GameWithManifest } from '@playcademy/types';
+import type { GameState, StartSessionResponse } from '../../types';
+/**
+ * Creates the games namespace for the PlaycademyClient.
+ * Provides methods for managing games, game state, and game sessions.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Games namespace with fetch, list, state, and session methods
+ */
+export declare function createGamesNamespace(client: PlaycademyClient): {
+    /**
+     * Fetches a game by ID or slug, including its manifest data.
+     * Combines game metadata with the game's asset manifest.
+     *
+     * @param gameIdOrSlug - The game ID or slug to fetch
+     * @returns Promise resolving to game data with manifest
+     *
+     * @example
+     * ```typescript
+     * const game = await client.games.fetch('my-game-123')
+     * console.log('Game title:', game.title)
+     * console.log('Assets:', game.manifest.assets)
+     * ```
+     */
+    fetch: (gameIdOrSlug: string) => Promise<GameWithManifest>;
+    /**
+     * Lists all available games.
+     *
+     * @returns Promise resolving to array of games
+     *
+     * @example
+     * ```typescript
+     * const games = await client.games.list()
+     * games.forEach(game => console.log(game.title))
+     * ```
+     */
+    list: () => Promise<Array<Game>>;
+    /**
+     * Saves the current game state to the server.
+     * Requires a gameId to be configured in the client.
+     *
+     * @param state - The game state object to save
+     * @returns Promise that resolves when state is saved
+     *
+     * @example
+     * ```typescript
+     * await client.games.saveState({
+     *   level: 5,
+     *   score: 1250,
+     *   inventory: ['sword', 'potion']
+     * })
+     * ```
+     */
+    saveState: (state: Record<string, unknown>) => Promise<void>;
+    /**
+     * Loads the saved game state from the server.
+     * Requires a gameId to be configured in the client.
+     *
+     * @returns Promise resolving to the saved game state
+     *
+     * @example
+     * ```typescript
+     * const state = await client.games.loadState()
+     * console.log('Current level:', state.level)
+     * ```
+     */
+    loadState: () => Promise<GameState>;
+    /**
+     * Starts a new game session.
+     *
+     * @param gameId - Optional game ID (uses client's gameId if not provided)
+     * @returns Promise resolving to session information
+     *
+     * @example
+     * ```typescript
+     * const session = await client.games.startSession('game-123')
+     * console.log('Session ID:', session.sessionId)
+     * ```
+     */
+    startSession: (gameId?: string) => Promise<StartSessionResponse>;
+    /**
+     * Ends an active game session.
+     * Automatically clears internal session tracking if ending the client's own session.
+     *
+     * @param sessionId - The session ID to end
+     * @param gameId - Optional game ID (uses client's gameId if not provided)
+     * @returns Promise that resolves when session is ended
+     *
+     * @example
+     * ```typescript
+     * await client.games.endSession('session-456', 'game-123')
+     * console.log('Session ended')
+     * ```
+     */
+    endSession: (sessionId: string, gameId?: string) => Promise<void>;
+};

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

@@ -0,0 +1,9 @@
+export { createAuthNamespace } from './auth';
+export { createRuntimeNamespace } from './runtime';
+export { createGamesNamespace } from './games';
+export { createUsersNamespace } from './users';
+export { createDevNamespace } from './dev';
+export { createMapsNamespace } from './maps';
+export { createAdminNamespace } from './admin';
+export { createShopNamespace } from './shop';
+export { createTelemetryNamespace } from './telemetry';

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

@@ -0,0 +1,37 @@
+import type { PlaycademyClient } from '../client';
+/**
+ * Creates the maps namespace for the PlaycademyClient.
+ * Provides methods for retrieving map data and elements.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Maps namespace with element retrieval methods
+ */
+export declare function createMapsNamespace(client: PlaycademyClient): {
+    /**
+     * Retrieves all elements for a specific map.
+     *
+     * @param mapId - The ID of the map to get elements for
+     * @returns Promise resolving to array of map elements
+     *
+     * @example
+     * ```typescript
+     * const elements = await client.maps.elements('map-123')
+     * elements.forEach(element => {
+     *   console.log(`Element: ${element.type} at (${element.x}, ${element.y})`)
+     * })
+     * ```
+     */
+    elements: (mapId: string) => Promise<{
+        id: string;
+        metadata: ({
+            description?: string | undefined;
+            sourceTiledObjects?: Record<string, unknown>[] | undefined;
+        } & {
+            [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";
+    }[]>;
+};