@playcademy/sdk 0.1.14 → 0.1.15

package/dist/types.d.ts

@@ -4244,6 +4244,20 @@ interface UserScore {
     gameSlug: string;
 }
 
+/**
+ * Connection monitoring types
+ *
+ * Type definitions for connection state, configuration, and callbacks.
+ */
+/**
+ * Possible connection states.
+ *
+ * - **online**: Connection is stable and healthy
+ * - **offline**: Complete loss of network connectivity
+ * - **degraded**: Connection is slow or experiencing intermittent issues
+ */
+type ConnectionState = 'online' | 'offline' | 'degraded';
+
 /**
  * @fileoverview Playcademy Messaging System
  *
@@ -4325,6 +4339,14 @@ declare enum MessageEvents {
      * Payload: boolean (true = show overlay, false = hide overlay)
      */
     OVERLAY = "PLAYCADEMY_OVERLAY",
+    /**
+     * Broadcasts connection state changes to games.
+     * Sent by platform when network connectivity changes.
+     * Payload:
+     * - `state`: 'online' | 'offline' | 'degraded'
+     * - `reason`: string
+     */
+    CONNECTION_STATE = "PLAYCADEMY_CONNECTION_STATE",
     /**
      * Game has finished loading and is ready to receive messages.
      * Sent once after game initialization is complete.
@@ -4354,6 +4376,14 @@ declare enum MessageEvents {
      * - `type`: 'keydown' | 'keyup'
      */
     KEY_EVENT = "PLAYCADEMY_KEY_EVENT",
+    /**
+     * Game requests platform to display an alert.
+     * Sent when connection issues are detected or other important events occur.
+     * Payload:
+     * - `message`: string
+     * - `options`: { type?: 'info' | 'warning' | 'error', duration?: number }
+     */
+    DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
     /**
      * Notifies about authentication state changes.
      * Can be sent in both directions depending on auth flow.
@@ -4401,6 +4431,8 @@ declare enum MessageEvents {
 declare function init(options?: {
     baseUrl?: string;
     allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
 }): Promise<PlaycademyClient>;
 
 /**
@@ -4454,6 +4486,7 @@ declare class PlaycademyClient {
     private internalClientSessionId?;
     private authContext?;
     private initPayload?;
+    private connectionManager?;
     /**
      * Creates a new PlaycademyClient instance.
      *
@@ -4545,6 +4578,85 @@ declare class PlaycademyClient {
      * @param callback - Function to call when auth state changes
      */
     onAuthChange(callback: (token: string | null) => void): void;
+    /**
+     * Registers a callback to be called when connection issues are detected.
+     *
+     * This is a convenience method that filters connection change events to only
+     * fire when the connection degrades (offline or degraded states). Use this
+     * when you want to handle disconnects without being notified of recoveries.
+     *
+     * For all connection state changes, use `client.on('connectionChange', ...)` instead.
+     *
+     * @param callback - Function to call when connection state changes to offline or degraded
+     * @returns Cleanup function to unregister the callback
+     *
+     * @example
+     * ```typescript
+     * const cleanup = client.onDisconnect(({ state, reason, displayAlert }) => {
+     *   console.log(`Connection ${state}: ${reason}`)
+     *
+     *   if (state === 'offline') {
+     *     // Save state and return to game lobby
+     *     displayAlert?.('Connection lost. Your progress has been saved.', { type: 'error' })
+     *     saveGameState()
+     *     returnToLobby()
+     *   } else if (state === 'degraded') {
+     *     displayAlert?.('Slow connection detected.', { type: 'warning' })
+     *   }
+     * })
+     *
+     * // Later: cleanup() to unregister
+     * ```
+     *
+     * @see {@link DISCONNECT_HANDLING.md} for detailed usage examples
+     * @see {@link ConnectionManager.onDisconnect} for the underlying implementation
+     */
+    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
+    /**
+     * Gets the current connection state.
+     *
+     * Returns the last known connection state without triggering a new check.
+     * Use `checkConnection()` to force an immediate verification.
+     *
+     * @returns Current connection state ('online', 'offline', 'degraded') or 'unknown' if monitoring is disabled
+     *
+     * @example
+     * ```typescript
+     * const state = client.getConnectionState()
+     * if (state === 'offline') {
+     *   console.log('No connection available')
+     * }
+     * ```
+     *
+     * @see {@link checkConnection} to trigger an immediate connection check
+     * @see {@link ConnectionManager.getState} for the underlying implementation
+     */
+    getConnectionState(): ConnectionState | 'unknown';
+    /**
+     * Manually triggers a connection check immediately.
+     *
+     * Forces a heartbeat ping to verify connectivity right now, bypassing the normal
+     * interval. Useful when you need to verify connection status before a critical
+     * operation (e.g., saving important game state).
+     *
+     * @returns Promise resolving to the current connection state after verification
+     *
+     * @example
+     * ```typescript
+     * // Check before critical operation
+     * const state = await client.checkConnection()
+     * if (state !== 'online') {
+     *   alert('Please check your internet connection before saving')
+     *   return
+     * }
+     *
+     * await client.games.saveState(importantData)
+     * ```
+     *
+     * @see {@link getConnectionState} to get the last known state without checking
+     * @see {@link ConnectionManager.checkNow} for the underlying implementation
+     */
+    checkConnection(): Promise<ConnectionState | 'unknown'>;
     /**
      * Sets the authentication context for the client.
      * This is called during initialization to store environment info.
@@ -4607,6 +4719,11 @@ declare class PlaycademyClient {
      * Safe to call in any environment - isInIframe handles browser detection.
      */
     private _detectAuthContext;
+    /**
+     * Initializes connection monitoring if enabled.
+     * Safe to call in any environment - only runs in browser.
+     */
+    private _initializeConnectionMonitor;
     /**
      * Initializes an internal game session for automatic session management.
      * Only starts a session if:
@@ -4808,50 +4925,50 @@ declare class PlaycademyClient {
         };
         items: {
             create: (props: InsertItemInput) => Promise<{
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 id: string;
-                metadata: unknown;
-                slug: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             get: (itemId: string) => Promise<{
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 id: string;
-                metadata: unknown;
-                slug: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             list: () => Promise<{
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 id: string;
-                metadata: unknown;
-                slug: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }[]>;
             update: (itemId: string, props: UpdateItemInput) => Promise<{
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 id: string;
-                metadata: unknown;
-                slug: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
@@ -4986,9 +5103,7 @@ declare class PlaycademyClient {
             }) => Promise<TodayXpResponse>;
             total: () => Promise<TotalXpResponse>;
             history: (options?: {
-                startDate
-                /** Auto-initializes a PlaycademyClient with context from the environment */
-                ?: string;
+                startDate?: string;
                 endDate?: string;
             }) => Promise<XpHistoryResponse>;
             summary: (options?: {
@@ -5109,6 +5224,29 @@ interface ClientConfig {
     tokenType?: TokenType;
     gameId?: string;
     autoStartSession?: boolean;
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+}
+/**
+ * Handler called when connection state changes to offline or degraded.
+ * Games can implement this to handle disconnects gracefully.
+ */
+type DisconnectHandler = (context: DisconnectContext) => void | Promise<void>;
+/**
+ * Context provided to disconnect handlers
+ */
+interface DisconnectContext {
+    /** Current connection state */
+    state: 'offline' | 'degraded';
+    /** Reason for the disconnect */
+    reason: string;
+    /** Timestamp when disconnect was detected */
+    timestamp: number;
+    /** Utility to display a platform-level alert */
+    displayAlert: (message: string, options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    }) => void;
 }
 interface InitPayload {
     /** Hub API base URL */
@@ -5254,6 +5392,32 @@ interface KeyEventPayload {
     /** Event type */
     type: 'keydown' | 'keyup';
 }
+interface DisplayAlertPayload {
+    message: string;
+    options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    };
+}
+/**
+ * Display alert payload.
+ * Request from game to show platform-level alert.
+ */
+interface DisplayAlertPayload {
+    message: string;
+    options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    };
+}
+/**
+ * Connection state payload.
+ * Broadcast from platform to games when connection changes.
+ */
+interface ConnectionStatePayload {
+    state: 'online' | 'offline' | 'degraded';
+    reason: string;
+}
 interface ClientEvents {
     authChange: {
         token: string | null;
@@ -5273,6 +5437,10 @@ interface ClientEvents {
         totalXP: number;
         leveledUp: boolean;
     };
+    connectionChange: {
+        state: 'online' | 'offline' | 'degraded';
+        reason: string;
+    };
 }
 type GameContextPayload = {
     token: string;
@@ -5368,4 +5536,4 @@ interface BucketFile {
 }
 
 export { PlaycademyClient };
-export type { Achievement, AchievementCurrent, AchievementProgressResponse, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponent, CharacterComponentWithSpriteUrl, ClientConfig, ClientEvents, Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusResponse, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameLeaderboardEntry, GameSession, GameStateData, GameTokenResponse, GameUser, HostedGame, InitPayload, InventoryItem, InventoryItemWithItem, InventoryMutationResponse, Item, KeyEventPayload, LeaderboardEntry, LevelConfig, LoginResponse, ManifestV1, Map, MapElement, MapElementWithGame, MapObject, MapObjectWithItem, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacter, ShopCurrency, ShopDisplayItem, ShopViewResponse, SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, User, UserInfo, UserLevel, UserLevelWithConfig, UserRank, UserRankResponse, UserRoleEnumType, UserScore$1 as UserScore, XpHistoryResponse };
+export type { Achievement, AchievementCurrent, AchievementProgressResponse, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponent, CharacterComponentWithSpriteUrl, ClientConfig, ClientEvents, ConnectionStatePayload, Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusResponse, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameLeaderboardEntry, GameSession, GameStateData, GameTokenResponse, GameUser, HostedGame, InitPayload, InventoryItem, InventoryItemWithItem, InventoryMutationResponse, Item, KeyEventPayload, LeaderboardEntry, LevelConfig, LoginResponse, ManifestV1, Map, MapElement, MapElementWithGame, MapObject, MapObjectWithItem, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacter, ShopCurrency, ShopDisplayItem, ShopViewResponse, SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, User, UserInfo, UserLevel, UserLevelWithConfig, UserRank, UserRankResponse, UserRoleEnumType, UserScore$1 as UserScore, XpHistoryResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.1.14",
+    "version": "0.1.15",
     "type": "module",
     "exports": {
         ".": {
@@ -37,12 +37,12 @@
         "@playcademy/constants": "0.0.1",
         "@playcademy/data": "0.0.1",
         "@playcademy/logger": "0.0.1",
-        "@playcademy/sandbox": "0.1.9",
+        "@playcademy/sandbox": "0.1.10",
         "@playcademy/test": "0.0.1",
         "@playcademy/timeback": "0.0.1",
         "@playcademy/utils": "0.0.1",
         "@types/bun": "latest",
-        "playcademy": "0.14.4",
+        "playcademy": "0.14.5",
         "rollup": "^4.50.2",
         "rollup-plugin-dts": "^6.2.3",
         "typescript": "^5.7.2"