@playcademy/sdk 0.0.5 → 0.0.6

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

@@ -1,25 +0,0 @@
-import type { PlaycademyClient, 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/sprites.d.ts

@@ -1,35 +0,0 @@
-import type { SpriteTemplateData } from '@playcademy/data/types';
-import type { PlaycademyClient } from '../../types';
-/**
- * Creates the sprites namespace for the PlaycademyClient.
- * Provides methods for managing sprite templates and related data.
- *
- * @param client - The PlaycademyClient instance
- * @returns Sprites namespace with template methods
- */
-export declare function createSpritesNamespace(client: PlaycademyClient): {
-    /**
-     * Sprite templates sub-namespace
-     */
-    templates: {
-        /**
-         * Gets a sprite template by its slug.
-         *
-         * CACHING ARCHITECTURE:
-         * - SDK caches the API response (URL mapping) - permanent cache
-         * - Frontend (assetStore) caches the actual JSON content
-         * This maintains clean separation: SDK caches API data, frontend caches static assets
-         *
-         * @param slug - The template slug to fetch
-         * @returns Promise resolving to the sprite template data
-         *
-         * @example
-         * ```typescript
-         * const template = await client.sprites.templates.get('hero-idle')
-         * console.log('Template frames:', template.frames?.length || 0)
-         * console.log('Template animations:', Object.keys(template.animations || {}))
-         * ```
-         */
-        get: (slug: string) => Promise<SpriteTemplateData>;
-    };
-};

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

@@ -1,28 +0,0 @@
-import type { PlaycademyClient } from '../../types';
-/**
- * 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/timeback.d.ts

@@ -1,111 +0,0 @@
-import type { TodayXpResponse, TotalXpResponse, XpHistoryResponse } from '@playcademy/data/types';
-import type { PlaycademyClient } from '../../types';
-/**
- * Combined response type for summary method
- */
-export type XpSummaryResponse = {
-    today: TodayXpResponse;
-    total: TotalXpResponse;
-};
-/**
- * Creates the timeback namespace for the PlaycademyClient.
- * Provides methods for retrieving TimeBack XP data.
- *
- * @param client - The PlaycademyClient instance
- * @returns TimeBack namespace with XP query methods
- */
-export declare function createTimebackNamespace(client: PlaycademyClient): {
-    /**
-     * XP-related methods
-     */
-    xp: {
-        /**
-         * Get today's XP for the current user.
-         *
-         * @param options - Optional parameters
-         * @param options.date - Specific date to get XP for (ISO string)
-         * @param options.timezone - IANA timezone (e.g., 'America/New_York', 'Europe/London')
-         * @returns Promise resolving to today's XP data
-         *
-         * @example
-         * ```typescript
-         * // Get today's XP in default timezone (EST)
-         * const todayXp = await client.timeback.xp.today()
-         *
-         * // Get today's XP in user's timezone
-         * const userTz = Intl.DateTimeFormat().resolvedOptions().timeZone
-         * const todayXp = await client.timeback.xp.today({ timezone: userTz })
-         *
-         * // Get XP for specific date in London timezone
-         * const londonXp = await client.timeback.xp.today({
-         *   date: '2025-01-15T14:30:00.000Z',
-         *   timezone: 'Europe/London'
-         * })
-         * ```
-         */
-        today: (options?: {
-            date?: string;
-            timezone?: string;
-        }) => Promise<TodayXpResponse>;
-        /**
-         * Get total accumulated XP for the current user.
-         *
-         * @returns Promise resolving to total XP data
-         *
-         * @example
-         * ```typescript
-         * const totalXp = await client.timeback.xp.total()
-         * console.log('Total XP earned:', totalXp.totalXp)
-         * ```
-         */
-        total: () => Promise<TotalXpResponse>;
-        /**
-         * Get XP history with optional date filtering.
-         *
-         * @param options - Optional filtering parameters
-         * @param options.startDate - Start date for filtering (YYYY-MM-DD format)
-         * @param options.endDate - End date for filtering (YYYY-MM-DD format)
-         * @returns Promise resolving to XP history data
-         *
-         * @example
-         * ```typescript
-         * // Get all XP history
-         * const history = await client.timeback.xp.history()
-         *
-         * // Get XP for January 2025
-         * const januaryXp = await client.timeback.xp.history({
-         *   startDate: '2025-01-01',
-         *   endDate: '2025-01-31'
-         * })
-         * ```
-         */
-        history: (options?: {
-            startDate?: string;
-            endDate?: string;
-        }) => Promise<XpHistoryResponse>;
-        /**
-         * Get both today's XP and total XP in a single call.
-         * More efficient than calling today() and total() separately.
-         *
-         * @param options - Optional parameters for today's XP
-         * @param options.date - Specific date to get today's XP for (ISO string)
-         * @param options.timezone - IANA timezone (e.g., 'America/New_York', 'Europe/London')
-         * @returns Promise resolving to combined XP data
-         *
-         * @example
-         * ```typescript
-         * // Get both today's and total XP in default timezone
-         * const xpData = await client.timeback.xp.summary()
-         * console.log('Today:', xpData.today.xp)
-         * console.log('Total:', xpData.total.totalXp)
-         *
-         * // Get summary with custom timezone
-         * const londonXp = await client.timeback.xp.summary({ timezone: 'Europe/London' })
-         * ```
-         */
-        summary: (options?: {
-            date?: string;
-            timezone?: string;
-        }) => Promise<XpSummaryResponse>;
-    };
-};

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

@@ -1,172 +0,0 @@
-import type { AuthenticatedUser, InventoryItemWithItem } from '@playcademy/data/types';
-import type { InventoryMutationResponse, PlaycademyClient } from '../../types';
-export interface UserScore {
-    id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
-}
-/**
- * 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 with authentication context.
-     *
-     * @returns Promise resolving to user profile data including auth provider info
-     *
-     * @example
-     * ```typescript
-     * const user = await client.users.me()
-     * console.log('Username:', user.username)
-     * console.log('Email:', user.email)
-     * console.log('Has Timeback Account:', user.hasTimebackAccount)
-     * ```
-     */
-    me: () => Promise<AuthenticatedUser>;
-    /**
-     * 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.
-         * Accepts either an item UUID or slug.
-         * Emits an 'inventoryChange' event when successful.
-         *
-         * @param identifier - The item UUID or slug
-         * @param qty - The quantity to add (must be positive)
-         * @returns Promise resolving to mutation response with new total
-         *
-         * @example
-         * ```typescript
-         * // Using slug
-         * const result = await client.users.inventory.add('gold-coin', 100)
-         *
-         * // Using UUID
-         * const result = await client.users.inventory.add('550e8400-e29b-41d4-a716-446655440000', 100)
-         *
-         * console.log('New total:', result.newTotal)
-         * ```
-         */
-        add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-        /**
-         * Removes items from the user's inventory.
-         * Accepts either an item UUID or slug.
-         * Emits an 'inventoryChange' event when successful.
-         *
-         * @param identifier - The item UUID or slug
-         * @param qty - The quantity to remove (must be positive)
-         * @returns Promise resolving to mutation response with new total
-         *
-         * @example
-         * ```typescript
-         * // Using slug
-         * const result = await client.users.inventory.remove('HEALTH_POTION', 1)
-         *
-         * // Using UUID
-         * const result = await client.users.inventory.remove('uuid-456-789', 1)
-         *
-         * console.log('Remaining:', result.newTotal)
-         * ```
-         */
-        remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-        /**
-         * Gets the current quantity of an item.
-         * Accepts either an item UUID or slug.
-         *
-         * @param identifier - The item UUID or slug
-         * @returns Promise resolving to the current quantity (0 if not owned)
-         *
-         * @example
-         * ```typescript
-         * const qty = await client.users.inventory.quantity('health-potion')
-         * const qty2 = await client.users.inventory.quantity('uuid-123-456')
-         * console.log('Health potions:', qty)
-         * ```
-         */
-        quantity: (identifier: string) => Promise<number>;
-        /**
-         * Checks if the user has at least the specified quantity of an item.
-         * Accepts either an item UUID or slug.
-         *
-         * @param identifier - The item UUID or slug
-         * @param minQuantity - Minimum quantity required (defaults to 1)
-         * @returns Promise resolving to true if user has enough of the item
-         *
-         * @example
-         * ```typescript
-         * const hasKey = await client.users.inventory.has('gold-coin')
-         * const hasEnoughGold = await client.users.inventory.has('gold-coin', 100)
-         * const hasPotion = await client.users.inventory.has('uuid-123-456', 5)
-         *
-         * if (hasKey && hasEnoughGold) {
-         *   console.log('Can enter premium dungeon!')
-         * }
-         * ```
-         */
-        has: (identifier: string, minQuantity?: number) => Promise<boolean>;
-    };
-    /**
-     * User scores management methods.
-     */
-    scores: {
-        /**
-         * Gets scores for a user across all games.
-         *
-         * @param userIdOrOptions - User ID or options object. If omitted, gets scores for the current user.
-         * @param options - Optional filtering options
-         * @param options.limit - Maximum number of scores to return
-         * @param options.gameId - Filter scores by specific game
-         * @returns Promise resolving to array of user scores
-         *
-         * @example
-         * ```typescript
-         * // Get all scores for current user
-         * const myScores = await client.users.scores.get()
-         *
-         * // Get scores for current user with options
-         * const myGameScores = await client.users.scores.get({
-         *   gameId: 'game-456',
-         *   limit: 20
-         * })
-         *
-         * // Get scores for a specific user
-         * const userScores = await client.users.scores.get('user-123')
-         *
-         * // Get scores for a specific user with options
-         * const userGameScores = await client.users.scores.get('user-123', {
-         *   gameId: 'game-789',
-         *   limit: 10
-         * })
-         * ```
-         */
-        get: (userIdOrOptions?: string | {
-            limit?: number;
-            gameId?: string;
-        }, options?: {
-            limit?: number;
-            gameId?: string;
-        }) => Promise<UserScore[]>;
-    };
-};

package/dist/core/request.d.ts

@@ -1,24 +0,0 @@
-import type { ManifestV1 } from '@playcademy/data/types';
-/** Permitted HTTP verbs */
-export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-export interface RequestOptions {
-    path: string;
-    baseUrl: string;
-    token?: string | null;
-    method?: Method;
-    body?: unknown;
-    extraHeaders?: Record<string, string>;
-}
-/**
- * Thin wrapper around `fetch` that:
- *  • attaches Bearer token if provided
- *  • stringifies JSON bodies and sets Content‑Type
- *  • passes FormData untouched so the browser adds multipart boundary
- *  • normalises non‑2xx responses into ApiError
- *  • auto‑parses JSON responses, falls back to text/void
- */
-export declare function request<T = unknown>({ path, baseUrl, token, method, body, extraHeaders, }: RequestOptions): Promise<T>;
-/**
- * Fetches, parses, and validates the playcademy.manifest.json file from a given base URL.
- */
-export declare function fetchManifest(assetBundleBase: string): Promise<ManifestV1>;

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

@@ -1,37 +0,0 @@
-import { parseOAuthState } from '../auth/oauth';
-/**
- * Static identity-related utilities for the Playcademy SDK.
- * These methods can be used without instantiating a PlaycademyClient.
- */
-export declare const identity: {
-    /**
-     * Parses an OAuth state parameter to extract CSRF token and custom data.
-     * Use this in your server callback to retrieve the data encoded in the state.
-     *
-     * @param state - The OAuth state parameter from the callback
-     * @returns Object containing the CSRF token and optional custom data
-     *
-     * @example
-     * ```typescript
-     * // In your server callback endpoint
-     * import { PlaycademyClient } from '@playcademy/sdk'
-     *
-     * app.get('/api/auth/callback', async (req, res) => {
-     *     const { csrfToken, data } = PlaycademyClient.identity.parseOAuthState(req.query.state)
-     *
-     *     // Validate CSRF token
-     *     if (!isValidCsrf(csrfToken)) {
-     *         return res.status(403).send('Invalid state')
-     *     }
-     *
-     *     // Access Playcademy user ID if available
-     *     const playcademyUserId = data?.playcademy_user_id
-     *     const gameId = data?.game_id
-     *
-     *     // Exchange code for tokens...
-     *     // Link accounts...
-     * })
-     * ```
-     */
-    parseOAuthState: typeof parseOAuthState;
-};

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

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

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

@@ -1,21 +0,0 @@
-import type { PlaycademyClient } from '../../types';
-/**
- * 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

@@ -1,34 +0,0 @@
-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.
- *
- * @deprecated Use client.auth.login() instead for better error handling and automatic token management
- *
- * @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
- * // Preferred approach:
- * const client = new PlaycademyClient({ baseUrl: '/api' })
- * const result = await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'password'
- * })
- *
- * // Legacy approach (still works):
- * 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>;