@playcademy/sdk 0.0.5 → 0.0.6

package/dist/messaging.d.ts

@@ -1,544 +0,0 @@
-/**
- * @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 { AuthCallbackPayload, AuthStateChangePayload, GameContextPayload, KeyEventPayload, TelemetryPayload, TokenRefreshPayload } 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",
-    /**
-     * Notifies about authentication state changes.
-     * Can be sent in both directions depending on auth flow.
-     * Payload:
-     * - `authenticated`: boolean
-     * - `user`: UserInfo | null
-     * - `error`: Error | null
-     */
-    AUTH_STATE_CHANGE = "PLAYCADEMY_AUTH_STATE_CHANGE",
-    /**
-     * OAuth callback data from popup/new-tab windows.
-     * Sent from popup window back to parent after OAuth completes.
-     * Payload:
-     * - `code`: string (OAuth authorization code)
-     * - `state`: string (OAuth state for CSRF protection)
-     * - `error`: string | null (OAuth error if any)
-     */
-    AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
-}
-/**
- * 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]: TokenRefreshPayload;
-    /** 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]: TelemetryPayload;
-    /** Key event data */
-    [MessageEvents.KEY_EVENT]: KeyEventPayload;
-    /** Authentication state change notification */
-    [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
-    /** OAuth callback data from popup/new-tab windows */
-    [MessageEvents.AUTH_CALLBACK]: AuthCallbackPayload;
-};
-/**
- * **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 {};