@playcademy/sdk 0.11.1-beta.4 → 0.12.0

package/dist/index.d.ts

@@ -226,6 +226,7 @@ declare abstract class PlaycademyBaseClient {
     };
     protected initPayload?: InitPayload;
     protected launchId?: string;
+    protected gameOrigin?: string;
     constructor(config?: Partial<ClientConfig>);
     /**
      * Gets the effective base URL for API requests.
@@ -306,6 +307,7 @@ declare abstract class PlaycademyBaseClient {
      * Ensures a gameId is available, throwing an error if not.
      */
     protected _ensureGameId(): string;
+    private _parseOrigin;
     /**
      * Detects and sets the authentication context (iframe vs standalone).
      */
@@ -970,9 +972,6 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `on('pause')`, `on('resume')` - Handle visibility changes
      */
     runtime: {
-        getGameToken: (gameId: string, options?: {
-            apply?: boolean;
-        }) => Promise<GameTokenResponse>;
         exit: () => void;
         onInit: (handler: (context: GameContextPayload) => void) => void;
         onTokenRefresh: (handler: (data: {
@@ -1441,6 +1440,8 @@ interface InitPayload {
     timeback?: TimebackInitContext;
     /** Runtime mode for the game client */
     mode?: PlaycademyMode;
+    /** Launch session correlation ID (UUID, set by platform on game launch) */
+    launchId?: string;
 }
 interface GameContextPayload {
     token: string;
@@ -1553,11 +1554,6 @@ interface DemoEndPayload extends DemoEndOptions {
 interface LoginResponse {
     token: string;
 }
-interface GameTokenResponse {
-    token: string;
-    exp: number;
-    baseUrl?: string;
-}
 
 /**
  * Scores namespace types

package/dist/index.js

@@ -209,7 +209,8 @@ async function init(options) {
     gameUrl: config.gameUrl,
     token: config.token,
     gameId: config.gameId,
-    mode: config.mode
+    mode: config.mode,
+    launchId: config.launchId
   });
   client["initPayload"] = config;
   messaging.listen("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, ({ token }) => client.setToken(token));
@@ -1001,13 +1002,6 @@ function createRuntimeNamespace(client) {
     });
   }
   return {
-    getGameToken: async (gameId, options) => {
-      const res = await client["request"](`/games/${gameId}/token`, "POST");
-      if (options?.apply) {
-        client.setToken(res.token);
-      }
-      return res;
-    },
     exit: () => {
       messaging.send("PLAYCADEMY_EXIT" /* EXIT */, undefined);
     },
@@ -2323,6 +2317,9 @@ async function request({
   const rawText = await res.text().catch(() => "");
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
+// src/version.ts
+var SDK_VERSION = "0.12.0";
+
 // src/clients/base.ts
 class PlaycademyBaseClient {
   baseUrl;
@@ -2335,6 +2332,7 @@ class PlaycademyBaseClient {
   authContext;
   initPayload;
   launchId;
+  gameOrigin;
   constructor(config) {
     this.baseUrl = config?.baseUrl?.endsWith("/api") ? config.baseUrl : `${config?.baseUrl}/api`;
     this.gameUrl = config?.gameUrl;
@@ -2342,6 +2340,7 @@ class PlaycademyBaseClient {
     this.gameId = config?.gameId;
     this.launchId = config?.launchId ?? undefined;
     this.config = config || {};
+    this.gameOrigin = this._parseOrigin(config?.gameUrl);
     this.authStrategy = createAuthStrategy(config?.token ?? null, config?.tokenType);
     this._detectAuthContext();
   }
@@ -2408,7 +2407,9 @@ class PlaycademyBaseClient {
     const effectiveHeaders = {
       ...options?.headers,
       ...this.authStrategy.getHeaders(),
-      ...this.launchId ? { "x-playcademy-launch-id": this.launchId } : {}
+      ...this.launchId ? { "x-playcademy-launch-id": this.launchId } : {},
+      ...this.gameOrigin ? { "x-playcademy-game-origin": this.gameOrigin } : {},
+      "x-playcademy-sdk-version": SDK_VERSION
     };
     return request({
       path,
@@ -2423,7 +2424,8 @@ class PlaycademyBaseClient {
   async requestGameBackend(path, method, body, headers, options) {
     const effectiveHeaders = {
       ...headers,
-      ...this.authStrategy.getHeaders()
+      ...this.authStrategy.getHeaders(),
+      ...this.launchId ? { "x-playcademy-launch-id": this.launchId } : {}
     };
     return request({
       path,
@@ -2441,6 +2443,16 @@ class PlaycademyBaseClient {
     }
     return this.gameId;
   }
+  _parseOrigin(url) {
+    if (!url) {
+      return;
+    }
+    try {
+      return new URL(url).origin;
+    } catch {
+      return;
+    }
+  }
   _detectAuthContext() {
     this.authContext = { isInIframe: isInIframe() };
   }

package/dist/internal.d.ts

@@ -768,6 +768,7 @@ declare abstract class PlaycademyBaseClient {
     };
     protected initPayload?: InitPayload;
     protected launchId?: string;
+    protected gameOrigin?: string;
     constructor(config?: Partial<ClientConfig>);
     /**
      * Gets the effective base URL for API requests.
@@ -848,6 +849,7 @@ declare abstract class PlaycademyBaseClient {
      * Ensures a gameId is available, throwing an error if not.
      */
     protected _ensureGameId(): string;
+    private _parseOrigin;
     /**
      * Detects and sets the authentication context (iframe vs standalone).
      */
@@ -1289,6 +1291,8 @@ interface InitPayload {
     timeback?: TimebackInitContext;
     /** Runtime mode for the game client */
     mode?: PlaycademyMode;
+    /** Launch session correlation ID (UUID, set by platform on game launch) */
+    launchId?: string;
 }
 /**
  * Simplified user data passed to games via InitPayload
@@ -2745,7 +2749,6 @@ interface PlaycademyServerClientState {
      */
     courseId?: string;
 }
-
 /**
  * Resource bindings for backend deployment
  * Provider-agnostic abstraction for cloud resources
@@ -2818,9 +2821,6 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
      */
     runtime: {
-        getGameToken: (gameId: string, options?: {
-            apply?: boolean;
-        }) => Promise<GameTokenResponse>;
         exit: () => void;
         onInit: (handler: (context: GameContextPayload) => void) => void;
         onTokenRefresh: (handler: (data: {
@@ -2996,6 +2996,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
         token: {
             create: (gameId: string, options?: {
                 apply?: boolean;
+                reason?: 'initial' | 'refresh_scheduled' | 'refresh_stale';
             }) => Promise<GameTokenResponse>;
         };
         leaderboard: {

package/dist/internal.js

@@ -209,7 +209,8 @@ async function init(options) {
     gameUrl: config.gameUrl,
     token: config.token,
     gameId: config.gameId,
-    mode: config.mode
+    mode: config.mode,
+    launchId: config.launchId
   });
   client["initPayload"] = config;
   messaging.listen("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, ({ token }) => client.setToken(token));
@@ -1001,13 +1002,6 @@ function createRuntimeNamespace(client) {
     });
   }
   return {
-    getGameToken: async (gameId, options) => {
-      const res = await client["request"](`/games/${gameId}/token`, "POST");
-      if (options?.apply) {
-        client.setToken(res.token);
-      }
-      return res;
-    },
     exit: () => {
       messaging.send("PLAYCADEMY_EXIT" /* EXIT */, undefined);
     },
@@ -2534,7 +2528,9 @@ function createGamesNamespace(client) {
     getSubjects: () => client["request"]("/games/subjects", "GET"),
     token: {
       create: async (gameId, options) => {
-        const res = await client["request"](`/games/${gameId}/token`, "POST");
+        const res = await client["request"](`/games/${gameId}/token`, "POST", {
+          body: options?.reason ? { reason: options.reason } : undefined
+        });
         if (options?.apply) {
           client.setToken(res.token);
         }
@@ -3011,6 +3007,9 @@ async function request({
   const rawText = await res.text().catch(() => "");
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
+// src/version.ts
+var SDK_VERSION = "0.12.0";
+
 // src/clients/base.ts
 class PlaycademyBaseClient {
   baseUrl;
@@ -3023,6 +3022,7 @@ class PlaycademyBaseClient {
   authContext;
   initPayload;
   launchId;
+  gameOrigin;
   constructor(config) {
     this.baseUrl = config?.baseUrl?.endsWith("/api") ? config.baseUrl : `${config?.baseUrl}/api`;
     this.gameUrl = config?.gameUrl;
@@ -3030,6 +3030,7 @@ class PlaycademyBaseClient {
     this.gameId = config?.gameId;
     this.launchId = config?.launchId ?? undefined;
     this.config = config || {};
+    this.gameOrigin = this._parseOrigin(config?.gameUrl);
     this.authStrategy = createAuthStrategy(config?.token ?? null, config?.tokenType);
     this._detectAuthContext();
   }
@@ -3096,7 +3097,9 @@ class PlaycademyBaseClient {
     const effectiveHeaders = {
       ...options?.headers,
       ...this.authStrategy.getHeaders(),
-      ...this.launchId ? { "x-playcademy-launch-id": this.launchId } : {}
+      ...this.launchId ? { "x-playcademy-launch-id": this.launchId } : {},
+      ...this.gameOrigin ? { "x-playcademy-game-origin": this.gameOrigin } : {},
+      "x-playcademy-sdk-version": SDK_VERSION
     };
     return request({
       path,
@@ -3111,7 +3114,8 @@ class PlaycademyBaseClient {
   async requestGameBackend(path, method, body, headers, options) {
     const effectiveHeaders = {
       ...headers,
-      ...this.authStrategy.getHeaders()
+      ...this.authStrategy.getHeaders(),
+      ...this.launchId ? { "x-playcademy-launch-id": this.launchId } : {}
     };
     return request({
       path,
@@ -3129,6 +3133,16 @@ class PlaycademyBaseClient {
     }
     return this.gameId;
   }
+  _parseOrigin(url) {
+    if (!url) {
+      return;
+    }
+    try {
+      return new URL(url).origin;
+    } catch {
+      return;
+    }
+  }
   _detectAuthContext() {
     this.authContext = { isInIframe: isInIframe() };
   }

package/dist/server/edge.d.ts

@@ -195,6 +195,12 @@ interface PlaycademyServerClientState {
      */
     courseId?: string;
 }
+interface RequestContext {
+    /** Per-request launch ID for cross-surface trace correlation */
+    launchId?: string;
+    /** Game origin URL derived from the inbound request */
+    gameOrigin?: string;
+}
 
 /**
  * Resource bindings for backend deployment
@@ -247,7 +253,8 @@ interface BackendDeploymentBundle {
  */
 declare class PlaycademyClient {
     private state;
-    protected constructor(state: PlaycademyServerClientState);
+    private requestCtx;
+    protected constructor(state: PlaycademyServerClientState, requestCtx?: RequestContext);
     /**
      * Initialize a new PlaycademyClient instance.
      *
@@ -264,6 +271,12 @@ declare class PlaycademyClient {
      * @throws {Error} If config is not provided
      */
     static init(config: PlaycademyServerClientConfig): Promise<PlaycademyClient>;
+    /**
+     * Creates a request-scoped client that shares this client's config
+     * but carries per-request context (launchId, gameOrigin) for outbound
+     * API calls. Safe for concurrent use — each wrapper has its own context.
+     */
+    forRequest(ctx: RequestContext): PlaycademyClient;
     private fetchGameId;
     /**
      * Makes an authenticated HTTP request to the API.
@@ -333,6 +346,7 @@ interface VerifyGameTokenResponse {
  * @param gameToken - The game JWT token string to verify
  * @param options - Optional configuration
  * @param options.baseUrl - Optional base URL override (defaults to env vars or production)
+ * @param options.gameOrigin - Optional game origin for observability (e.g., 'https://math-raiders.playcademy.gg')
  * @returns Promise resolving to verified token payload
  * @returns claims - Arbitrary claims from the JWT payload
  * @returns gameId - The game ID this token was issued for
@@ -365,7 +379,9 @@ interface VerifyGameTokenResponse {
  */
 declare function verifyGameToken(gameToken: string, options?: {
     baseUrl?: string;
+    gameOrigin?: string;
+    launchId?: string;
 }): Promise<VerifyGameTokenResponse>;
 
 export { PlaycademyClient, verifyGameToken };
-export type { BackendDeploymentBundle, BackendResourceBindings, IntegrationsConfig, PlaycademyConfig, PlaycademyServerClientConfig, PlaycademyServerClientState, QueueConfig, TimebackBaseConfig, TimebackCourseConfigWithOverrides, TimebackIntegrationConfig };
+export type { BackendDeploymentBundle, BackendResourceBindings, IntegrationsConfig, PlaycademyConfig, PlaycademyServerClientConfig, PlaycademyServerClientState, QueueConfig, RequestContext, TimebackBaseConfig, TimebackCourseConfigWithOverrides, TimebackIntegrationConfig };

package/dist/server/edge.js

@@ -232,12 +232,23 @@ function extractApiErrorInfo(error) {
   };
 }
 
+// src/version.ts
+var SDK_VERSION = "0.12.0";
+
 // src/server/request.ts
-async function makeApiRequest(baseUrl, apiToken, endpoint, method = "GET", body) {
+async function makeApiRequest(opts) {
+  const { baseUrl, apiToken, endpoint, method = "GET", body, gameOrigin, launchId } = opts;
   const url = `${baseUrl}${endpoint}`;
   const headers = new Headers;
   headers.set("Content-Type", "application/json");
   headers.set("x-api-key", apiToken);
+  headers.set("x-playcademy-sdk-version", SDK_VERSION);
+  if (gameOrigin) {
+    headers.set("x-playcademy-game-origin", gameOrigin);
+  }
+  if (launchId) {
+    headers.set("x-playcademy-launch-id", launchId);
+  }
   const options = {
     method,
     headers
@@ -263,8 +274,10 @@ async function makeApiRequest(baseUrl, apiToken, endpoint, method = "GET", body)
 // src/server/client-base.ts
 class PlaycademyClient {
   state;
-  constructor(state) {
+  requestCtx = {};
+  constructor(state, requestCtx) {
     this.state = state;
+    this.requestCtx = requestCtx ?? {};
   }
   static async init(config) {
     const { apiKey, baseUrl, gameId } = config;
@@ -288,11 +301,22 @@ class PlaycademyClient {
     }
     return client;
   }
+  forRequest(ctx) {
+    return new PlaycademyClient(this.state, ctx);
+  }
   async fetchGameId() {
     throw new Error("[Playcademy SDK] gameId is required. Please provide it in the config or implement gameId fetching.");
   }
   async request(path, method = "GET", body) {
-    return makeApiRequest(this.state.baseUrl, this.state.apiKey, path, method, body);
+    return makeApiRequest({
+      baseUrl: this.state.baseUrl,
+      apiToken: this.state.apiKey,
+      endpoint: path,
+      method,
+      body,
+      gameOrigin: this.requestCtx.gameOrigin,
+      launchId: this.requestCtx.launchId
+    });
   }
   get gameId() {
     return this.state.gameId;
@@ -313,11 +337,19 @@ async function verifyGameToken(gameToken, options) {
 Please set the PLAYCADEMY_BASE_URL environment variable`);
   }
   try {
+    const headers = {
+      "Content-Type": "application/json",
+      "x-playcademy-sdk-version": SDK_VERSION
+    };
+    if (options?.gameOrigin) {
+      headers["x-playcademy-game-origin"] = options.gameOrigin;
+    }
+    if (options?.launchId) {
+      headers["x-playcademy-launch-id"] = options.launchId;
+    }
     const response = await fetch(`${baseUrl}/api/games/verify`, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json"
-      },
+      headers,
       body: JSON.stringify({ token: gameToken })
     });
     if (!response.ok) {

package/dist/server.d.ts

@@ -195,6 +195,12 @@ interface PlaycademyServerClientState {
      */
     courseId?: string;
 }
+interface RequestContext {
+    /** Per-request launch ID for cross-surface trace correlation */
+    launchId?: string;
+    /** Game origin URL derived from the inbound request */
+    gameOrigin?: string;
+}
 
 /**
  * Resource bindings for backend deployment
@@ -247,7 +253,8 @@ interface BackendDeploymentBundle {
  */
 declare class PlaycademyClient$1 {
     private state;
-    protected constructor(state: PlaycademyServerClientState);
+    private requestCtx;
+    protected constructor(state: PlaycademyServerClientState, requestCtx?: RequestContext);
     /**
      * Initialize a new PlaycademyClient instance.
      *
@@ -264,6 +271,12 @@ declare class PlaycademyClient$1 {
      * @throws {Error} If config is not provided
      */
     static init(config: PlaycademyServerClientConfig): Promise<PlaycademyClient$1>;
+    /**
+     * Creates a request-scoped client that shares this client's config
+     * but carries per-request context (launchId, gameOrigin) for outbound
+     * API calls. Safe for concurrent use — each wrapper has its own context.
+     */
+    forRequest(ctx: RequestContext): PlaycademyClient$1;
     private fetchGameId;
     /**
      * Makes an authenticated HTTP request to the API.
@@ -379,6 +392,7 @@ interface VerifyGameTokenResponse {
  * @param gameToken - The game JWT token string to verify
  * @param options - Optional configuration
  * @param options.baseUrl - Optional base URL override (defaults to env vars or production)
+ * @param options.gameOrigin - Optional game origin for observability (e.g., 'https://math-raiders.playcademy.gg')
  * @returns Promise resolving to verified token payload
  * @returns claims - Arbitrary claims from the JWT payload
  * @returns gameId - The game ID this token was issued for
@@ -411,6 +425,8 @@ interface VerifyGameTokenResponse {
  */
 declare function verifyGameToken(gameToken: string, options?: {
     baseUrl?: string;
+    gameOrigin?: string;
+    launchId?: string;
 }): Promise<VerifyGameTokenResponse>;
 
 export { PlaycademyClient, verifyGameToken };

package/dist/server.js

@@ -421,12 +421,23 @@ function extractApiErrorInfo(error) {
   };
 }
 
+// src/version.ts
+var SDK_VERSION = "0.12.0";
+
 // src/server/request.ts
-async function makeApiRequest(baseUrl, apiToken, endpoint, method = "GET", body) {
+async function makeApiRequest(opts) {
+  const { baseUrl, apiToken, endpoint, method = "GET", body, gameOrigin, launchId } = opts;
   const url = `${baseUrl}${endpoint}`;
   const headers = new Headers;
   headers.set("Content-Type", "application/json");
   headers.set("x-api-key", apiToken);
+  headers.set("x-playcademy-sdk-version", SDK_VERSION);
+  if (gameOrigin) {
+    headers.set("x-playcademy-game-origin", gameOrigin);
+  }
+  if (launchId) {
+    headers.set("x-playcademy-launch-id", launchId);
+  }
   const options = {
     method,
     headers
@@ -452,8 +463,10 @@ async function makeApiRequest(baseUrl, apiToken, endpoint, method = "GET", body)
 // src/server/client-base.ts
 class PlaycademyClient {
   state;
-  constructor(state) {
+  requestCtx = {};
+  constructor(state, requestCtx) {
     this.state = state;
+    this.requestCtx = requestCtx ?? {};
   }
   static async init(config) {
     const { apiKey, baseUrl, gameId } = config;
@@ -477,11 +490,22 @@ class PlaycademyClient {
     }
     return client;
   }
+  forRequest(ctx) {
+    return new PlaycademyClient(this.state, ctx);
+  }
   async fetchGameId() {
     throw new Error("[Playcademy SDK] gameId is required. Please provide it in the config or implement gameId fetching.");
   }
   async request(path, method = "GET", body) {
-    return makeApiRequest(this.state.baseUrl, this.state.apiKey, path, method, body);
+    return makeApiRequest({
+      baseUrl: this.state.baseUrl,
+      apiToken: this.state.apiKey,
+      endpoint: path,
+      method,
+      body,
+      gameOrigin: this.requestCtx.gameOrigin,
+      launchId: this.requestCtx.launchId
+    });
   }
   get gameId() {
     return this.state.gameId;
@@ -514,11 +538,19 @@ async function verifyGameToken(gameToken, options) {
 Please set the PLAYCADEMY_BASE_URL environment variable`);
   }
   try {
+    const headers = {
+      "Content-Type": "application/json",
+      "x-playcademy-sdk-version": SDK_VERSION
+    };
+    if (options?.gameOrigin) {
+      headers["x-playcademy-game-origin"] = options.gameOrigin;
+    }
+    if (options?.launchId) {
+      headers["x-playcademy-launch-id"] = options.launchId;
+    }
     const response = await fetch(`${baseUrl}/api/games/verify`, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json"
-      },
+      headers,
       body: JSON.stringify({ token: gameToken })
     });
     if (!response.ok) {

package/dist/types.d.ts

@@ -1148,6 +1148,7 @@ declare abstract class PlaycademyBaseClient {
     };
     protected initPayload?: InitPayload;
     protected launchId?: string;
+    protected gameOrigin?: string;
     constructor(config?: Partial<ClientConfig>);
     /**
      * Gets the effective base URL for API requests.
@@ -1228,6 +1229,7 @@ declare abstract class PlaycademyBaseClient {
      * Ensures a gameId is available, throwing an error if not.
      */
     protected _ensureGameId(): string;
+    private _parseOrigin;
     /**
      * Detects and sets the authentication context (iframe vs standalone).
      */
@@ -1327,9 +1329,6 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `on('pause')`, `on('resume')` - Handle visibility changes
      */
     runtime: {
-        getGameToken: (gameId: string, options?: {
-            apply?: boolean;
-        }) => Promise<GameTokenResponse>;
         exit: () => void;
         onInit: (handler: (context: GameContextPayload) => void) => void;
         onTokenRefresh: (handler: (data: {
@@ -1798,6 +1797,8 @@ interface InitPayload {
     timeback?: TimebackInitContext;
     /** Runtime mode for the game client */
     mode?: PlaycademyMode;
+    /** Launch session correlation ID (UUID, set by platform on game launch) */
+    launchId?: string;
 }
 /**
  * Simplified user data passed to games via InitPayload

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.11.1-beta.4",
+    "version": "0.12.0",
     "type": "module",
     "exports": {
         ".": {