@playcademy/sdk 0.0.1-beta.16 → 0.0.1-beta.18

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";
+    }[]>;
+};

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

@@ -0,0 +1,45 @@
+import type { PlaycademyClient } from '../client';
+import type { GameTokenResponse } from '../../types';
+/**
+ * Creates the runtime namespace for the PlaycademyClient.
+ * Provides methods for managing game runtime operations and lifecycle.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Runtime namespace with game token and exit methods
+ */
+export declare function createRuntimeNamespace(client: PlaycademyClient): {
+    /**
+     * Retrieves a game token for the specified game.
+     * Optionally applies the token to the current client instance.
+     *
+     * @param gameId - The ID of the game to get a token for
+     * @param options - Optional configuration
+     * @param options.apply - Whether to automatically apply the token to this client
+     * @returns Promise resolving to game token response
+     *
+     * @example
+     * ```typescript
+     * // Get token without applying it
+     * const tokenResponse = await client.runtime.getGameToken('game-123')
+     *
+     * // Get token and apply it to current client
+     * const tokenResponse = await client.runtime.getGameToken('game-123', { apply: true })
+     * ```
+     */
+    getGameToken: (gameId: string, options?: {
+        apply?: boolean;
+    }) => Promise<GameTokenResponse>;
+    /**
+     * Gracefully exits the game runtime.
+     * Automatically ends any active game session and emits an exit event.
+     *
+     * @returns Promise that resolves when exit is complete
+     *
+     * @example
+     * ```typescript
+     * // Clean up and exit the game
+     * await client.runtime.exit()
+     * ```
+     */
+    exit: () => Promise<void>;
+};

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

@@ -0,0 +1,26 @@
+import type { PlaycademyClient } from '../client';
+import type { ShopViewResponse } from '../../types';
+/**
+ * Creates the shop namespace for the PlaycademyClient.
+ * Provides methods for viewing shop listings and items available for purchase.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Shop namespace with view methods
+ */
+export declare function createShopNamespace(client: PlaycademyClient): {
+    /**
+     * Retrieves the current shop view with available listings.
+     * Returns all items currently available for purchase in the shop.
+     *
+     * @returns Promise resolving to shop view data with listings
+     *
+     * @example
+     * ```typescript
+     * const shopData = await client.shop.view()
+     * shopData.listings.forEach(listing => {
+     *   console.log(`${listing.item.name}: ${listing.price} ${listing.currency.symbol}`)
+     * })
+     * ```
+     */
+    view: () => Promise<ShopViewResponse>;
+};

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

@@ -0,0 +1,28 @@
+import type { PlaycademyClient } from '../client';
+/**
+ * Creates the telemetry namespace for the PlaycademyClient.
+ * Provides methods for sending analytics and metrics data to the platform.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Telemetry namespace with metrics methods
+ */
+export declare function createTelemetryNamespace(client: PlaycademyClient): {
+    /**
+     * Sends custom metrics data to the telemetry system.
+     * Useful for tracking game events, performance metrics, and analytics.
+     *
+     * @param metrics - Object containing metric names and their numeric values
+     * @returns Promise that resolves when metrics are successfully sent
+     *
+     * @example
+     * ```typescript
+     * await client.telemetry.pushMetrics({
+     *   'level_completed': 1,
+     *   'score': 1250,
+     *   'time_played_seconds': 180,
+     *   'enemies_defeated': 15
+     * })
+     * ```
+     */
+    pushMetrics: (metrics: Record<string, number>) => Promise<void>;
+};

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

@@ -0,0 +1,84 @@
+import type { InventoryItemWithItem, InventoryMutationResponse } from '../../types';
+import type { PlaycademyClient } from '../client';
+/**
+ * Creates the users namespace for the PlaycademyClient.
+ * Provides methods for managing user data and inventory operations.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Users namespace with user profile and inventory methods
+ */
+export declare function createUsersNamespace(client: PlaycademyClient): {
+    /**
+     * Retrieves the current user's profile information.
+     *
+     * @returns Promise resolving to user profile data
+     *
+     * @example
+     * ```typescript
+     * const user = await client.users.me()
+     * console.log('Username:', user.username)
+     * console.log('Email:', user.email)
+     * ```
+     */
+    me: () => Promise<{
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        name: string;
+        username: string | null;
+        email: string;
+        emailVerified: boolean;
+        image: string | null;
+        role: "admin" | "player" | "developer";
+        developerStatus: "none" | "pending" | "approved";
+    }>;
+    /**
+     * Inventory management methods for the current user.
+     */
+    inventory: {
+        /**
+         * Retrieves the user's complete inventory.
+         *
+         * @returns Promise resolving to array of inventory items with item details
+         *
+         * @example
+         * ```typescript
+         * const inventory = await client.users.inventory.get()
+         * inventory.forEach(item => {
+         *   console.log(`${item.item.name}: ${item.quantity}`)
+         * })
+         * ```
+         */
+        get: () => Promise<InventoryItemWithItem[]>;
+        /**
+         * Adds items to the user's inventory.
+         * Emits an 'inventoryChange' event when successful.
+         *
+         * @param itemId - The ID of the item to add
+         * @param qty - The quantity to add (must be positive)
+         * @returns Promise resolving to mutation response with new total
+         *
+         * @example
+         * ```typescript
+         * const result = await client.users.inventory.add('gold-coin', 100)
+         * console.log('New total:', result.newTotal)
+         * ```
+         */
+        add: (itemId: string, qty: number) => Promise<InventoryMutationResponse>;
+        /**
+         * Spends (removes) items from the user's inventory.
+         * Emits an 'inventoryChange' event when successful.
+         *
+         * @param itemId - The ID of the item to spend
+         * @param qty - The quantity to spend (must be positive)
+         * @returns Promise resolving to mutation response with new total
+         *
+         * @example
+         * ```typescript
+         * const result = await client.users.inventory.spend('health-potion', 1)
+         * console.log('Remaining potions:', result.newTotal)
+         * ```
+         */
+        spend: (itemId: string, qty: number) => Promise<InventoryMutationResponse>;
+    };
+};

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

@@ -0,0 +1,2 @@
+export { init } from './init';
+export { login } from './login';

package/dist/core/static/init.d.ts

@@ -0,0 +1,21 @@
+import type { PlaycademyClient } from '../client';
+/**
+ * Auto-initializes a PlaycademyClient with context from the environment.
+ * Works in both iframe mode (production/development) and standalone mode (local dev).
+ *
+ * This is the recommended way to initialize the SDK as it automatically:
+ * - Detects the runtime environment (iframe vs standalone)
+ * - Configures the client with the appropriate context
+ * - Sets up event listeners for token refresh
+ * - Exposes the client for debugging in development mode
+ *
+ * @returns Promise resolving to a fully initialized PlaycademyClient
+ * @throws Error if not running in a browser context
+ *
+ * @example
+ * ```typescript
+ * const client = await PlaycademyClient.init()
+ * const user = await client.users.me()
+ * ```
+ */
+export declare function init(): Promise<PlaycademyClient>;

package/dist/core/static/login.d.ts

@@ -0,0 +1,24 @@
+import type { LoginResponse } from '../../types';
+/**
+ * Authenticates a user with email and password.
+ *
+ * This is a standalone authentication method that doesn't require an initialized client.
+ * Use this for login flows before creating a client instance.
+ *
+ * @param baseUrl - The base URL of the Playcademy API
+ * @param email - User's email address
+ * @param password - User's password
+ * @returns Promise resolving to authentication response with token
+ * @throws PlaycademyError if authentication fails or network error occurs
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
+ *   const client = new PlaycademyClient({ token: response.token })
+ * } catch (error) {
+ *   console.error('Login failed:', error.message)
+ * }
+ * ```
+ */
+export declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Playcademy SDK - Main Entry Point
+ *
+ * This file serves as the primary entry point for the Playcademy SDK,
+ * providing access to the main client class and supporting utilities.
+ */
+export { PlaycademyClient } from './core/client';
+export { messaging, MessageEvents } from './messaging';
+export type * from './types';