@playcademy/sdk 0.0.1-beta.9 → 0.0.2

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

@@ -0,0 +1,385 @@
+import type { InsertCurrencyInput, InsertItemInput, InsertShopListingInput, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput } from '@playcademy/data/types';
+import type { PlaycademyClient } 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: InsertItemInput) => Promise<{
+            description: string | null;
+            id: string;
+            createdAt: Date;
+            slug: string;
+            displayName: string;
+            metadata: unknown;
+            gameId: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            isPlaceable: boolean;
+            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<{
+            description: string | null;
+            id: string;
+            createdAt: Date;
+            slug: string;
+            displayName: string;
+            metadata: unknown;
+            gameId: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            isPlaceable: boolean;
+            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<{
+            description: string | null;
+            id: string;
+            createdAt: Date;
+            slug: string;
+            displayName: string;
+            metadata: unknown;
+            gameId: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            isPlaceable: boolean;
+            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: UpdateItemInput) => Promise<{
+            description: string | null;
+            id: string;
+            createdAt: Date;
+            slug: string;
+            displayName: string;
+            metadata: unknown;
+            gameId: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            isPlaceable: boolean;
+            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: InsertCurrencyInput) => 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: UpdateCurrencyInput) => 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: InsertShopListingInput) => 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: UpdateShopListingInput) => 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,54 @@
+import type { PlaycademyClient } from '../../types';
+/**
+ * Creates the authentication namespace for the PlaycademyClient.
+ * Provides methods for platform API authentication.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Authentication namespace with platform auth methods
+ */
+export declare function createAuthNamespace(client: PlaycademyClient): {
+    /**
+     * Authenticates with the Playcademy platform API using email and password.
+     * This is for server-side/CLI usage to obtain an API token.
+     *
+     * Note: This is different from client.identity.connect() which facilitates
+     * OAuth identity linking for end users.
+     *
+     * @param credentials - Email and password for platform authentication
+     * @returns Promise resolving to authentication result with token
+     *
+     * @example
+     * ```typescript
+     * const result = await client.auth.login({
+     *   email: 'developer@example.com',
+     *   password: 'secure-password'
+     * })
+     *
+     * if (result.success) {
+     *   // Token is automatically set on the client
+     *   const games = await client.games.list()
+     * }
+     * ```
+     */
+    login: (credentials: {
+        email: string;
+        password: string;
+    }) => Promise<{
+        success: boolean;
+        token?: string;
+        error?: string;
+    }>;
+    /**
+     * Logs out from the Playcademy platform API and clears the API token.
+     * This revokes the current API token on the server.
+     *
+     * @returns Promise that resolves when logout is complete
+     *
+     * @example
+     * ```typescript
+     * await client.auth.logout()
+     * console.log('Logged out from platform API')
+     * ```
+     */
+    logout: () => Promise<void>;
+};

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

@@ -0,0 +1,205 @@
+import type { CharacterComponentWithSpriteUrl, PlayerCharacter, PlayerCharacterAccessory } from '@playcademy/data/types';
+import type { PlaycademyClient } from '../../types';
+import type { TTLCacheConfig } from '../cache/types';
+export interface CharacterComponentsOptions {
+    /**
+     * Optional level filter for components
+     * When provided, only components available at this level or below are returned
+     */
+    level?: number;
+    /**
+     * Whether to bypass the cache and force a fresh API request
+     * Default: false (use cache when available)
+     */
+    skipCache?: boolean;
+}
+export interface CreateCharacterData {
+    bodyComponentId: string;
+    eyesComponentId: string;
+    hairstyleComponentId: string;
+    outfitComponentId: string;
+}
+export interface UpdateCharacterData {
+    bodyComponentId?: string;
+    eyesComponentId?: string;
+    hairstyleComponentId?: string;
+    outfitComponentId?: string;
+}
+/**
+ * Creates the character namespace for the PlaycademyClient.
+ * Provides methods for managing player character configuration and components.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Character namespace with get, create, update, and components methods
+ */
+export declare function createCharacterNamespace(client: PlaycademyClient): {
+    /**
+     * Gets a player character configuration.
+     *
+     * @param userId - Optional user ID. If omitted, gets the current user's character
+     * @returns Promise resolving to player character data or null if no character exists
+     *
+     * @example
+     * ```typescript
+     * // Get current user's character
+     * const myCharacter = await client.character.get()
+     *
+     * // Get a specific user's character
+     * const otherCharacter = await client.character.get('user-123')
+     *
+     * if (myCharacter) {
+     *   console.log('My character body:', myCharacter.bodyComponentId)
+     * }
+     * ```
+     */
+    get: (userId?: string) => Promise<PlayerCharacter | null>;
+    /**
+     * Creates a new player character.
+     *
+     * @param characterData - The character configuration data
+     * @returns Promise resolving to the created player character
+     *
+     * @example
+     * ```typescript
+     * const character = await client.character.create({
+     *   bodyComponentId: 'body-1',
+     *   eyesComponentId: 'eyes-2',
+     *   hairstyleComponentId: 'hair-3',
+     *   outfitComponentId: 'outfit-4',
+     *   accessoryComponentId: 'accessory-5'
+     * })
+     * console.log('Character created:', character.id)
+     * ```
+     */
+    create: (characterData: CreateCharacterData) => Promise<PlayerCharacter>;
+    /**
+     * Updates an existing player character.
+     *
+     * @param updates - Partial character data to update
+     * @returns Promise resolving to the updated player character
+     *
+     * @example
+     * ```typescript
+     * const updatedCharacter = await client.character.update({
+     *   hairstyleComponentId: 'new-hair-style',
+     *   outfitComponentId: 'new-outfit'
+     * })
+     * console.log('Character updated:', updatedCharacter.id)
+     * ```
+     */
+    update: (updates: UpdateCharacterData) => Promise<PlayerCharacter>;
+    /**
+     * Character components sub-namespace
+     */
+    components: {
+        /**
+         * Lists available character components with optional level filtering.
+         * Results are cached for 5 minutes by default.
+         *
+         * @param options - Optional filtering and cache configuration
+         * @param options.level - Filter components by required level
+         * @param options.ttl - Custom TTL in milliseconds (0 to disable caching)
+         * @param options.skipCache - Bypass the cache and force fresh data
+         * @returns Promise resolving to array of character components with sprite URLs
+         *
+         * @example
+         * ```typescript
+         * // Use default 5 minute cache
+         * const allComponents = await client.character.components.list()
+         *
+         * // Get components for level 5+ with custom 10 minute cache
+         * const levelComponents = await client.character.components.list({
+         *   level: 5,
+         *   ttl: 600_000
+         * })
+         *
+         * // Force fresh data from API
+         * const freshComponents = await client.character.components.list({ skipCache: true })
+         *
+         * // Disable caching for this call
+         * const uncached = await client.character.components.list({ ttl: 0 })
+         * ```
+         */
+        list: (options?: CharacterComponentsOptions & TTLCacheConfig) => Promise<CharacterComponentWithSpriteUrl[]>;
+        /**
+         * Clears the component cache.
+         * Useful when you know the component data has changed and want to force fresh data.
+         *
+         * @example
+         * ```typescript
+         * // Clear all cached component data
+         * client.character.components.clearCache()
+         *
+         * // Clear cache for specific level
+         * client.character.components.clearCache('5')
+         * ```
+         */
+        clearCache: (key?: string) => void;
+        /**
+         * Returns a list of all the component cache keys currently stored.
+         * Primarily useful for debugging and cache inspection.
+         *
+         * @returns Array of cache keys (e.g., ['all', '1', '5'])
+         *
+         * @example
+         * ```typescript
+         * // List all cache keys
+         * const cacheKeys = client.character.components.getCacheKeys()
+         * console.log('Cached levels:', cacheKeys)
+         * ```
+         */
+        getCacheKeys: () => string[];
+    };
+    /**
+     * Accessory management sub-namespace
+     */
+    accessories: {
+        /**
+         * Equip an accessory to a specific slot.
+         *
+         * @param slot - The slot to equip to ('head', 'face', 'hands', 'back')
+         * @param componentId - The accessory component ID to equip
+         * @returns Promise resolving to the equipped accessory data
+         *
+         * @example
+         * ```typescript
+         * // Equip glasses to the face slot
+         * const equipped = await client.character.accessories.equip('face', 'glasses-uuid')
+         * console.log('Equipped:', equipped)
+         * ```
+         */
+        equip: (slot: string, componentId: string) => Promise<PlayerCharacterAccessory>;
+        /**
+         * Remove an accessory from a specific slot.
+         *
+         * @param slot - The slot to remove from ('head', 'face', 'hands', 'back')
+         * @returns Promise resolving to success status
+         *
+         * @example
+         * ```typescript
+         * // Remove glasses from face slot
+         * const result = await client.character.accessories.remove('face')
+         * console.log('Removed:', result.success)
+         * ```
+         */
+        remove: (slot: string) => Promise<{
+            success: boolean;
+        }>;
+        /**
+         * Get all equipped accessories for the current player.
+         * Note: This is included automatically in character.get() with relations.
+         *
+         * @returns Promise resolving to array of equipped accessories
+         *
+         * @example
+         * ```typescript
+         * // Get all equipped accessories
+         * const accessories = await client.character.accessories.list()
+         * accessories.forEach(acc => {
+         *     console.log(`Slot ${acc.slot}: ${acc.accessoryComponent.displayName}`)
+         * })
+         * ```
+         */
+        list: () => Promise<PlayerCharacterAccessory[]>;
+    };
+};

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

@@ -0,0 +1,51 @@
+import type { PlaycademyClient } from '../../types';
+/**
+ * Creates the credits namespace for the PlaycademyClient.
+ * Provides convenient methods for working with Playcademy Credits (the primary platform currency).
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Credits namespace with balance and transaction methods
+ */
+export declare function createCreditsNamespace(client: PlaycademyClient): {
+    /**
+     * Gets the current balance of Playcademy Credits for the authenticated user.
+     * This is a convenience method that finds the primary currency in the user's inventory.
+     *
+     * @returns Promise resolving to the current credits balance
+     *
+     * @example
+     * ```typescript
+     * const balance = await client.credits.balance()
+     * console.log('Current credits:', balance)
+     * ```
+     */
+    balance: () => Promise<number>;
+    /**
+     * Adds Playcademy Credits to the user's inventory.
+     * This is a convenience method that automatically finds the credits item ID.
+     *
+     * @param amount - The amount of credits to add (must be positive)
+     * @returns Promise resolving to the new total balance
+     *
+     * @example
+     * ```typescript
+     * const newBalance = await client.credits.add(100)
+     * console.log('New balance after adding 100 credits:', newBalance)
+     * ```
+     */
+    add: (amount: number) => Promise<number>;
+    /**
+     * Spends (removes) Playcademy Credits from the user's inventory.
+     * This is a convenience method that automatically finds the credits item ID.
+     *
+     * @param amount - The amount of credits to spend (must be positive)
+     * @returns Promise resolving to the new total balance
+     *
+     * @example
+     * ```typescript
+     * const newBalance = await client.credits.spend(50)
+     * console.log('New balance after spending 50 credits:', newBalance)
+     * ```
+     */
+    spend: (amount: number) => Promise<number>;
+};