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

package/dist/messaging.d.ts

@@ -0,0 +1,522 @@
+/**
+ * @fileoverview Playcademy Messaging System
+ *
+ * This file implements a unified messaging system for the Playcademy platform that handles
+ * communication between different contexts:
+ *
+ * 1. **Iframe-to-Parent Communication**: When games run inside iframes (production/development),
+ *    they need to communicate with the parent window using postMessage API
+ *
+ * 2. **Local Communication**: When games run in the same context (local development),
+ *    they use CustomEvents for internal messaging
+ *
+ * The system automatically detects the runtime environment and chooses the appropriate
+ * transport method, abstracting this complexity from the developer.
+ *
+ * **Architecture Overview**:
+ * - Games run in iframes for security and isolation
+ * - Parent window (Playcademy shell) manages game lifecycle
+ * - Messages flow bidirectionally between parent and iframe
+ * - Local development mode simulates this architecture without iframes
+ */
+import type { GameContextPayload } from './types';
+/**
+ * Enumeration of all message types used in the Playcademy messaging system.
+ *
+ * **Message Flow Patterns**:
+ *
+ * **Parent → Game (Overworld → Game)**:
+ * - INIT: Provides game with authentication token and configuration
+ * - TOKEN_REFRESH: Updates game's authentication token before expiry
+ * - PAUSE/RESUME: Controls game execution state
+ * - FORCE_EXIT: Immediately terminates the game
+ * - OVERLAY: Shows/hides UI overlays over the game
+ *
+ * **Game → Parent (Game → Overworld)**:
+ * - READY: Game has loaded and is ready to receive messages
+ * - EXIT: Game requests to be closed (user clicked exit, game ended, etc.)
+ * - TELEMETRY: Game reports performance metrics (FPS, memory usage, etc.)
+ */
+export declare enum MessageEvents {
+    /**
+     * Initializes the game with authentication context and configuration.
+     * Sent immediately after game iframe loads.
+     * Payload: { baseUrl: string, token: string, gameId: string }
+     */
+    INIT = "PLAYCADEMY_INIT",
+    /**
+     * Updates the game's authentication token before it expires.
+     * Sent periodically to maintain valid authentication.
+     * Payload: { token: string, exp: number }
+     */
+    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
+    /**
+     * Pauses game execution (e.g., when user switches tabs).
+     * Game should pause timers, animations, and user input.
+     * Payload: void
+     */
+    PAUSE = "PLAYCADEMY_PAUSE",
+    /**
+     * Resumes game execution after being paused.
+     * Game should restore timers, animations, and user input.
+     * Payload: void
+     */
+    RESUME = "PLAYCADEMY_RESUME",
+    /**
+     * Forces immediate game termination (emergency exit).
+     * Game should clean up resources and exit immediately.
+     * Payload: void
+     */
+    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
+    /**
+     * Shows or hides UI overlays over the game.
+     * Game may need to pause or adjust rendering accordingly.
+     * Payload: boolean (true = show overlay, false = hide overlay)
+     */
+    OVERLAY = "PLAYCADEMY_OVERLAY",
+    /**
+     * Game has finished loading and is ready to receive messages.
+     * Sent once after game initialization is complete.
+     * Payload: void
+     */
+    READY = "PLAYCADEMY_READY",
+    /**
+     * Game requests to be closed/exited.
+     * Sent when user clicks exit button or game naturally ends.
+     * Payload: void
+     */
+    EXIT = "PLAYCADEMY_EXIT",
+    /**
+     * Game reports performance telemetry data.
+     * Sent periodically for monitoring and analytics.
+     * Payload: { fps: number, mem: number }
+     */
+    TELEMETRY = "PLAYCADEMY_TELEMETRY",
+    /**
+     * Game reports key events to parent.
+     * Sent when certain keys are pressed within the game iframe.
+     * Payload: { key: string, code?: string, type: 'keydown' | 'keyup' }
+     */
+    KEY_EVENT = "PLAYCADEMY_KEY_EVENT"
+}
+/**
+ * Type definition for message handler functions.
+ * These functions are called when a specific message type is received.
+ *
+ * @template T - The type of payload data the handler expects
+ * @param payload - The data sent with the message
+ */
+type MessageHandler<T = unknown> = (payload: T) => void;
+/**
+ * Type mapping that defines the payload structure for each message type.
+ * This ensures type safety when sending and receiving messages.
+ *
+ * **Usage Examples**:
+ * ```typescript
+ * // Type-safe message sending
+ * messaging.send(MessageEvents.INIT, { baseUrl: '/api', token: 'abc', gameId: '123' })
+ *
+ * // Type-safe message handling
+ * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
+ *   console.log(`New token expires at: ${new Date(exp)}`)
+ * })
+ * ```
+ */
+export type MessageEventMap = {
+    /** Game initialization context with API endpoint, auth token, and game ID */
+    [MessageEvents.INIT]: GameContextPayload;
+    /** Token refresh data with new token and expiration timestamp */
+    [MessageEvents.TOKEN_REFRESH]: {
+        token: string;
+        exp: number;
+    };
+    /** Pause message has no payload data */
+    [MessageEvents.PAUSE]: void;
+    /** Resume message has no payload data */
+    [MessageEvents.RESUME]: void;
+    /** Force exit message has no payload data */
+    [MessageEvents.FORCE_EXIT]: void;
+    /** Overlay visibility state (true = show, false = hide) */
+    [MessageEvents.OVERLAY]: boolean;
+    /** Ready message has no payload data */
+    [MessageEvents.READY]: void;
+    /** Exit message has no payload data */
+    [MessageEvents.EXIT]: void;
+    /** Performance telemetry data */
+    [MessageEvents.TELEMETRY]: {
+        fps: number;
+        mem: number;
+    };
+    /** Key event data */
+    [MessageEvents.KEY_EVENT]: {
+        key: string;
+        code?: string;
+        type: 'keydown' | 'keyup';
+    };
+};
+/**
+ * **PlaycademyMessaging Class**
+ *
+ * This is the core messaging system that handles all communication in the Playcademy platform.
+ * It automatically detects the runtime environment and chooses the appropriate transport method.
+ *
+ * **Key Features**:
+ * 1. **Automatic Transport Selection**: Detects iframe vs local context and uses appropriate method
+ * 2. **Type Safety**: Full TypeScript support with payload type checking
+ * 3. **Bidirectional Communication**: Handles both parent→game and game→parent messages
+ * 4. **Event Cleanup**: Proper listener management to prevent memory leaks
+ *
+ * **Transport Methods**:
+ * - **postMessage**: Used for iframe-to-parent communication (production/development)
+ * - **CustomEvent**: Used for local same-context communication (local development)
+ *
+ * **Runtime Detection Logic**:
+ * - If `window.self !== window.top`: We're in an iframe, use postMessage
+ * - If `window.self === window.top`: We're in the same context, use CustomEvent
+ *
+ * **Example Usage**:
+ * ```typescript
+ * // Send a message (automatically chooses transport)
+ * messaging.send(MessageEvents.READY, undefined)
+ *
+ * // Listen for messages (handles both transports)
+ * messaging.listen(MessageEvents.INIT, (payload) => {
+ *   console.log('Game initialized with:', payload)
+ * })
+ *
+ * // Clean up listeners
+ * messaging.unlisten(MessageEvents.INIT, handler)
+ * ```
+ */
+declare class PlaycademyMessaging {
+    /**
+     * Internal storage for message listeners.
+     *
+     * **Structure Explanation**:
+     * - Outer Map: MessageEvents → Map of handlers for that event type
+     * - Inner Map: MessageHandler → Object containing both listener types
+     * - Object: { postMessage: EventListener, customEvent: EventListener }
+     *
+     * **Why Two Listeners Per Handler?**:
+     * Since we don't know at registration time which transport will be used,
+     * we register both a postMessage listener and a CustomEvent listener.
+     * The appropriate one will be triggered based on the runtime context.
+     */
+    private listeners;
+    /**
+     * **Send Message Method**
+     *
+     * Sends a message using the appropriate transport method based on the runtime context.
+     * This is the main public API for sending messages in the Playcademy system.
+     *
+     * **How It Works**:
+     * 1. Analyzes the message type and current runtime context
+     * 2. Determines if we're in an iframe and if this message should use postMessage
+     * 3. Routes to the appropriate transport method (postMessage or CustomEvent)
+     *
+     * **Transport Selection Logic**:
+     * - **postMessage**: Used when game is in iframe and sending to parent, OR when target window is specified
+     * - **CustomEvent**: Used for local/same-context communication
+     *
+     * **Type Safety**:
+     * The generic type parameter `K` ensures that the payload type matches
+     * the expected type for the given message event.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to send
+     * @param payload - The data to send with the message (type-checked)
+     * @param options - Optional configuration for message sending
+     *
+     * @example
+     * ```typescript
+     * // Send game ready signal (no payload)
+     * messaging.send(MessageEvents.READY, undefined)
+     *
+     * // Send telemetry data (typed payload)
+     * messaging.send(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
+     *
+     * // Send to specific iframe window (parent to iframe communication)
+     * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId }, {
+     *   target: iframe.contentWindow,
+     *   origin: '*'
+     * })
+     *
+     * // TypeScript will error if payload type is wrong
+     * messaging.send(MessageEvents.INIT, "wrong type") // ❌ Error
+     * ```
+     */
+    send<K extends MessageEvents>(type: K, payload: MessageEventMap[K], options?: {
+        target?: Window;
+        origin?: string;
+    }): void;
+    /**
+     * **Listen for Messages Method**
+     *
+     * Registers a message listener that will be called when the specified message type is received.
+     * This method automatically handles both postMessage and CustomEvent sources.
+     *
+     * **Why Register Two Listeners?**:
+     * Since we don't know at registration time which transport method will be used to send
+     * messages, we register listeners for both possible sources:
+     * 1. **postMessage listener**: Handles messages from iframe-to-parent communication
+     * 2. **CustomEvent listener**: Handles messages from local same-context communication
+     *
+     * **Message Processing**:
+     * - **postMessage**: Extracts data from `event.data.payload` or `event.data`
+     * - **CustomEvent**: Extracts data from `event.detail`
+     *
+     * **Type Safety**:
+     * The handler function receives the correctly typed payload based on the message type.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to listen for
+     * @param handler - Function to call when the message is received
+     *
+     * @example
+     * ```typescript
+     * // Listen for game initialization
+     * messaging.listen(MessageEvents.INIT, (payload) => {
+     *   // payload is automatically typed as GameContextPayload
+     *   console.log(`Game ${payload.gameId} initialized`)
+     *   console.log(`API base URL: ${payload.baseUrl}`)
+     * })
+     *
+     * // Listen for token refresh
+     * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
+     *   // payload is automatically typed as { token: string; exp: number }
+     *   updateAuthToken(token)
+     *   scheduleTokenRefresh(exp)
+     * })
+     * ```
+     */
+    listen<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    /**
+     * **Remove Message Listener Method**
+     *
+     * Removes a previously registered message listener to prevent memory leaks and unwanted callbacks.
+     * This method cleans up both the postMessage and CustomEvent listeners that were registered.
+     *
+     * **Why Clean Up Both Listeners?**:
+     * When we registered the listener with `listen()`, we created two browser event listeners:
+     * 1. A 'message' event listener for postMessage communication
+     * 2. A custom event listener for local CustomEvent communication
+     *
+     * Both must be removed to prevent memory leaks and ensure the handler is completely unregistered.
+     *
+     * **Memory Management**:
+     * - Removes both event listeners from the browser
+     * - Cleans up internal tracking maps
+     * - If no more handlers exist for a message type, removes the entire type entry
+     *
+     * **Safe to Call Multiple Times**:
+     * This method is idempotent - calling it multiple times with the same handler is safe.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to stop listening for
+     * @param handler - The exact handler function that was passed to listen()
+     *
+     * @example
+     * ```typescript
+     * // Register a handler
+     * const handleInit = (payload) => console.log('Game initialized')
+     * messaging.listen(MessageEvents.INIT, handleInit)
+     *
+     * // Later, remove the handler
+     * messaging.unlisten(MessageEvents.INIT, handleInit)
+     *
+     * // Safe to call multiple times
+     * messaging.unlisten(MessageEvents.INIT, handleInit) // No error
+     * ```
+     */
+    unlisten<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    /**
+     * **Get Messaging Context Method**
+     *
+     * Analyzes the current runtime environment and message type to determine the appropriate
+     * transport method and configuration for sending messages.
+     *
+     * **Runtime Environment Detection**:
+     * The method detects whether the code is running in an iframe by comparing:
+     * - `window.self`: Reference to the current window
+     * - `window.top`: Reference to the topmost window in the hierarchy
+     *
+     * If they're different, we're in an iframe. If they're the same, we're in the top-level window.
+     *
+     * **Message Direction Analysis**:
+     * Different message types flow in different directions:
+     * - **Game → Parent**: READY, EXIT, TELEMETRY (use postMessage when in iframe)
+     * - **Parent → Game**: INIT, TOKEN_REFRESH, PAUSE, etc. (use CustomEvent in local dev, or postMessage with target)
+     *
+     * **Cross-Context Communication**:
+     * The messaging system supports cross-context targeting through the optional `target` parameter.
+     * When a target window is specified, postMessage is used regardless of the current context.
+     * This enables parent-to-iframe communication through the unified messaging API.
+     *
+     * **Transport Selection Logic**:
+     * - **postMessage**: Used when game is in iframe AND sending to parent, OR when target window is specified
+     * - **CustomEvent**: Used for all other cases (local development, same-context communication)
+     *
+     * **Security Considerations**:
+     * The origin is currently set to '*' for development convenience, but should be
+     * configurable for production security.
+     *
+     * @param eventType - The message event type being sent
+     * @returns Configuration object with transport method and target information
+     *
+     * @example
+     * ```typescript
+     * // In iframe sending READY to parent
+     * const context = getMessagingContext(MessageEvents.READY)
+     * // Returns: { shouldUsePostMessage: true, target: window.parent, origin: '*' }
+     *
+     * // In same context sending INIT
+     * const context = getMessagingContext(MessageEvents.INIT)
+     * // Returns: { shouldUsePostMessage: false, target: undefined, origin: '*' }
+     * ```
+     */
+    private getMessagingContext;
+    /**
+     * **Send Via PostMessage Method**
+     *
+     * Sends a message using the browser's postMessage API for iframe-to-parent communication.
+     * This method is used when the game is running in an iframe and needs to communicate
+     * with the parent window (the Playcademy shell).
+     *
+     * **PostMessage Protocol**:
+     * The postMessage API is the standard way for iframes to communicate with their parent.
+     * It's secure, cross-origin capable, and designed specifically for this use case.
+     *
+     * **Message Structure**:
+     * The method creates a message object with the following structure:
+     * - `type`: The message event type (e.g., 'PLAYCADEMY_READY')
+     * - `payload`: The message data (if any)
+     *
+     * **Payload Handling**:
+     * - **All payloads**: Wrapped in a `payload` property for consistency (e.g., { type, payload: data })
+     * - **Undefined payloads**: Only the type is sent (e.g., { type })
+     *
+     * **Security**:
+     * The origin parameter controls which domains can receive the message.
+     * Currently set to '*' for development, but should be restricted in production.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to send
+     * @param payload - The data to send with the message
+     * @param target - The target window (defaults to parent window)
+     * @param origin - The allowed origin for the message (defaults to '*')
+     *
+     * @example
+     * ```typescript
+     * // Send ready signal (no payload)
+     * sendViaPostMessage(MessageEvents.READY, undefined)
+     * // Sends: { type: 'PLAYCADEMY_READY' }
+     *
+     * // Send telemetry data (object payload)
+     * sendViaPostMessage(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
+     * // Sends: { type: 'PLAYCADEMY_TELEMETRY', payload: { fps: 60, mem: 128 } }
+     *
+     * // Send overlay state (primitive payload)
+     * sendViaPostMessage(MessageEvents.OVERLAY, true)
+     * // Sends: { type: 'PLAYCADEMY_OVERLAY', payload: true }
+     * ```
+     */
+    private sendViaPostMessage;
+    /**
+     * **Send Via CustomEvent Method**
+     *
+     * Sends a message using the browser's CustomEvent API for local same-context communication.
+     * This method is used when both the sender and receiver are in the same window context,
+     * typically during local development or when the parent needs to send messages to the game.
+     *
+     * **CustomEvent Protocol**:
+     * CustomEvent is a browser API for creating and dispatching custom events within the same
+     * window context. It's simpler than postMessage but only works within the same origin/context.
+     *
+     * **Event Structure**:
+     * - **type**: The event name (e.g., 'PLAYCADEMY_INIT')
+     * - **detail**: The payload data attached to the event
+     *
+     * **When This Is Used**:
+     * - Local development when game and shell run in the same context
+     * - Parent-to-game communication (INIT, TOKEN_REFRESH, PAUSE, etc.)
+     * - Any scenario where postMessage isn't needed
+     *
+     * **Event Bubbling**:
+     * CustomEvents are dispatched on the window object and can be listened to by any
+     * code in the same context using `addEventListener(type, handler)`.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to send (becomes the event name)
+     * @param payload - The data to send with the message (stored in event.detail)
+     *
+     * @example
+     * ```typescript
+     * // Send initialization data
+     * sendViaCustomEvent(MessageEvents.INIT, {
+     *   baseUrl: '/api',
+     *   token: 'abc123',
+     *   gameId: 'game-456'
+     * })
+     * // Creates: CustomEvent('PLAYCADEMY_INIT', { detail: { baseUrl, token, gameId } })
+     *
+     * // Send pause signal
+     * sendViaCustomEvent(MessageEvents.PAUSE, undefined)
+     * // Creates: CustomEvent('PLAYCADEMY_PAUSE', { detail: undefined })
+     *
+     * // Listeners can access the data via event.detail:
+     * window.addEventListener('PLAYCADEMY_INIT', (event) => {
+     *   console.log(event.detail.gameId) // 'game-456'
+     * })
+     * ```
+     */
+    private sendViaCustomEvent;
+}
+/**
+ * **Playcademy Messaging Singleton**
+ *
+ * This is the main messaging instance used throughout the Playcademy platform.
+ * It's exported as a singleton to ensure consistent communication across all parts
+ * of the application.
+ *
+ * **Why a Singleton?**:
+ * - Ensures all parts of the app use the same messaging instance
+ * - Prevents conflicts between multiple messaging systems
+ * - Simplifies the API - no need to pass instances around
+ * - Maintains consistent event listener management
+ *
+ * **Usage in Different Contexts**:
+ *
+ * **In Games**:
+ * ```typescript
+ * import { messaging, MessageEvents } from '@playcademy/sdk'
+ *
+ * // Tell parent we're ready
+ * messaging.send(MessageEvents.READY, undefined)
+ *
+ * // Listen for pause/resume
+ * messaging.listen(MessageEvents.PAUSE, () => game.pause())
+ * messaging.listen(MessageEvents.RESUME, () => game.resume())
+ * ```
+ *
+ * **In Parent Shell**:
+ * ```typescript
+ * import { messaging, MessageEvents } from '@playcademy/sdk'
+ *
+ * // Send initialization data to game
+ * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId })
+ *
+ * // Listen for game events
+ * messaging.listen(MessageEvents.EXIT, () => closeGame())
+ * messaging.listen(MessageEvents.READY, () => showGame())
+ * ```
+ *
+ * **Automatic Transport Selection**:
+ * The messaging system automatically chooses the right transport method:
+ * - Uses postMessage when game is in iframe sending to parent
+ * - Uses CustomEvent for local development and parent-to-game communication
+ *
+ * **Type Safety**:
+ * All message sending and receiving is fully type-safe with TypeScript.
+ */
+export declare const messaging: PlaycademyMessaging;
+export {};

package/dist/types.d.ts

@@ -1,4 +1,6 @@
-import type { User, InventoryItemWithReward, Game, DeveloperKey, DeveloperStatusResponse, MapElement, Reward, InsertReward, ManifestV1, UpdateReward } from '@playcademy/data/schemas';
+export type * from '@playcademy/data/types';
+export { CURRENCIES, BADGES } from '@playcademy/data/constants';
+export type { PlaycademyClient } from './core/client';
 export interface ClientConfig {
     baseUrl: string;
     token?: string;
@@ -9,24 +11,30 @@ export interface ClientEvents {
         token: string | null;
     };
     inventoryChange: {
-        rewardId: string;
+        itemId: string;
         delta: number;
         newTotal: number;
     };
+    levelUp: {
+        oldLevel: number;
+        newLevel: number;
+        creditsAwarded: number;
+    };
+    xpGained: {
+        amount: number;
+        totalXP: number;
+        leveledUp: boolean;
+    };
 }
 export type GameContextPayload = {
     token: string;
     baseUrl: string;
     gameId: string;
+    forwardKeys?: string[];
 };
 export type EventListeners = {
     [E in keyof ClientEvents]?: Array<(payload: ClientEvents[E]) => void>;
 };
-export type GameWithManifest = Game & {
-    manifest: ManifestV1;
-};
-export type DeveloperStatusValue = DeveloperStatusResponse['status'];
-export type GameState = Record<string, unknown>;
 export type LoginResponse = {
     token: string;
 };
@@ -40,4 +48,3 @@ export type StartSessionResponse = {
 export type InventoryMutationResponse = {
     newTotal: number;
 };
-export type { User, InventoryItemWithReward, Game, ManifestV1, DeveloperKey, DeveloperStatusResponse, MapElement, Reward, InsertReward, UpdateReward, };