@playcademy/sdk 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -7,6 +7,21 @@ import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 declare class PlaycademyError extends Error {
     constructor(message: string);
 }
+type CorsProbeResult = 'reachable' | 'unreachable' | 'skipped';
+interface ManifestErrorDetails {
+    manifestUrl: string;
+    manifestHost: string;
+    deploymentUrl: string;
+    fetchOutcome: 'network_error' | 'bad_status' | 'invalid_body';
+    retryCount: number;
+    durationMs: number;
+    fetchErrorMessage?: string;
+    corsProbe?: CorsProbeResult;
+    status?: number;
+    contentType?: string;
+    cfRay?: string;
+    redirected?: boolean;
+}
 /**
  * Error codes returned by the API.
  * These map to specific error types and HTTP status codes.
@@ -855,6 +870,7 @@ declare abstract class PlaycademyBaseClient {
     };
     protected initPayload?: InitPayload;
     protected connectionManager?: ConnectionManager;
+    protected launchId?: string;
     /**
      * Internal session manager for automatic session lifecycle.
      * @private
@@ -883,6 +899,7 @@ declare abstract class PlaycademyBaseClient {
      * Sets the authentication token for API requests.
      */
     setToken(token: string | null, tokenType?: TokenType): void;
+    setLaunchId(launchId: string | null | undefined): void;
     /**
      * Gets the current token type.
      */
@@ -1308,6 +1325,7 @@ interface ClientConfig {
     token?: string;
     tokenType?: TokenType;
     gameId?: string;
+    launchId?: string;
     autoStartSession?: boolean;
     onDisconnect?: DisconnectHandler;
     enableConnectionMonitoring?: boolean;
@@ -2301,4 +2319,4 @@ declare class PlaycademyMessaging {
 declare const messaging: PlaycademyMessaging;
 
 export { ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
-export type { ApiErrorCode, ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody };
+export type { ApiErrorCode, ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, ManifestErrorDetails };

package/dist/index.js

@@ -407,6 +407,18 @@ class PlaycademyError extends Error {
   }
 }
 
+class ManifestError extends PlaycademyError {
+  kind;
+  details;
+  constructor(message, kind, details) {
+    super(message);
+    this.name = "ManifestError";
+    this.kind = kind;
+    this.details = details;
+    Object.setPrototypeOf(this, ManifestError.prototype);
+  }
+}
+
 class ApiError extends Error {
   code;
   details;
@@ -1915,7 +1927,158 @@ class ConnectionManager {
     }
   }
 }
-// src/core/request.ts
+// src/core/transport/retry.ts
+var RETRY_DELAYS_MS = [500, 1500];
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var retryRuntime = { wait };
+function isRetryableStatus(status) {
+  return status === 429 || status >= 500;
+}
+async function fetchWithRetry(url, init2) {
+  const startedAt = Date.now();
+  for (let attempt = 0;attempt <= RETRY_DELAYS_MS.length; attempt++) {
+    const retryDelayMs = RETRY_DELAYS_MS[attempt];
+    const canRetry = init2.method === "GET" && retryDelayMs !== undefined;
+    try {
+      const response = await fetch(url, init2);
+      if (canRetry && isRetryableStatus(response.status)) {
+        await retryRuntime.wait(retryDelayMs);
+      } else {
+        return { response, retryCount: attempt, durationMs: Date.now() - startedAt };
+      }
+    } catch (error) {
+      if (canRetry && error instanceof TypeError) {
+        await retryRuntime.wait(retryDelayMs);
+      } else {
+        return { error, retryCount: attempt, durationMs: Date.now() - startedAt };
+      }
+    }
+  }
+  return {
+    error: new PlaycademyError("Request failed after exhausting retries"),
+    retryCount: RETRY_DELAYS_MS.length,
+    durationMs: Date.now() - startedAt
+  };
+}
+function unwrapFetchResult(result) {
+  if (result.error) {
+    throw result.error;
+  }
+  if (!result.response) {
+    throw new PlaycademyError("Request failed after exhausting retries");
+  }
+  return result.response;
+}
+// src/core/transport/manifest.ts
+var CORS_PROBE_TIMEOUT_MS = 3000;
+async function probeCorsReachability(url) {
+  if (typeof globalThis.AbortController === "undefined") {
+    return "skipped";
+  }
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), CORS_PROBE_TIMEOUT_MS);
+  try {
+    await fetch(url, { mode: "no-cors", signal: controller.signal });
+    return "reachable";
+  } catch {
+    return "unreachable";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var MAX_FETCH_ERROR_MESSAGE_LENGTH = 512;
+function getFetchErrorMessage(error) {
+  let raw;
+  if (error instanceof Error) {
+    raw = error.message;
+  } else if (typeof error === "string") {
+    raw = error;
+  }
+  if (!raw) {
+    return;
+  }
+  const normalized = raw.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return;
+  }
+  return normalized.slice(0, MAX_FETCH_ERROR_MESSAGE_LENGTH);
+}
+async function fetchManifest(deploymentUrl) {
+  const manifestUrl = `${deploymentUrl.replace(/\/$/, "")}/playcademy.manifest.json`;
+  const result = await fetchWithRetry(manifestUrl, { method: "GET" });
+  let manifestHost;
+  try {
+    manifestHost = new URL(manifestUrl).host;
+  } catch {
+    manifestHost = manifestUrl;
+  }
+  const base = {
+    manifestUrl,
+    manifestHost,
+    deploymentUrl,
+    retryCount: result.retryCount,
+    durationMs: result.durationMs
+  };
+  if (result.error || !result.response) {
+    log.error(`[Playcademy SDK] Error fetching manifest from ${manifestUrl}:`, {
+      error: result.error
+    });
+    throw new ManifestError("Failed to load game manifest", "temporary", {
+      ...base,
+      fetchOutcome: "network_error",
+      ...result.error ? { fetchErrorMessage: getFetchErrorMessage(result.error) } : {}
+    });
+  }
+  const response = result.response;
+  if (!response.ok) {
+    log.error(`[fetchManifest] Failed to fetch manifest from ${manifestUrl}. Status: ${response.status}`);
+    throw new ManifestError(`Failed to fetch manifest: ${response.status} ${response.statusText}`, isRetryableStatus(response.status) ? "temporary" : "permanent", {
+      ...base,
+      fetchOutcome: "bad_status",
+      status: response.status,
+      contentType: response.headers.get("content-type") ?? undefined,
+      cfRay: response.headers.get("cf-ray") ?? undefined,
+      redirected: response.redirected
+    });
+  }
+  try {
+    return await response.json();
+  } catch (error) {
+    log.error(`[Playcademy SDK] Error parsing manifest from ${manifestUrl}:`, {
+      error
+    });
+    throw new ManifestError("Failed to parse game manifest", "permanent", {
+      ...base,
+      fetchOutcome: "invalid_body",
+      status: response.status,
+      contentType: response.headers.get("content-type") ?? undefined,
+      cfRay: response.headers.get("cf-ray") ?? undefined,
+      redirected: response.redirected
+    });
+  }
+}
+// src/core/transport/request.ts
+function prepareRequestBody(body, headers) {
+  if (body instanceof FormData) {
+    return body;
+  }
+  if (body instanceof ArrayBuffer || body instanceof Blob || ArrayBuffer.isView(body)) {
+    if (!headers["Content-Type"]) {
+      headers["Content-Type"] = "application/octet-stream";
+    }
+    return body;
+  }
+  if (body !== undefined && body !== null) {
+    if (headers["Content-Type"]) {
+      return typeof body === "string" ? body : JSON.stringify(body);
+    }
+    headers["Content-Type"] = "application/json";
+    return JSON.stringify(body);
+  }
+  return;
+}
 function checkDevWarnings(data) {
   if (!data || typeof data !== "object") {
     return;
@@ -1943,25 +2106,6 @@ function checkDevWarnings(data) {
     }
   }
 }
-function prepareRequestBody(body, headers) {
-  if (body instanceof FormData) {
-    return body;
-  }
-  if (body instanceof ArrayBuffer || body instanceof Blob || ArrayBuffer.isView(body)) {
-    if (!headers["Content-Type"]) {
-      headers["Content-Type"] = "application/octet-stream";
-    }
-    return body;
-  }
-  if (body !== undefined && body !== null) {
-    if (headers["Content-Type"]) {
-      return typeof body === "string" ? body : JSON.stringify(body);
-    }
-    headers["Content-Type"] = "application/json";
-    return JSON.stringify(body);
-  }
-  return;
-}
 async function request({
   path,
   baseUrl,
@@ -1973,12 +2117,12 @@ async function request({
   const url = baseUrl.replace(/\/$/, "") + (path.startsWith("/") ? path : `/${path}`);
   const headers = { ...extraHeaders };
   const payload = prepareRequestBody(body, headers);
-  const res = await fetch(url, {
+  const res = unwrapFetchResult(await fetchWithRetry(url, {
     method,
     headers,
     body: payload,
     credentials: "omit"
-  });
+  }));
   if (raw) {
     return res;
   }
@@ -2008,26 +2152,6 @@ async function request({
   const rawText = await res.text().catch(() => "");
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
-async function fetchManifest(deploymentUrl) {
-  const manifestUrl = `${deploymentUrl.replace(/\/$/, "")}/playcademy.manifest.json`;
-  try {
-    const response = await fetch(manifestUrl);
-    if (!response.ok) {
-      log.error(`[fetchManifest] Failed to fetch manifest from ${manifestUrl}. Status: ${response.status}`);
-      throw new PlaycademyError(`Failed to fetch manifest: ${response.status} ${response.statusText}`);
-    }
-    return await response.json();
-  } catch (error) {
-    if (error instanceof PlaycademyError) {
-      throw error;
-    }
-    log.error(`[Playcademy SDK] Error fetching or parsing manifest from ${manifestUrl}:`, {
-      error
-    });
-    throw new PlaycademyError("Failed to load or parse game manifest");
-  }
-}
-
 // src/clients/base.ts
 class PlaycademyBaseClient {
   baseUrl;
@@ -2040,6 +2164,7 @@ class PlaycademyBaseClient {
   authContext;
   initPayload;
   connectionManager;
+  launchId;
   _sessionManager = {
     startSession: async (gameId) => this.request(`/games/${gameId}/sessions`, "POST"),
     endSession: async (sessionId, gameId) => this.request(`/games/${gameId}/sessions/${sessionId}`, "DELETE")
@@ -2048,6 +2173,7 @@ class PlaycademyBaseClient {
     this.baseUrl = config?.baseUrl?.endsWith("/api") ? config.baseUrl : `${config?.baseUrl}/api`;
     this.gameUrl = config?.gameUrl;
     this.gameId = config?.gameId;
+    this.launchId = config?.launchId ?? undefined;
     this.config = config || {};
     this.authStrategy = createAuthStrategy(config?.token ?? null, config?.tokenType);
     this._detectAuthContext();
@@ -2075,6 +2201,9 @@ class PlaycademyBaseClient {
     this.authStrategy = createAuthStrategy(token, tokenType);
     this.emit("authChange", { token });
   }
+  setLaunchId(launchId) {
+    this.launchId = launchId ?? undefined;
+  }
   getTokenType() {
     return this.authStrategy.getType();
   }
@@ -2117,7 +2246,8 @@ class PlaycademyBaseClient {
   async request(path, method, options) {
     const effectiveHeaders = {
       ...options?.headers,
-      ...this.authStrategy.getHeaders()
+      ...this.authStrategy.getHeaders(),
+      ...this.launchId ? { "x-playcademy-launch-id": this.launchId } : {}
     };
     try {
       const result = await request({

package/dist/internal.d.ts

@@ -5,6 +5,9 @@ import { z } from 'zod';
 import { SchemaInfo } from '@playcademy/cloudflare';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
+/** Permitted HTTP verbs */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
 /**
  * Game Types
  *
@@ -82,8 +85,181 @@ interface DomainValidationRecords {
     }[];
 }
 
-/** Permitted HTTP verbs */
-type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Base error class for Cademy SDK specific errors.
+ */
+declare class PlaycademyError extends Error {
+    constructor(message: string);
+}
+type ManifestErrorKind = 'temporary' | 'permanent';
+type CorsProbeResult = 'reachable' | 'unreachable' | 'skipped';
+interface ManifestErrorDetails {
+    manifestUrl: string;
+    manifestHost: string;
+    deploymentUrl: string;
+    fetchOutcome: 'network_error' | 'bad_status' | 'invalid_body';
+    retryCount: number;
+    durationMs: number;
+    fetchErrorMessage?: string;
+    corsProbe?: CorsProbeResult;
+    status?: number;
+    contentType?: string;
+    cfRay?: string;
+    redirected?: boolean;
+}
+declare class ManifestError extends PlaycademyError {
+    readonly kind: ManifestErrorKind;
+    readonly details: ManifestErrorDetails | undefined;
+    constructor(message: string, kind: ManifestErrorKind, details?: ManifestErrorDetails);
+}
+/**
+ * Error codes returned by the API.
+ * These map to specific error types and HTTP status codes.
+ */
+type ApiErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'ACCESS_DENIED' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'ALREADY_EXISTS' | 'GONE' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_FAILED' | 'TOO_MANY_REQUESTS' | 'RATE_LIMITED' | 'EXPIRED' | 'INTERNAL' | 'INTERNAL_ERROR' | 'NOT_IMPLEMENTED' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | string;
+/**
+ * Structure of error response bodies returned by API endpoints.
+ *
+ * @example
+ * ```json
+ * {
+ *   "error": {
+ *     "code": "NOT_FOUND",
+ *     "message": "Item not found",
+ *     "details": { "identifier": "abc123" }
+ *   }
+ * }
+ * ```
+ */
+interface ErrorResponseBody {
+    error?: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/**
+ * API error thrown when a request fails.
+ *
+ * Contains structured error information from the API response:
+ * - `status` - HTTP status code (e.g., 404)
+ * - `code` - API error code (e.g., "NOT_FOUND")
+ * - `message` - Human-readable error message
+ * - `details` - Optional additional error context
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.games.get('nonexistent')
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.log(error.status)   // 404
+ *     console.log(error.code)     // "NOT_FOUND"
+ *     console.log(error.message)  // "Game not found"
+ *     console.log(error.details)  // { identifier: "nonexistent" }
+ *   }
+ * }
+ * ```
+ */
+declare class ApiError extends Error {
+    /**
+     * API error code (e.g., "NOT_FOUND", "VALIDATION_FAILED").
+     * Use this for programmatic error handling.
+     */
+    readonly code: ApiErrorCode;
+    /**
+     * Additional error context from the API.
+     * Structure varies by error type (e.g., validation errors include field details).
+     */
+    readonly details: unknown;
+    /**
+     * Raw response body for debugging.
+     * @internal
+     */
+    readonly rawBody: unknown;
+    readonly status: number;
+    constructor(
+    /** HTTP status code */
+    status: number, 
+    /** API error code */
+    code: ApiErrorCode, 
+    /** Human-readable error message */
+    message: string, 
+    /** Additional error context */
+    details?: unknown, 
+    /** Raw response body */
+    rawBody?: unknown);
+    /**
+     * Create an ApiError from an HTTP response.
+     * Parses the structured error response from the API.
+     *
+     * @internal
+     */
+    static fromResponse(status: number, statusText: string, body: unknown): ApiError;
+    /**
+     * Check if this is a specific error type.
+     *
+     * @example
+     * ```typescript
+     * if (error.is('NOT_FOUND')) {
+     *   // Handle not found
+     * } else if (error.is('VALIDATION_FAILED')) {
+     *   // Handle validation error
+     * }
+     * ```
+     */
+    is(code: ApiErrorCode): boolean;
+    /**
+     * Check if this is a client error (4xx).
+     */
+    isClientError(): boolean;
+    /**
+     * Check if this is a server error (5xx).
+     */
+    isServerError(): boolean;
+    /**
+     * Check if this error is retryable.
+     * Server errors and rate limits are typically retryable.
+     */
+    isRetryable(): boolean;
+}
+/**
+ * Extracted error information for display purposes.
+ */
+interface ApiErrorInfo {
+    /** HTTP status code */
+    status: number;
+    /** API error code */
+    code: ApiErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error context */
+    details?: unknown;
+}
+/**
+ * Extract useful error information from an API error.
+ * Useful for displaying errors to users in a friendly way.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.shop.purchase(itemId)
+ * } catch (error) {
+ *   const info = extractApiErrorInfo(error)
+ *   if (info) {
+ *     showToast(`Error: ${info.message}`)
+ *   }
+ * }
+ * ```
+ */
+declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
+
+/**
+ * Fire-and-forget reachability check using `no-cors` mode.
+ * Exported for use by the app telemetry layer — not awaited inside
+ * fetchManifest so it doesn't block the error screen.
+ */
+declare function probeCorsReachability(url: string): Promise<CorsProbeResult>;
 
 /**
  * User Types
@@ -935,154 +1111,6 @@ interface SpriteConfigWithDimensions {
     animations: Record<string, SpriteAnimationFrame>;
 }
 
-/**
- * Base error class for Cademy SDK specific errors.
- */
-declare class PlaycademyError extends Error {
-    constructor(message: string);
-}
-/**
- * Error codes returned by the API.
- * These map to specific error types and HTTP status codes.
- */
-type ApiErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'ACCESS_DENIED' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'ALREADY_EXISTS' | 'GONE' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_FAILED' | 'TOO_MANY_REQUESTS' | 'RATE_LIMITED' | 'EXPIRED' | 'INTERNAL' | 'INTERNAL_ERROR' | 'NOT_IMPLEMENTED' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | string;
-/**
- * Structure of error response bodies returned by API endpoints.
- *
- * @example
- * ```json
- * {
- *   "error": {
- *     "code": "NOT_FOUND",
- *     "message": "Item not found",
- *     "details": { "identifier": "abc123" }
- *   }
- * }
- * ```
- */
-interface ErrorResponseBody {
-    error?: {
-        code?: string;
-        message?: string;
-        details?: unknown;
-    };
-}
-/**
- * API error thrown when a request fails.
- *
- * Contains structured error information from the API response:
- * - `status` - HTTP status code (e.g., 404)
- * - `code` - API error code (e.g., "NOT_FOUND")
- * - `message` - Human-readable error message
- * - `details` - Optional additional error context
- *
- * @example
- * ```typescript
- * try {
- *   await client.games.get('nonexistent')
- * } catch (error) {
- *   if (error instanceof ApiError) {
- *     console.log(error.status)   // 404
- *     console.log(error.code)     // "NOT_FOUND"
- *     console.log(error.message)  // "Game not found"
- *     console.log(error.details)  // { identifier: "nonexistent" }
- *   }
- * }
- * ```
- */
-declare class ApiError extends Error {
-    /**
-     * API error code (e.g., "NOT_FOUND", "VALIDATION_FAILED").
-     * Use this for programmatic error handling.
-     */
-    readonly code: ApiErrorCode;
-    /**
-     * Additional error context from the API.
-     * Structure varies by error type (e.g., validation errors include field details).
-     */
-    readonly details: unknown;
-    /**
-     * Raw response body for debugging.
-     * @internal
-     */
-    readonly rawBody: unknown;
-    readonly status: number;
-    constructor(
-    /** HTTP status code */
-    status: number, 
-    /** API error code */
-    code: ApiErrorCode, 
-    /** Human-readable error message */
-    message: string, 
-    /** Additional error context */
-    details?: unknown, 
-    /** Raw response body */
-    rawBody?: unknown);
-    /**
-     * Create an ApiError from an HTTP response.
-     * Parses the structured error response from the API.
-     *
-     * @internal
-     */
-    static fromResponse(status: number, statusText: string, body: unknown): ApiError;
-    /**
-     * Check if this is a specific error type.
-     *
-     * @example
-     * ```typescript
-     * if (error.is('NOT_FOUND')) {
-     *   // Handle not found
-     * } else if (error.is('VALIDATION_FAILED')) {
-     *   // Handle validation error
-     * }
-     * ```
-     */
-    is(code: ApiErrorCode): boolean;
-    /**
-     * Check if this is a client error (4xx).
-     */
-    isClientError(): boolean;
-    /**
-     * Check if this is a server error (5xx).
-     */
-    isServerError(): boolean;
-    /**
-     * Check if this error is retryable.
-     * Server errors and rate limits are typically retryable.
-     */
-    isRetryable(): boolean;
-}
-/**
- * Extracted error information for display purposes.
- */
-interface ApiErrorInfo {
-    /** HTTP status code */
-    status: number;
-    /** API error code */
-    code: ApiErrorCode;
-    /** Human-readable error message */
-    message: string;
-    /** Additional error context */
-    details?: unknown;
-}
-/**
- * Extract useful error information from an API error.
- * Useful for displaying errors to users in a friendly way.
- *
- * @example
- * ```typescript
- * try {
- *   await client.shop.purchase(itemId)
- * } catch (error) {
- *   const info = extractApiErrorInfo(error)
- *   if (info) {
- *     showToast(`Error: ${info.message}`)
- *   }
- * }
- * ```
- */
-declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
-
 /**
  * Connection monitoring types
  *
@@ -5629,6 +5657,7 @@ declare abstract class PlaycademyBaseClient {
     };
     protected initPayload?: InitPayload;
     protected connectionManager?: ConnectionManager;
+    protected launchId?: string;
     /**
      * Internal session manager for automatic session lifecycle.
      * @private
@@ -5657,6 +5686,7 @@ declare abstract class PlaycademyBaseClient {
      * Sets the authentication token for API requests.
      */
     setToken(token: string | null, tokenType?: TokenType): void;
+    setLaunchId(launchId: string | null | undefined): void;
     /**
      * Gets the current token type.
      */
@@ -5954,6 +5984,7 @@ interface ClientConfig {
     token?: string;
     tokenType?: TokenType;
     gameId?: string;
+    launchId?: string;
     autoStartSession?: boolean;
     onDisconnect?: DisconnectHandler;
     enableConnectionMonitoring?: boolean;
@@ -7629,5 +7660,5 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
     };
 }
 
-export { AchievementCompletionType, ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, NotificationStatus, NotificationType, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging };
-export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };
+export { AchievementCompletionType, ApiError, ConnectionManager, ConnectionMonitor, ManifestError, MessageEvents, NotificationStatus, NotificationType, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging, probeCorsReachability };
+export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, CorsProbeResult, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestErrorDetails, ManifestV1, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };

package/dist/internal.js

@@ -407,6 +407,18 @@ class PlaycademyError extends Error {
   }
 }
 
+class ManifestError extends PlaycademyError {
+  kind;
+  details;
+  constructor(message, kind, details) {
+    super(message);
+    this.name = "ManifestError";
+    this.kind = kind;
+    this.details = details;
+    Object.setPrototypeOf(this, ManifestError.prototype);
+  }
+}
+
 class ApiError extends Error {
   code;
   details;
@@ -2026,7 +2038,158 @@ function createDevNamespace(client) {
     }
   };
 }
-// src/core/request.ts
+// src/core/transport/retry.ts
+var RETRY_DELAYS_MS = [500, 1500];
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var retryRuntime = { wait };
+function isRetryableStatus(status) {
+  return status === 429 || status >= 500;
+}
+async function fetchWithRetry(url, init2) {
+  const startedAt = Date.now();
+  for (let attempt = 0;attempt <= RETRY_DELAYS_MS.length; attempt++) {
+    const retryDelayMs = RETRY_DELAYS_MS[attempt];
+    const canRetry = init2.method === "GET" && retryDelayMs !== undefined;
+    try {
+      const response = await fetch(url, init2);
+      if (canRetry && isRetryableStatus(response.status)) {
+        await retryRuntime.wait(retryDelayMs);
+      } else {
+        return { response, retryCount: attempt, durationMs: Date.now() - startedAt };
+      }
+    } catch (error) {
+      if (canRetry && error instanceof TypeError) {
+        await retryRuntime.wait(retryDelayMs);
+      } else {
+        return { error, retryCount: attempt, durationMs: Date.now() - startedAt };
+      }
+    }
+  }
+  return {
+    error: new PlaycademyError("Request failed after exhausting retries"),
+    retryCount: RETRY_DELAYS_MS.length,
+    durationMs: Date.now() - startedAt
+  };
+}
+function unwrapFetchResult(result) {
+  if (result.error) {
+    throw result.error;
+  }
+  if (!result.response) {
+    throw new PlaycademyError("Request failed after exhausting retries");
+  }
+  return result.response;
+}
+// src/core/transport/manifest.ts
+var CORS_PROBE_TIMEOUT_MS = 3000;
+async function probeCorsReachability(url) {
+  if (typeof globalThis.AbortController === "undefined") {
+    return "skipped";
+  }
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), CORS_PROBE_TIMEOUT_MS);
+  try {
+    await fetch(url, { mode: "no-cors", signal: controller.signal });
+    return "reachable";
+  } catch {
+    return "unreachable";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var MAX_FETCH_ERROR_MESSAGE_LENGTH = 512;
+function getFetchErrorMessage(error) {
+  let raw;
+  if (error instanceof Error) {
+    raw = error.message;
+  } else if (typeof error === "string") {
+    raw = error;
+  }
+  if (!raw) {
+    return;
+  }
+  const normalized = raw.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return;
+  }
+  return normalized.slice(0, MAX_FETCH_ERROR_MESSAGE_LENGTH);
+}
+async function fetchManifest(deploymentUrl) {
+  const manifestUrl = `${deploymentUrl.replace(/\/$/, "")}/playcademy.manifest.json`;
+  const result = await fetchWithRetry(manifestUrl, { method: "GET" });
+  let manifestHost;
+  try {
+    manifestHost = new URL(manifestUrl).host;
+  } catch {
+    manifestHost = manifestUrl;
+  }
+  const base = {
+    manifestUrl,
+    manifestHost,
+    deploymentUrl,
+    retryCount: result.retryCount,
+    durationMs: result.durationMs
+  };
+  if (result.error || !result.response) {
+    log.error(`[Playcademy SDK] Error fetching manifest from ${manifestUrl}:`, {
+      error: result.error
+    });
+    throw new ManifestError("Failed to load game manifest", "temporary", {
+      ...base,
+      fetchOutcome: "network_error",
+      ...result.error ? { fetchErrorMessage: getFetchErrorMessage(result.error) } : {}
+    });
+  }
+  const response = result.response;
+  if (!response.ok) {
+    log.error(`[fetchManifest] Failed to fetch manifest from ${manifestUrl}. Status: ${response.status}`);
+    throw new ManifestError(`Failed to fetch manifest: ${response.status} ${response.statusText}`, isRetryableStatus(response.status) ? "temporary" : "permanent", {
+      ...base,
+      fetchOutcome: "bad_status",
+      status: response.status,
+      contentType: response.headers.get("content-type") ?? undefined,
+      cfRay: response.headers.get("cf-ray") ?? undefined,
+      redirected: response.redirected
+    });
+  }
+  try {
+    return await response.json();
+  } catch (error) {
+    log.error(`[Playcademy SDK] Error parsing manifest from ${manifestUrl}:`, {
+      error
+    });
+    throw new ManifestError("Failed to parse game manifest", "permanent", {
+      ...base,
+      fetchOutcome: "invalid_body",
+      status: response.status,
+      contentType: response.headers.get("content-type") ?? undefined,
+      cfRay: response.headers.get("cf-ray") ?? undefined,
+      redirected: response.redirected
+    });
+  }
+}
+// src/core/transport/request.ts
+function prepareRequestBody(body, headers) {
+  if (body instanceof FormData) {
+    return body;
+  }
+  if (body instanceof ArrayBuffer || body instanceof Blob || ArrayBuffer.isView(body)) {
+    if (!headers["Content-Type"]) {
+      headers["Content-Type"] = "application/octet-stream";
+    }
+    return body;
+  }
+  if (body !== undefined && body !== null) {
+    if (headers["Content-Type"]) {
+      return typeof body === "string" ? body : JSON.stringify(body);
+    }
+    headers["Content-Type"] = "application/json";
+    return JSON.stringify(body);
+  }
+  return;
+}
 function checkDevWarnings(data) {
   if (!data || typeof data !== "object") {
     return;
@@ -2054,25 +2217,6 @@ function checkDevWarnings(data) {
     }
   }
 }
-function prepareRequestBody(body, headers) {
-  if (body instanceof FormData) {
-    return body;
-  }
-  if (body instanceof ArrayBuffer || body instanceof Blob || ArrayBuffer.isView(body)) {
-    if (!headers["Content-Type"]) {
-      headers["Content-Type"] = "application/octet-stream";
-    }
-    return body;
-  }
-  if (body !== undefined && body !== null) {
-    if (headers["Content-Type"]) {
-      return typeof body === "string" ? body : JSON.stringify(body);
-    }
-    headers["Content-Type"] = "application/json";
-    return JSON.stringify(body);
-  }
-  return;
-}
 async function request({
   path,
   baseUrl,
@@ -2084,12 +2228,12 @@ async function request({
   const url = baseUrl.replace(/\/$/, "") + (path.startsWith("/") ? path : `/${path}`);
   const headers = { ...extraHeaders };
   const payload = prepareRequestBody(body, headers);
-  const res = await fetch(url, {
+  const res = unwrapFetchResult(await fetchWithRetry(url, {
     method,
     headers,
     body: payload,
     credentials: "omit"
-  });
+  }));
   if (raw) {
     return res;
   }
@@ -2119,26 +2263,6 @@ async function request({
   const rawText = await res.text().catch(() => "");
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
-async function fetchManifest(deploymentUrl) {
-  const manifestUrl = `${deploymentUrl.replace(/\/$/, "")}/playcademy.manifest.json`;
-  try {
-    const response = await fetch(manifestUrl);
-    if (!response.ok) {
-      log.error(`[fetchManifest] Failed to fetch manifest from ${manifestUrl}. Status: ${response.status}`);
-      throw new PlaycademyError(`Failed to fetch manifest: ${response.status} ${response.statusText}`);
-    }
-    return await response.json();
-  } catch (error) {
-    if (error instanceof PlaycademyError) {
-      throw error;
-    }
-    log.error(`[Playcademy SDK] Error fetching or parsing manifest from ${manifestUrl}:`, {
-      error
-    });
-    throw new PlaycademyError("Failed to load or parse game manifest");
-  }
-}
-
 // src/namespaces/platform/games.ts
 function createGamesNamespace(client) {
   const gamesListCache = createTTLCache({
@@ -2956,6 +3080,7 @@ class PlaycademyBaseClient {
   authContext;
   initPayload;
   connectionManager;
+  launchId;
   _sessionManager = {
     startSession: async (gameId) => this.request(`/games/${gameId}/sessions`, "POST"),
     endSession: async (sessionId, gameId) => this.request(`/games/${gameId}/sessions/${sessionId}`, "DELETE")
@@ -2964,6 +3089,7 @@ class PlaycademyBaseClient {
     this.baseUrl = config?.baseUrl?.endsWith("/api") ? config.baseUrl : `${config?.baseUrl}/api`;
     this.gameUrl = config?.gameUrl;
     this.gameId = config?.gameId;
+    this.launchId = config?.launchId ?? undefined;
     this.config = config || {};
     this.authStrategy = createAuthStrategy(config?.token ?? null, config?.tokenType);
     this._detectAuthContext();
@@ -2991,6 +3117,9 @@ class PlaycademyBaseClient {
     this.authStrategy = createAuthStrategy(token, tokenType);
     this.emit("authChange", { token });
   }
+  setLaunchId(launchId) {
+    this.launchId = launchId ?? undefined;
+  }
   getTokenType() {
     return this.authStrategy.getType();
   }
@@ -3033,7 +3162,8 @@ class PlaycademyBaseClient {
   async request(path, method, options) {
     const effectiveHeaders = {
       ...options?.headers,
-      ...this.authStrategy.getHeaders()
+      ...this.authStrategy.getHeaders(),
+      ...this.launchId ? { "x-playcademy-launch-id": this.launchId } : {}
     };
     try {
       const result = await request({
@@ -3154,12 +3284,14 @@ class PlaycademyInternalClient extends PlaycademyBaseClient {
   static identity = identity;
 }
 export {
+  probeCorsReachability,
   messaging,
   extractApiErrorInfo,
   PlaycademyInternalClient,
   PlaycademyError,
   PlaycademyInternalClient as PlaycademyClient,
   MessageEvents,
+  ManifestError,
   ConnectionMonitor,
   ConnectionManager,
   ApiError

package/dist/server.js

@@ -81,6 +81,18 @@ class PlaycademyError extends Error {
   }
 }
 
+class ManifestError extends PlaycademyError {
+  kind;
+  details;
+  constructor(message, kind, details) {
+    super(message);
+    this.name = "ManifestError";
+    this.kind = kind;
+    this.details = details;
+    Object.setPrototypeOf(this, ManifestError.prototype);
+  }
+}
+
 class ApiError extends Error {
   code;
   details;

package/dist/types.d.ts

@@ -19,6 +19,9 @@ declare function parseOAuthState(state: string): {
     data?: Record<string, string>;
 };
 
+/** Permitted HTTP verbs */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
 /**
  * Game Types
  *
@@ -49,9 +52,6 @@ interface DomainValidationRecords {
     }[];
 }
 
-/** Permitted HTTP verbs */
-type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-
 /**
  * User Types
  *
@@ -4735,6 +4735,7 @@ declare abstract class PlaycademyBaseClient {
     };
     protected initPayload?: InitPayload;
     protected connectionManager?: ConnectionManager;
+    protected launchId?: string;
     /**
      * Internal session manager for automatic session lifecycle.
      * @private
@@ -4763,6 +4764,7 @@ declare abstract class PlaycademyBaseClient {
      * Sets the authentication token for API requests.
      */
     setToken(token: string | null, tokenType?: TokenType): void;
+    setLaunchId(launchId: string | null | undefined): void;
     /**
      * Gets the current token type.
      */
@@ -5188,6 +5190,7 @@ interface ClientConfig {
     token?: string;
     tokenType?: TokenType;
     gameId?: string;
+    launchId?: string;
     autoStartSession?: boolean;
     onDisconnect?: DisconnectHandler;
     enableConnectionMonitoring?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.3.2",
+    "version": "0.3.4",
     "type": "module",
     "exports": {
         ".": {
@@ -35,10 +35,10 @@
     ],
     "scripts": {
         "build": "bun build.js",
+        "docs": "typedoc",
         "pub": "bun publish.ts",
         "test": "bun test",
-        "test:watch": "bun test --watch",
-        "docs": "typedoc"
+        "test:watch": "bun test --watch"
     },
     "devDependencies": {
         "@inquirer/prompts": "^7.8.6",