@playcademy/sdk 0.3.2 → 0.3.3

package/dist/index.d.ts

@@ -855,6 +855,7 @@ declare abstract class PlaycademyBaseClient {
     };
     protected initPayload?: InitPayload;
     protected connectionManager?: ConnectionManager;
+    protected launchId?: string;
     /**
      * Internal session manager for automatic session lifecycle.
      * @private
@@ -883,6 +884,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 +1310,7 @@ interface ClientConfig {
     token?: string;
     tokenType?: TokenType;
     gameId?: string;
+    launchId?: string;
     autoStartSession?: boolean;
     onDisconnect?: DisconnectHandler;
     enableConnectionMonitoring?: boolean;

package/dist/index.js

@@ -407,6 +407,16 @@ class PlaycademyError extends Error {
   }
 }
 
+class ManifestError extends PlaycademyError {
+  kind;
+  constructor(message, kind) {
+    super(message);
+    this.name = "ManifestError";
+    this.kind = kind;
+    Object.setPrototypeOf(this, ManifestError.prototype);
+  }
+}
+
 class ApiError extends Error {
   code;
   details;
@@ -1916,6 +1926,54 @@ class ConnectionManager {
   }
 }
 // src/core/request.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) {
+  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;
+      }
+    } catch (error) {
+      if (canRetry && error instanceof TypeError) {
+        await retryRuntime.wait(retryDelayMs);
+      } else {
+        throw error;
+      }
+    }
+  }
+  throw new PlaycademyError("Request failed after exhausting retries");
+}
+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 +2001,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,7 +2012,7 @@ 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 = await fetchWithRetry(url, {
     method,
     headers,
     body: payload,
@@ -2010,21 +2049,26 @@ async function request({
 }
 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 {
-    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}:`, {
+    log.error(`[Playcademy SDK] Error parsing manifest from ${manifestUrl}:`, {
       error
     });
-    throw new PlaycademyError("Failed to load or parse game manifest");
+    throw new ManifestError("Failed to parse game manifest", "permanent");
   }
 }
 
@@ -2040,6 +2084,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 +2093,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 +2121,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 +2166,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

@@ -941,6 +941,11 @@ interface SpriteConfigWithDimensions {
 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.
@@ -5629,6 +5634,7 @@ declare abstract class PlaycademyBaseClient {
     };
     protected initPayload?: InitPayload;
     protected connectionManager?: ConnectionManager;
+    protected launchId?: string;
     /**
      * Internal session manager for automatic session lifecycle.
      * @private
@@ -5657,6 +5663,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 +5961,7 @@ interface ClientConfig {
     token?: string;
     tokenType?: TokenType;
     gameId?: string;
+    launchId?: string;
     autoStartSession?: boolean;
     onDisconnect?: DisconnectHandler;
     enableConnectionMonitoring?: boolean;
@@ -7629,5 +7637,5 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
     };
 }
 
-export { AchievementCompletionType, ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, NotificationStatus, NotificationType, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging };
+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 };

package/dist/internal.js

@@ -407,6 +407,16 @@ class PlaycademyError extends Error {
   }
 }
 
+class ManifestError extends PlaycademyError {
+  kind;
+  constructor(message, kind) {
+    super(message);
+    this.name = "ManifestError";
+    this.kind = kind;
+    Object.setPrototypeOf(this, ManifestError.prototype);
+  }
+}
+
 class ApiError extends Error {
   code;
   details;
@@ -2027,6 +2037,54 @@ function createDevNamespace(client) {
   };
 }
 // src/core/request.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) {
+  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;
+      }
+    } catch (error) {
+      if (canRetry && error instanceof TypeError) {
+        await retryRuntime.wait(retryDelayMs);
+      } else {
+        throw error;
+      }
+    }
+  }
+  throw new PlaycademyError("Request failed after exhausting retries");
+}
+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 +2112,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,7 +2123,7 @@ 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 = await fetchWithRetry(url, {
     method,
     headers,
     body: payload,
@@ -2121,21 +2160,26 @@ async function request({
 }
 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 {
-    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}:`, {
+    log.error(`[Playcademy SDK] Error parsing manifest from ${manifestUrl}:`, {
       error
     });
-    throw new PlaycademyError("Failed to load or parse game manifest");
+    throw new ManifestError("Failed to parse game manifest", "permanent");
   }
 }
 
@@ -2956,6 +3000,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 +3009,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 +3037,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 +3082,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({
@@ -3160,6 +3210,7 @@ export {
   PlaycademyError,
   PlaycademyInternalClient as PlaycademyClient,
   MessageEvents,
+  ManifestError,
   ConnectionMonitor,
   ConnectionManager,
   ApiError

package/dist/server.js

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

package/dist/types.d.ts

@@ -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.3",
     "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",