@playcademy/sdk 0.3.3 → 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.
@@ -2304,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

@@ -409,10 +409,12 @@ class PlaycademyError extends Error {
 
 class ManifestError extends PlaycademyError {
   kind;
-  constructor(message, kind) {
+  details;
+  constructor(message, kind, details) {
     super(message);
     this.name = "ManifestError";
     this.kind = kind;
+    this.details = details;
     Object.setPrototypeOf(this, ManifestError.prototype);
   }
 }
@@ -1925,7 +1927,7 @@ 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));
@@ -1935,6 +1937,7 @@ 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;
@@ -1943,18 +1946,120 @@ async function fetchWithRetry(url, init2) {
       if (canRetry && isRetryableStatus(response.status)) {
         await retryRuntime.wait(retryDelayMs);
       } else {
-        return response;
+        return { response, retryCount: attempt, durationMs: Date.now() - startedAt };
       }
     } catch (error) {
       if (canRetry && error instanceof TypeError) {
         await retryRuntime.wait(retryDelayMs);
       } else {
-        throw error;
+        return { error, retryCount: attempt, durationMs: Date.now() - startedAt };
       }
     }
   }
-  throw new PlaycademyError("Request failed after exhausting retries");
+  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;
@@ -2012,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 fetchWithRetry(url, {
+  const res = unwrapFetchResult(await fetchWithRetry(url, {
     method,
     headers,
     body: payload,
     credentials: "omit"
-  });
+  }));
   if (raw) {
     return res;
   }
@@ -2047,31 +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`;
-  let response;
-  try {
-    response = await fetchWithRetry(manifestUrl, { method: "GET" });
-  } catch (error) {
-    log.error(`[Playcademy SDK] Error fetching manifest from ${manifestUrl}:`, {
-      error
-    });
-    throw new ManifestError("Failed to load game manifest", "temporary");
-  }
-  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");
-  }
-  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");
-  }
-}
-
 // src/clients/base.ts
 class PlaycademyBaseClient {
   baseUrl;

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,159 +1111,6 @@ interface SpriteConfigWithDimensions {
     animations: Record<string, SpriteAnimationFrame>;
 }
 
-/**
- * Base error class for Cademy SDK specific errors.
- */
-declare class PlaycademyError extends Error {
-    constructor(message: string);
-}
-type ManifestErrorKind = 'temporary' | 'permanent';
-declare class ManifestError extends PlaycademyError {
-    readonly kind: ManifestErrorKind;
-    constructor(message: string, kind: ManifestErrorKind);
-}
-/**
- * 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
  *
@@ -7637,5 +7660,5 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
     };
 }
 
-export { AchievementCompletionType, ApiError, ConnectionManager, ConnectionMonitor, ManifestError, 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

@@ -409,10 +409,12 @@ class PlaycademyError extends Error {
 
 class ManifestError extends PlaycademyError {
   kind;
-  constructor(message, kind) {
+  details;
+  constructor(message, kind, details) {
     super(message);
     this.name = "ManifestError";
     this.kind = kind;
+    this.details = details;
     Object.setPrototypeOf(this, ManifestError.prototype);
   }
 }
@@ -2036,7 +2038,7 @@ 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));
@@ -2046,6 +2048,7 @@ 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;
@@ -2054,18 +2057,120 @@ async function fetchWithRetry(url, init2) {
       if (canRetry && isRetryableStatus(response.status)) {
         await retryRuntime.wait(retryDelayMs);
       } else {
-        return response;
+        return { response, retryCount: attempt, durationMs: Date.now() - startedAt };
       }
     } catch (error) {
       if (canRetry && error instanceof TypeError) {
         await retryRuntime.wait(retryDelayMs);
       } else {
-        throw error;
+        return { error, retryCount: attempt, durationMs: Date.now() - startedAt };
       }
     }
   }
-  throw new PlaycademyError("Request failed after exhausting retries");
+  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;
@@ -2123,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 fetchWithRetry(url, {
+  const res = unwrapFetchResult(await fetchWithRetry(url, {
     method,
     headers,
     body: payload,
     credentials: "omit"
-  });
+  }));
   if (raw) {
     return res;
   }
@@ -2158,31 +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`;
-  let response;
-  try {
-    response = await fetchWithRetry(manifestUrl, { method: "GET" });
-  } catch (error) {
-    log.error(`[Playcademy SDK] Error fetching manifest from ${manifestUrl}:`, {
-      error
-    });
-    throw new ManifestError("Failed to load game manifest", "temporary");
-  }
-  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");
-  }
-  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");
-  }
-}
-
 // src/namespaces/platform/games.ts
 function createGamesNamespace(client) {
   const gamesListCache = createTTLCache({
@@ -3204,6 +3284,7 @@ class PlaycademyInternalClient extends PlaycademyBaseClient {
   static identity = identity;
 }
 export {
+  probeCorsReachability,
   messaging,
   extractApiErrorInfo,
   PlaycademyInternalClient,

package/dist/server.js

@@ -83,10 +83,12 @@ class PlaycademyError extends Error {
 
 class ManifestError extends PlaycademyError {
   kind;
-  constructor(message, kind) {
+  details;
+  constructor(message, kind, details) {
     super(message);
     this.name = "ManifestError";
     this.kind = kind;
+    this.details = details;
     Object.setPrototypeOf(this, ManifestError.prototype);
   }
 }

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
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.3.3",
+    "version": "0.3.4",
     "type": "module",
     "exports": {
         ".": {