@playcademy/sdk 0.0.1-beta.9 → 0.0.2

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 { DevUploadHooks, 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 status methods.
+     */
+    status: {
+        /**
+         * Applies for developer status for the current user.
+         *
+         * @returns Promise that resolves when application is submitted
+         *
+         * @example
+         * ```typescript
+         * await client.dev.status.apply()
+         * console.log('Developer application submitted')
+         * ```
+         */
+        apply: () => Promise<void>;
+        /**
+         * Gets the current developer status for the user.
+         *
+         * @returns Promise resolving to developer status value
+         *
+         * @example
+         * ```typescript
+         * const status = await client.dev.status.get()
+         * if (status === 'approved') {
+         *   console.log('Developer access granted')
+         * }
+         * ```
+         */
+        get: () => 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 | null, hooks?: DevUploadHooks) => 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,173 @@
+import type { FetchedGame, Game, GameStateData, LeaderboardEntry } from '@playcademy/data/types';
+import type { GameTokenResponse, PlaycademyClient, StartSessionResponse } from '../../types';
+import type { TTLCacheConfig } from '../cache/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 for hosted games.
+     * For external games, returns the game data without a manifest.
+     *
+     * @param gameIdOrSlug - The game ID or slug to fetch
+     * @param options - Optional cache configuration (TTL/force)
+     * @returns Promise resolving to game data (with manifest for hosted games)
+     *
+     * @example
+     * ```typescript
+     * const game = await client.games.fetch('my-game-123')
+     * console.log('Game title:', game.displayName)
+     *
+     * // For hosted games:
+     * if ('manifest' in game) {
+     *     console.log('Assets:', game.manifest.assets)
+     * }
+     *
+     * // For external games:
+     * if (game.gameType === 'external') {
+     *     console.log('External URL:', game.externalUrl)
+     * }
+     * ```
+     */
+    fetch: (gameIdOrSlug: string, options?: TTLCacheConfig) => Promise<FetchedGame>;
+    /**
+     * Lists all available games.
+     * Results are cached for 60 seconds by default.
+     *
+     * @param options - Optional cache configuration
+     * @param options.ttl - Custom TTL in milliseconds (0 to disable caching)
+     * @param options.force - Force refresh the cache
+     * @returns Promise resolving to array of games
+     *
+     * @example
+     * ```typescript
+     * // Use default 60 second cache
+     * const games = await client.games.list()
+     *
+     * // Custom 5 minute cache for dashboard
+     * const dashboardGames = await client.games.list({ ttl: 300_000 })
+     *
+     * // Force refresh on user action
+     * const freshGames = await client.games.list({ force: true })
+     *
+     * // Disable caching for admin panel
+     * const uncachedGames = await client.games.list({ ttl: 0 })
+     * ```
+     */
+    list: (options?: TTLCacheConfig) => 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/identity.d.ts

@@ -0,0 +1,91 @@
+import type { AuthOptions, AuthResult, PlaycademyClient } from '../../types';
+/**
+ * Creates the identity namespace for the PlaycademyClient.
+ * Provides methods for connecting external identity providers.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Identity namespace with connection methods
+ */
+export declare function createIdentityNamespace(client: PlaycademyClient): {
+    /**
+     * Connects an external identity provider to the user's Playcademy account.
+     *
+     * For games in iframes: Uses popup flow to avoid navigation issues.
+     * For standalone apps: Uses redirect flow for traditional OAuth.
+     *
+     * @param options - Connection options including provider and callback URL
+     * @returns Promise resolving to the connection result
+     *
+     * @example
+     * ```typescript
+     * // Connect TimeBack identity
+     * const result = await client.identity.connect({
+     *     provider: AuthProvider.TIMEBACK,
+     *     callbackUrl: 'https://myapp.com/api/auth/callback',
+     *     onStateChange: (state) => {
+     *         console.log('Connection state:', state.message)
+     *     }
+     * })
+     *
+     * if (result.success) {
+     *     console.log('Connected as:', result.user.email)
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Force popup mode even in standalone context
+     * const result = await client.identity.connect({
+     *     provider: AuthProvider.TIMEBACK,
+     *     callbackUrl: 'https://myapp.com/api/auth/callback',
+     *     mode: 'popup'
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Provide custom OAuth configuration for external games
+     * const result = await client.identity.connect({
+     *     provider: AuthProvider.TIMEBACK,
+     *     callbackUrl: 'https://myapp.com/api/auth/callback',
+     *     oauth: {
+     *         clientId: 'my-oauth-client-id',
+     *         // Optional: override default endpoints
+     *         authorizationEndpoint: 'https://custom-idp.com/oauth2/authorize',
+     *         tokenEndpoint: 'https://custom-idp.com/oauth2/token',
+     *         scope: 'openid email profile custom_scope'
+     *     }
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // The SDK automatically includes Playcademy user ID in the OAuth state
+     * const result = await client.identity.connect({
+     *     provider: AuthProvider.TIMEBACK,
+     *     callbackUrl: 'https://myapp.com/api/auth/callback'
+     * })
+     *
+     * // On your server callback, parse the state to get the user ID:
+     * import { PlaycademyClient } from '@playcademy/sdk'
+     *
+     * app.get('/api/auth/callback', async (req, res) => {
+     *     const { csrfToken, data } = PlaycademyClient.identity.parseOAuthState(req.query.state)
+     *     const playcademyUserId = data?.playcademy_user_id
+     *     const gameId = data?.game_id
+     *
+     *     // Now you can associate the OAuth user with the Playcademy user
+     *     await linkAccounts(oauthUserId, playcademyUserId)
+     * })
+     * ```
+     */
+    connect: (options: AuthOptions) => Promise<AuthResult>;
+    /**
+     * Gets the current identity connection context (for internal use).
+     *
+     * @internal
+     */
+    _getContext: () => {
+        isInIframe: boolean;
+    };
+};

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

@@ -0,0 +1,19 @@
+export { createAuthNamespace } from './auth';
+export { createIdentityNamespace } from './identity';
+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';
+export { createAchievementsNamespace } from './achievements';
+export { createTimebackNamespace } from './timeback';

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