@playcademy/sdk 0.0.1-beta.3 → 0.0.1-beta.31

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

@@ -0,0 +1,323 @@
+import type { DeveloperStatusValue, Game, InsertItemInput, InsertShopListingInput, Item, ShopListing, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput } from '@playcademy/data/types';
+import type { PlaycademyClient } from '../../types';
+/**
+ * Creates the developer namespace for the PlaycademyClient.
+ * Provides methods for developer account management, game publishing, API key management, and item management.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Developer namespace with auth, games, keys, and items 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.getStatus()
+         * if (status === 'approved') {
+         *   console.log('Developer access granted')
+         * }
+         * ```
+         */
+        getStatus: () => 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', {
+         *   displayName: 'My Awesome Game',
+         *   platform: 'web',
+         *   metadata: { 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 the developer.
+         *
+         * @param label - Optional label for the key
+         * @returns Promise resolving to the created API key
+         *
+         * @example
+         * ```typescript
+         * const key = await client.dev.keys.create('Production Key')
+         * console.log('API Key:', key.apiKey)
+         * ```
+         */
+        create: (label?: string) => Promise<{
+            id: string;
+            createdAt: Date;
+            userId: string;
+            label: string | null;
+            keyHash: string;
+        }>;
+        /**
+         * Lists all API keys for the developer.
+         *
+         * @returns Promise resolving to array of API keys
+         *
+         * @example
+         * ```typescript
+         * const keys = await client.dev.keys.list()
+         * keys.forEach(key => console.log(`${key.label}: ${key.id}`))
+         * ```
+         */
+        list: () => 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.revoke('key-456')
+         * console.log('API key revoked')
+         * ```
+         */
+        revoke: (keyId: string) => Promise<void>;
+    };
+    /**
+     * Item management methods for developers.
+     * Allows developers to create and manage game-specific items.
+     */
+    items: {
+        /**
+         * Creates a new game-scoped item.
+         *
+         * @param gameId - The game ID to create the item for
+         * @param slug - The item slug (unique within the game)
+         * @param itemData - Item properties (displayName, description, type, etc.)
+         * @returns Promise resolving to the created item
+         *
+         * @example
+         * ```typescript
+         * const item = await client.dev.items.create('game-123', 'MAGIC_SWORD', {
+         *   displayName: 'Magic Sword',
+         *   description: 'A powerful enchanted blade',
+         *   type: 'unlock',
+         *   metadata: { rarity: 'epic' }
+         * })
+         * ```
+         */
+        create: (gameId: string, slug: string, itemData: Omit<InsertItemInput, "slug" | "gameId">) => Promise<Item>;
+        /**
+         * Updates an existing game-scoped item.
+         *
+         * @param gameId - The game ID
+         * @param itemId - The item ID to update
+         * @param updates - Partial item properties to update
+         * @returns Promise resolving to the updated item
+         *
+         * @example
+         * ```typescript
+         * const updated = await client.dev.items.update('game-123', 'item-456', {
+         *   displayName: 'Super Magic Sword',
+         *   metadata: { rarity: 'legendary' }
+         * })
+         * ```
+         */
+        update: (gameId: string, itemId: string, updates: UpdateItemInput) => Promise<Item>;
+        /**
+         * Lists all items for a specific game.
+         *
+         * @param gameId - The game ID to list items for
+         * @returns Promise resolving to array of game-scoped items
+         *
+         * @example
+         * ```typescript
+         * const items = await client.dev.items.list('game-123')
+         * items.forEach(item => console.log(`${item.slug}: ${item.displayName}`))
+         * ```
+         */
+        list: (gameId: string) => Promise<Array<Item>>;
+        /**
+         * Gets a specific item by slug within a game context.
+         * Uses the resolution endpoint to find the item.
+         *
+         * @param gameId - The game ID context
+         * @param slug - The item slug to retrieve
+         * @returns Promise resolving to the item
+         *
+         * @example
+         * ```typescript
+         * const item = await client.dev.items.get('game-123', 'MAGIC_SWORD')
+         * console.log('Item:', item.displayName)
+         * ```
+         */
+        get: (gameId: string, slug: string) => Promise<Item>;
+        /**
+         * Deletes a game-scoped item.
+         *
+         * @param gameId - The game ID
+         * @param itemId - The item ID to delete
+         * @returns Promise that resolves when item is deleted
+         *
+         * @example
+         * ```typescript
+         * await client.dev.items.delete('game-123', 'item-456')
+         * console.log('Item deleted successfully')
+         * ```
+         */
+        delete: (gameId: string, itemId: string) => Promise<void>;
+        /**
+         * Shop listing management for game items.
+         * Allows developers to control if and how their items are sold.
+         */
+        shop: {
+            /**
+             * Creates a shop listing for a game item.
+             *
+             * @param gameId - The game ID
+             * @param itemId - The item ID to list for sale
+             * @param listingData - Shop listing properties (price, currency, etc.)
+             * @returns Promise resolving to the created shop listing
+             *
+             * @example
+             * ```typescript
+             * const listing = await client.dev.items.shop.create('game-123', 'item-456', {
+             *   currencyId: 'credits-currency-id',
+             *   price: 100,
+             *   sellBackPercentage: 50,
+             *   isActive: true
+             * })
+             * ```
+             */
+            create: (gameId: string, itemId: string, listingData: Omit<InsertShopListingInput, "itemId">) => Promise<ShopListing>;
+            /**
+             * Gets the shop listing for a specific game item.
+             *
+             * @param gameId - The game ID
+             * @param itemId - The item ID
+             * @returns Promise resolving to the shop listing, or null if no listing exists
+             *
+             * @example
+             * ```typescript
+             * const listing = await client.dev.items.shop.get('game-123', 'item-456')
+             * if (listing) {
+             *   console.log(`Item is listed for ${listing.price} credits`)
+             * }
+             * ```
+             */
+            get: (gameId: string, itemId: string) => Promise<ShopListing | null>;
+            /**
+             * Updates an existing shop listing for a game item.
+             *
+             * @param gameId - The game ID
+             * @param itemId - The item ID
+             * @param updates - Partial shop listing properties to update
+             * @returns Promise resolving to the updated shop listing
+             *
+             * @example
+             * ```typescript
+             * const updated = await client.dev.items.shop.update('game-123', 'item-456', {
+             *   price: 150,
+             *   isActive: false
+             * })
+             * ```
+             */
+            update: (gameId: string, itemId: string, updates: UpdateShopListingInput) => Promise<ShopListing>;
+            /**
+             * Removes the shop listing for a game item.
+             *
+             * @param gameId - The game ID
+             * @param itemId - The item ID
+             * @returns Promise that resolves when listing is removed
+             *
+             * @example
+             * ```typescript
+             * await client.dev.items.shop.delete('game-123', 'item-456')
+             * console.log('Item removed from shop')
+             * ```
+             */
+            delete: (gameId: string, itemId: string) => Promise<void>;
+            /**
+             * Lists all shop listings for a game.
+             *
+             * @param gameId - The game ID
+             * @returns Promise resolving to array of shop listings for the game
+             *
+             * @example
+             * ```typescript
+             * const listings = await client.dev.items.shop.list('game-123')
+             * listings.forEach(listing => {
+             *   console.log(`${listing.item.displayName}: ${listing.price}`)
+             * })
+             * ```
+             */
+            list: (gameId: string) => Promise<Array<ShopListing & {
+                item: Item;
+            }>>;
+        };
+    };
+};

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

@@ -0,0 +1,149 @@
+import type { Game, GameStateData, GameWithManifest, LeaderboardEntry } from '@playcademy/data/types';
+import type { GameTokenResponse, PlaycademyClient, 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 data
+     *
+     * @example
+     * ```typescript
+     * const state = await client.games.loadState()
+     * console.log('Current level:', state.level)
+     * ```
+     */
+    loadState: () => Promise<GameStateData>;
+    /**
+     * 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>;
+    /**
+     * Token management sub-namespace
+     */
+    token: {
+        /**
+         * Creates a game token for the specified game.
+         * This method replaces the old runtime.getGameToken() method.
+         *
+         * @param gameId - The ID of the game to create 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
+         * // Create token without applying it
+         * const tokenResponse = await client.games.token.create('game-123')
+         *
+         * // Create token and apply it to current client
+         * const tokenResponse = await client.games.token.create('game-123', { apply: true })
+         * ```
+         */
+        create: (gameId: string, options?: {
+            apply?: boolean;
+        }) => Promise<GameTokenResponse>;
+    };
+    /**
+     * Leaderboard sub-namespace
+     */
+    leaderboard: {
+        /**
+         * Gets the leaderboard for a specific game.
+         *
+         * @param gameId - The ID of the game to get leaderboard for
+         * @param options - Optional query parameters
+         * @param options.limit - Maximum number of entries to return
+         * @param options.offset - Number of entries to skip
+         * @returns Promise resolving to array of leaderboard entries
+         *
+         * @example
+         * ```typescript
+         * // Get top 10 scores
+         * const leaderboard = await client.games.leaderboard.get('game-123', { limit: 10 })
+         *
+         * // Get next 10 scores
+         * const moreScores = await client.games.leaderboard.get('game-123', { limit: 10, offset: 10 })
+         * ```
+         */
+        get: (gameId: string, options?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<LeaderboardEntry[]>;
+    };
+};

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

@@ -0,0 +1,16 @@
+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';
+export { createLevelsNamespace } from './levels';
+export { createCreditsNamespace } from './credits';
+export { createLeaderboardNamespace } from './leaderboard';
+export { createScoresNamespace } from './scores';
+export { createCharacterNamespace } from './character';
+export { createSpritesNamespace } from './sprites';
+export { createRealtimeNamespace } from './realtime';

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

@@ -0,0 +1,48 @@
+import type { GameLeaderboardEntry, LeaderboardOptions, UserRankResponse } from '@playcademy/data/types';
+import type { PlaycademyClient } from '../../types';
+/**
+ * Creates the leaderboard namespace for the PlaycademyClient.
+ * Provides methods for accessing game-specific leaderboards.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Leaderboard namespace with fetch methods
+ */
+export declare function createLeaderboardNamespace(client: PlaycademyClient): {
+    /**
+     * Fetches the leaderboard for a specific game.
+     * Note: gameId is required as cross-game score comparisons are not meaningful.
+     *
+     * @param options - Query options for the leaderboard (gameId is required)
+     * @returns Promise resolving to array of leaderboard entries
+     *
+     * @example
+     * ```typescript
+     * // Get top 10 players for a specific game
+     * const gameTop10 = await client.leaderboard.fetch({
+     *   gameId: 'game-123',
+     *   limit: 10
+     * })
+     *
+     * // Get weekly leaderboard for a specific game
+     * const weeklyGameLeaderboard = await client.leaderboard.fetch({
+     *   timeframe: 'weekly',
+     *   gameId: 'game-123'
+     * })
+     * ```
+     */
+    fetch: (options?: LeaderboardOptions) => Promise<GameLeaderboardEntry[]>;
+    /**
+     * Gets the rank of a specific user within a game's leaderboard.
+     *
+     * @param gameId - The game ID to get the user's rank for
+     * @param userId - The user ID to get the rank for
+     * @returns Promise resolving to user rank information
+     *
+     * @example
+     * ```typescript
+     * const userRank = await client.leaderboard.getUserRank('game-123', 'user-456')
+     * console.log(`User is rank ${userRank.rank} with score ${userRank.score}`)
+     * ```
+     */
+    getUserRank: (gameId: string, userId: string) => Promise<UserRankResponse>;
+};

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

@@ -0,0 +1,93 @@
+import type { LevelConfig, UserLevel, XPAddResult } from '@playcademy/data/types';
+import type { PlaycademyClient } from '../../types';
+/**
+ * Creates the levels namespace for the PlaycademyClient.
+ * Provides methods for managing user levels and experience points.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Levels namespace with level and XP methods
+ */
+export declare function createLevelsNamespace(client: PlaycademyClient): {
+    /**
+     * Retrieves the current user's level information.
+     *
+     * @returns Promise resolving to user level data
+     *
+     * @example
+     * ```typescript
+     * const userLevel = await client.levels.get()
+     * console.log('Current level:', userLevel.currentLevel)
+     * console.log('Current XP:', userLevel.currentXp)
+     * console.log('Total XP earned:', userLevel.totalXP)
+     * ```
+     */
+    get: () => Promise<UserLevel>;
+    /**
+     * Retrieves the current user's level progress information.
+     *
+     * @returns Promise resolving to level progress data
+     *
+     * @example
+     * ```typescript
+     * const progress = await client.levels.progress()
+     * console.log('Level:', progress.level)
+     * console.log('XP to next level:', progress.xpToNextLevel)
+     * ```
+     */
+    progress: () => Promise<{
+        level: number;
+        currentXp: number;
+        xpToNextLevel: number;
+        totalXP: number;
+    }>;
+    /**
+     * Adds XP to the current user.
+     * Emits 'xpGained' and 'levelUp' events when successful.
+     *
+     * @param amount - The amount of XP to add (must be positive)
+     * @returns Promise resolving to XP addition result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.levels.addXP(100)
+     * console.log('New level:', result.newLevel)
+     * console.log('Leveled up:', result.leveledUp)
+     * console.log('Credits awarded:', result.creditsAwarded)
+     * ```
+     */
+    addXP: (amount: number) => Promise<XPAddResult>;
+    /**
+     * Configuration methods for level system.
+     */
+    config: {
+        /**
+         * Retrieves all level configurations (full XP curve).
+         *
+         * @returns Promise resolving to array of level configurations
+         *
+         * @example
+         * ```typescript
+         * const configs = await client.levels.config.list()
+         * configs.forEach(config => {
+         *   console.log(`Level ${config.level}: ${config.xpRequired} XP, ${config.creditsReward} credits`)
+         * })
+         * ```
+         */
+        list: () => Promise<LevelConfig[]>;
+        /**
+         * Retrieves configuration for a specific level.
+         *
+         * @param level - The level number to get configuration for
+         * @returns Promise resolving to level configuration or null if not found
+         *
+         * @example
+         * ```typescript
+         * const config = await client.levels.config.get(10)
+         * if (config) {
+         *   console.log(`Level 10 requires ${config.xpRequired} XP`)
+         * }
+         * ```
+         */
+        get: (level: number) => Promise<LevelConfig | null>;
+    };
+};