@playcademy/sdk 0.0.5 → 0.0.7

package/dist/core/client.d.ts

@@ -1,521 +0,0 @@
-import { init, login } from './static';
-import type { ClientConfig, ClientEvents } from '../types';
-import type { Method } from './request';
-/**
- * Main Playcademy SDK client for interacting with the platform API.
- * Provides namespaced access to all platform features including games, users, inventory, and more.
- */
-export declare class PlaycademyClient {
-    private baseUrl;
-    private token?;
-    private gameId?;
-    private listeners;
-    private internalClientSessionId?;
-    private authContext?;
-    private initPayload?;
-    /**
-     * Creates a new PlaycademyClient instance.
-     *
-     * @param config - Optional configuration object
-     * @param config.baseUrl - Base URL for API requests (defaults to '/api')
-     * @param config.token - Authentication token
-     * @param config.gameId - Game ID for automatic session management
-     */
-    constructor(config?: Partial<ClientConfig>);
-    /**
-     * Gets the effective base URL for API requests.
-     * Converts relative URLs to absolute URLs in browser environments.
-     *
-     * @returns The complete base URL for API requests
-     */
-    getBaseUrl(): string;
-    /**
-     * Simple ping method for testing connectivity.
-     *
-     * @returns 'pong' string response
-     */
-    ping(): string;
-    /**
-     * Sets the authentication token for API requests.
-     * Emits an 'authChange' event when the token changes.
-     *
-     * @param token - The authentication token, or null to clear
-     */
-    setToken(token: string | null): void;
-    /**
-     * Checks if the client has a valid API token for making Playcademy API requests.
-     *
-     * For games (iframe context): Checks if we have a valid token from the parent.
-     * For Cademy (standalone): Checks if we have a token from better-auth.
-     *
-     * Note: This checks for API authentication, not whether a user has linked
-     * their identity via OAuth.
-     *
-     * @returns true if API token exists, false otherwise
-     *
-     * @example
-     * ```typescript
-     * if (client.isAuthenticated()) {
-     *     // Can make API calls
-     *     const games = await client.games.list()
-     * } else {
-     *     console.error('No API token available')
-     * }
-     * ```
-     */
-    isAuthenticated(): boolean;
-    /**
-     * Registers a callback to be called when authentication state changes.
-     *
-     * @param callback - Function to call when auth state changes
-     */
-    onAuthChange(callback: (token: string | null) => void): void;
-    /**
-     * Sets the authentication context for the client.
-     * This is called during initialization to store environment info.
-     * @internal
-     */
-    _setAuthContext(context: {
-        isInIframe: boolean;
-    }): void;
-    /**
-     * Registers an event listener for client events.
-     *
-     * @param event - The event type to listen for
-     * @param callback - Function to call when the event is emitted
-     */
-    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
-    /**
-     * Emits an event to all registered listeners.
-     *
-     * @param event - The event type to emit
-     * @param payload - The event payload
-     */
-    private emit;
-    /**
-     * Makes an authenticated HTTP request to the API.
-     *
-     * @param path - API endpoint path
-     * @param method - HTTP method
-     * @param body - Request body (optional)
-     * @param headers - Additional headers (optional)
-     * @returns Promise resolving to the response data
-     */
-    protected request<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
-    /**
-     * Ensures a gameId is available, throwing an error if not.
-     *
-     * @returns The gameId
-     * @throws PlaycademyError if no gameId is configured
-     */
-    private _ensureGameId;
-    /**
-     * Detects and sets the authentication context (iframe vs standalone).
-     * Safe to call in any environment - isInIframe handles browser detection.
-     */
-    private detectAuthContext;
-    /**
-     * Initializes an internal game session for automatic session management.
-     * Called automatically when a gameId is provided in the constructor.
-     */
-    private _initializeInternalSession;
-    /** Platform API authentication methods (login, logout) */
-    auth: {
-        login: (credentials: {
-            email: string;
-            password: string;
-        }) => Promise<{
-            success: boolean;
-            token?: string;
-            error?: string;
-        }>;
-        logout: () => Promise<void>;
-    };
-    /** Identity provider connection methods (connect external accounts) */
-    identity: {
-        readonly user: import("@playcademy/data/types").AuthenticatedUser | null;
-        connect: (options: import("../types").AuthOptions) => Promise<import("../types").AuthResult>;
-        _getContext: () => {
-            isInIframe: boolean;
-        };
-    };
-    /** Runtime methods (getGameToken, exit) */
-    runtime: {
-        getGameToken: (gameId: string, options?: {
-            apply?: boolean;
-        }) => Promise<import("../types").GameTokenResponse>;
-        exit: () => Promise<void>;
-        onInit: (handler: (context: import("../types").GameContextPayload) => void) => void;
-        onTokenRefresh: (handler: (data: {
-            token: string;
-            exp: number;
-        }) => void) => void;
-        onPause: (handler: () => void) => void;
-        onResume: (handler: () => void) => void;
-        onForceExit: (handler: () => void) => void;
-        onOverlay: (handler: (isVisible: boolean) => void) => void;
-        ready: () => void;
-        sendTelemetry: (data: {
-            fps: number;
-            mem: number;
-        }) => void;
-        removeListener: (eventType: import("..").MessageEvents, handler: ((context: import("../types").GameContextPayload) => void) | ((data: {
-            token: string;
-            exp: number;
-        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
-        removeAllListeners: () => void;
-        getListenerCounts: () => Record<string, number>;
-    };
-    /** Game management methods (fetch, list, saveState, loadState, sessions) */
-    games: {
-        fetch: (gameIdOrSlug: string, options?: import("./cache/types").TTLCacheConfig) => Promise<import("@playcademy/data/types").FetchedGame>;
-        list: (options?: import("./cache/types").TTLCacheConfig) => Promise<Array<import("@playcademy/data/types").Game>>;
-        saveState: (state: Record<string, unknown>) => Promise<void>;
-        loadState: () => Promise<import("@playcademy/data/types").GameStateData>;
-        startSession: (gameId?: string) => Promise<import("../types").StartSessionResponse>;
-        endSession: (sessionId: string, gameId?: string) => Promise<void>;
-        token: {
-            create: (gameId: string, options?: {
-                apply?: boolean;
-            }) => Promise<import("../types").GameTokenResponse>;
-        };
-        leaderboard: {
-            get: (gameId: string, options?: {
-                limit?: number;
-                offset? /** Telemetry methods (pushMetrics) */: number;
-            }) => Promise<import("@playcademy/data/types").LeaderboardEntry[]>;
-        };
-    };
-    /** User methods (me, inventory management) */
-    users: {
-        me: () => Promise<import("@playcademy/data/types").AuthenticatedUser>;
-        inventory: {
-            get: () => Promise<import("@playcademy/data/types").InventoryItemWithItem[]>;
-            add: (identifier: string, qty: number) => Promise<import("../types").InventoryMutationResponse>;
-            remove: (identifier: string, qty: number) => Promise<import("../types").InventoryMutationResponse>;
-            quantity: (identifier: string) => Promise<number>;
-            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
-        };
-        scores: {
-            get: (userIdOrOptions?: string | {
-                limit?: number;
-                gameId?: string;
-            }, options?: {
-                limit?: number;
-                gameId?: string;
-            }) => Promise<import("./namespaces/users").UserScore[]>;
-        };
-    };
-    /** Developer tools (auth, games, keys management) */
-    dev: {
-        status: {
-            apply: () => Promise<void>;
-            get: () => Promise<import("@playcademy/data/types").DeveloperStatusValue>;
-        };
-        games: {
-            upsert: (slug: string, metadata: import("@playcademy/data/types").UpsertGameMetadataInput, file: File | Blob | null, hooks?: import("..").DevUploadHooks) => Promise<import("@playcademy/data/types").Game>;
-            update: (gameId: string, props: Partial<import("@playcademy/data/types").Game>) => Promise<void>;
-            delete: (gameId: string) => Promise<void>;
-        };
-        keys: {
-            create: (label?: string) => Promise<{
-                id: string;
-                createdAt: Date;
-                userId: string;
-                label: string | null;
-                keyHash: string;
-            }>;
-            list: () => Promise<{
-                id: string;
-                createdAt: Date;
-                userId: string;
-                label: string | null;
-                keyHash: string;
-            }[]>;
-            revoke: (keyId: string) => Promise<void>;
-        };
-        items: {
-            create: (gameId: string, slug: string, itemData: Omit<import("@playcademy/data/types").InsertItemInput, "slug" | "gameId">) => Promise<import("@playcademy/data/types").Item>;
-            update: (gameId: string, itemId: string, updates: import("@playcademy/data/types").UpdateItemInput) => Promise<import("@playcademy/data/types").Item>;
-            list: (gameId: string) => Promise<Array<import("@playcademy/data/types").Item>>;
-            get: (gameId: string, slug: string) => Promise<import("@playcademy/data/types").Item>;
-            delete: (gameId: string, itemId: string) => Promise<void>;
-            shop: {
-                create: (gameId: string, itemId: string, listingData: Omit<import("@playcademy/data/types").InsertShopListingInput, "itemId">) => Promise<import("@playcademy/data/types").ShopListing>;
-                get: (gameId: string, itemId: string) => Promise<import("@playcademy/data/types").ShopListing | null>;
-                update: (gameId: string, itemId: string, updates: import("@playcademy/data/types").UpdateShopListingInput) => Promise<import("@playcademy/data/types").ShopListing>;
-                delete: (gameId: string, itemId: string) => Promise<void>;
-                list: (gameId: string) => Promise<Array<import("@playcademy/data/types").ShopListing & {
-                    item: import("@playcademy/data/types").Item;
-                }>>;
-            };
-        };
-    };
-    /** Map methods (elements) */
-    maps: {
-        get: (identifier: string) => Promise<import("@playcademy/data/types").MapData>;
-        elements: (mapId: string) => Promise<import("@playcademy/data/types").MapElementWithGame[]>;
-        objects: {
-            list: (mapId: string) => Promise<import("@playcademy/data/types").MapObjectWithItem[]>;
-            create: (mapId: string, objectData: import("@playcademy/data/types").CreateMapObjectData) => Promise<import("@playcademy/data/types").MapObjectWithItem>;
-            delete: (mapId: string, objectId: string) => Promise<void>;
-        };
-    };
-    /** Admin methods (games, items, currencies, shop listings) */
-    admin: {
-        games: {
-            pauseGame: (gameId: string) => Promise<void>;
-            resumeGame: (gameId: string) => Promise<void>;
-        };
-        items: {
-            create: (props: import("@playcademy/data/types").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;
-            }>;
-            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;
-            }>;
-            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;
-            }[]>;
-            update: (itemId: string, props: import("@playcademy/data/types").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;
-            }>;
-            delete: (itemId: string) => Promise<void>;
-        };
-        currencies: {
-            create: (props: import("@playcademy/data/types").InsertCurrencyInput) => Promise<{
-                symbol: string | null;
-                id: string;
-                createdAt: Date;
-                updatedAt: Date | null;
-                itemId: string;
-                isPrimary: boolean;
-            }>;
-            get: (currencyId: string) => Promise<{
-                symbol: string | null;
-                id: string;
-                createdAt: Date;
-                updatedAt: Date | null;
-                itemId: string;
-                isPrimary: boolean;
-            }>;
-            list: () => Promise<{
-                symbol: string | null;
-                id: string;
-                createdAt: Date;
-                updatedAt: Date | null;
-                itemId: string;
-                isPrimary: boolean;
-            }[]>;
-            update: (currencyId: string, props: import("@playcademy/data/types").UpdateCurrencyInput) => Promise<{
-                symbol: string | null;
-                id: string;
-                createdAt: Date;
-                updatedAt: Date | null;
-                itemId: string;
-                isPrimary: boolean;
-            }>;
-            delete: (currencyId: string) => Promise<void>;
-        };
-        shopListings: {
-            create: (props: import("@playcademy/data/types").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;
-            }>;
-            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;
-            }>;
-            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;
-            }[]>;
-            update: (listingId: string, props: import("@playcademy/data/types").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;
-            }>;
-            delete: (listingId: string) => Promise<void>;
-        };
-    };
-    /** Shop methods (view) */
-    shop: {
-        view: () => Promise<import("@playcademy/data/types").ShopViewResponse>;
-    };
-    /** Level methods (levels) */
-    levels: {
-        get: () => Promise<import("@playcademy/data/types").UserLevel>;
-        progress: (options?: import("./cache/types").CooldownCacheConfig) => Promise<{
-            level: number;
-            currentXp: number;
-            xpToNextLevel: number;
-            totalXP: number;
-        }>;
-        config: {
-            list: () => Promise<import("@playcademy/data/types").LevelConfig[]>;
-            get: (level: number) => Promise<import("@playcademy/data/types").LevelConfig | null>;
-        };
-    };
-    /** TimeBack XP methods (today, total, history) */
-    timeback: {
-        xp: {
-            today: (options?: {
-                date?: string;
-                timezone?: string;
-            }) => Promise<import("@playcademy/data/types").TodayXpResponse>;
-            total: () => Promise<import("@playcademy/data/types").TotalXpResponse>;
-            history: (options?: {
-                startDate?: string;
-                endDate?: string;
-            }) => Promise<import("@playcademy/data/types").XpHistoryResponse>;
-            summary: (options?: {
-                date?: string;
-                timezone?: string;
-            }) => Promise<import("./namespaces/timeback").XpSummaryResponse>;
-        };
-    };
-    /** Telemetry methods (pushMetrics) */
-    telemetry: {
-        pushMetrics: (metrics: Record<string, number>) => Promise<void>;
-    };
-    /** Credits methods (credits management) */
-    credits: {
-        balance: () => Promise<number>;
-        add: (amount: number) => Promise<number>;
-        spend: (amount: number) => Promise<number>;
-    };
-    /** Platform-wide leaderboard methods (fetch, getUserRank) */
-    leaderboard: {
-        fetch: (options?: import("@playcademy/data/types").LeaderboardOptions) => Promise<import("@playcademy/data/types").GameLeaderboardEntry[]>;
-        getUserRank: (gameId: string, userId: string) => Promise<import("@playcademy/data/types").UserRankResponse>;
-    };
-    /** Platform-wide scores methods (submit, getUserScores) */
-    scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<import("./namespaces/scores").ScoreSubmission>;
-        getByUser: (gameId: string, userId: string, options?: {
-            limit?: number;
-        }) => Promise<import("@playcademy/data/types").UserScore[]>;
-    };
-    /** Character methods (get, create, update, components) */
-    character: {
-        get: (userId?: string) => Promise<import("@playcademy/data/types").PlayerCharacter | null>;
-        create: (characterData: import("./namespaces/character").CreateCharacterData) => Promise<import("@playcademy/data/types").PlayerCharacter>;
-        update: (updates: import("./namespaces/character").UpdateCharacterData) => Promise<import("@playcademy/data/types").PlayerCharacter>;
-        components: {
-            list: (options?: import("./namespaces/character").CharacterComponentsOptions & import("./cache/types").TTLCacheConfig) => Promise<import("@playcademy/data/types").CharacterComponentWithSpriteUrl[]>;
-            clearCache: (key?: string) => void;
-            getCacheKeys: () => string[];
-        };
-        accessories: {
-            equip: (slot: string, componentId: string) => Promise<import("@playcademy/data/types").PlayerCharacterAccessory>;
-            remove: (slot: string) => Promise<{
-                success: boolean;
-            }>;
-            list: () => Promise<import("@playcademy/data/types").PlayerCharacterAccessory[]>;
-        };
-    };
-    /** Sprites methods (templates) */
-    sprites: {
-        templates: {
-            get: (slug: string) => Promise<import("@playcademy/data/types").SpriteTemplateData>;
-        };
-    };
-    /** Realtime methods (token) */
-    realtime: {
-        token: {
-            get: () => Promise<import("./namespaces/realtime").RealtimeTokenResponse>;
-        };
-        open(channel?: string, url?: string): Promise<import("@playcademy/realtime/server/types").RealtimeChannel>;
-    };
-    /** Achievements methods (list, history, progress) */
-    achievements: {
-        list: (options?: import("./cache/types").TTLCacheConfig) => Promise<import("@playcademy/data/types").AchievementCurrent[]>;
-        history: {
-            list: (queryOptions?: {
-                limit?: number;
-            }, cacheOptions?: import("./cache/types").TTLCacheConfig) => Promise<import("@playcademy/data/types").AchievementHistoryEntry[]>;
-        };
-        progress: {
-            submit: (achievementId: string) => Promise<import("@playcademy/data/types").AchievementProgressResponse>;
-        };
-    };
-    /** Auto-initializes a PlaycademyClient with context from the environment */
-    static init: typeof init;
-    /** Authenticates a user with email and password */
-    static login: typeof login;
-    /** Static identity utilities for OAuth operations */
-    static identity: {
-        parseOAuthState: typeof import("./auth/oauth").parseOAuthState;
-    };
-}

package/dist/core/errors.d.ts

@@ -1,11 +0,0 @@
-/**
- * Base error class for Cademy SDK specific errors.
- */
-export declare class PlaycademyError extends Error {
-    constructor(message: string);
-}
-export declare class ApiError extends Error {
-    status: number;
-    details: unknown;
-    constructor(status: number, message: string, details: unknown);
-}

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

@@ -1,84 +0,0 @@
-import type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse } from '@playcademy/data/types';
-import type { PlaycademyClient } from '../../types';
-import type { TTLCacheConfig } from '../cache/types';
-/**
- * Creates the achievements namespace for the PlaycademyClient.
- * Provides methods to list current achievements, read claim history,
- * and submit progress for an achievement.
- *
- * Method naming and structure follow existing conventions:
- * - Top-level listing via `list()`
- * - Nested sub-namespaces (e.g., `history.list`, `progress.submit`)
- *
- * @param client - The PlaycademyClient instance
- * @returns Achievements namespace with list/history/progress methods
- */
-export declare function createAchievementsNamespace(client: PlaycademyClient): {
-    /**
-     * Lists current-interval achievements with status (available/completed).
-     * Results are cached for 5 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 current achievements
-     *
-     * @example
-     * ```typescript
-     * // Use default 5 second cache
-     * const achievements = await client.achievements.list()
-     *
-     * // Force refresh on user action
-     * const freshAchievements = await client.achievements.list({ force: true })
-     *
-     * // Disable caching for admin panel
-     * const uncachedAchievements = await client.achievements.list({ ttl: 0 })
-     * ```
-     */
-    list: (options?: TTLCacheConfig) => Promise<AchievementCurrent[]>;
-    /**
-     * History sub-namespace
-     */
-    history: {
-        /**
-         * Lists recent achievement claims for the current user.
-         * Results are cached for 5 seconds by default.
-         *
-         * @param queryOptions - Query parameters for the request
-         * @param queryOptions.limit - Maximum number of entries to return (default 20)
-         * @param cacheOptions - Optional cache configuration
-         * @param cacheOptions.ttl - Custom TTL in milliseconds (0 to disable caching)
-         * @param cacheOptions.force - Force refresh the cache
-         * @returns Promise resolving to array of achievement history entries
-         *
-         * @example
-         * ```typescript
-         * // Use default 5 second cache, get 20 entries
-         * const history = await client.achievements.history.list()
-         *
-         * // Get 50 entries with cache
-         * const moreHistory = await client.achievements.history.list({ limit: 50 })
-         *
-         * // Force refresh with custom limit
-         * const freshHistory = await client.achievements.history.list(
-         *   { limit: 10 },
-         *   { force: true }
-         * )
-         * ```
-         */
-        list: (queryOptions?: {
-            limit?: number;
-        }, cacheOptions?: TTLCacheConfig) => Promise<AchievementHistoryEntry[]>;
-    };
-    /**
-     * Progress sub-namespace
-     */
-    progress: {
-        /**
-         * Submits completion for an achievement (server validates idempotency).
-         *
-         * @param achievementId - The ID of the achievement to submit progress for
-         */
-        submit: (achievementId: string) => Promise<AchievementProgressResponse>;
-    };
-};