@oasiz/sdk 1.8.5 → 1.8.6

package/README.md

@@ -171,18 +171,20 @@ still returns `backflip`.
 
 Inside the Oasiz app, `oasiz.getPlayerCharacter()` returns the authenticated
 player's real character atlas. On `localhost` or `file://` without the app
-bridge, it returns a bundled sample Jibble atlas instead, so browser games can
-test sprite loading, atlas slicing, and animation lookup before publishing.
+bridge, it first fetches an Oasiz-owned real sample atlas from
+`https://api.oasiz.ai/api/sdk/sample-character`, so browser games can test
+sprite loading, atlas slicing, and animation lookup before publishing.
 
-The sample atlas includes every catalog ID above, and its `imageUrl` is an
-inline `data:image/svg+xml` URL. It does not make a network request and it is
-only used when the app bridge is missing.
+The platform sample is generated by the same backend/R2 atlas pipeline as real
+characters, but it is not a user character and it does not expose user id,
+layer config, or personal data. If the endpoint is unavailable, the SDK uses a
+tiny generated atlas as a resilience fallback unless disabled.
 
 ```ts
 const character = await oasiz.getPlayerCharacter();
 
 // In Oasiz app: the real signed-in player's character.
-// On localhost without the app bridge: "SDK Sample Jibble".
+// On localhost without the app bridge: "Oasiz Sample Jibble".
 // On non-local pages without the app bridge: null.
 ```
 
@@ -195,8 +197,17 @@ const characterOrNull = await oasiz.getPlayerCharacter({ localFallback: false })
 // Force the sample atlas in a browser test harness.
 const sampleCharacter = await oasiz.getPlayerCharacter({ localFallback: true });
 
-// Or fetch the sample directly without checking the bridge.
-const directSample = oasiz.getSamplePlayerCharacter();
+// Strict mode: require the platform-generated sample, with no generated backup.
+const platformOnlySample = await oasiz.getPlayerCharacter({
+  localFallback: true,
+  generatedFallback: false,
+});
+
+// Override the sample endpoint when testing against staging.
+const stagingSample = await oasiz.getPlayerCharacter({
+  localFallback: true,
+  sampleCharacterUrl: "https://staging-api.oasiz.ai/api/sdk/sample-character",
+});
 ```
 
 #### HTML5 / TypeScript

package/dist/index.cjs

@@ -1685,6 +1685,8 @@ function getSamplePlayerCharacter() {
 }
 
 // src/character.ts
+var DEFAULT_SAMPLE_CHARACTER_URL = "https://api.oasiz.ai/api/sdk/sample-character";
+var DEFAULT_SAMPLE_FETCH_TIMEOUT_MS = 1500;
 function isDevelopment2() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -1718,6 +1720,56 @@ function warnMissingBridge2(methodName, usingFallback) {
     );
   }
 }
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function isTextureAtlas(value) {
+  if (!isRecord2(value)) {
+    return false;
+  }
+  return typeof value.imageUrl === "string" && typeof value.imageWidth === "number" && Number.isFinite(value.imageWidth) && typeof value.imageHeight === "number" && Number.isFinite(value.imageHeight) && Array.isArray(value.frames) && Array.isArray(value.animations);
+}
+function isPlayerCharacter(value) {
+  if (!isRecord2(value)) {
+    return false;
+  }
+  return (typeof value.characterName === "string" || value.characterName === null) && typeof value.baseCharacterId === "string" && typeof value.compositionCode === "string" && isTextureAtlas(value.textureAtlas) && (value.editorTextureAtlas === null || isTextureAtlas(value.editorTextureAtlas));
+}
+function unwrapSampleCharacterResponse(payload) {
+  if (isPlayerCharacter(payload)) {
+    return payload;
+  }
+  if (isRecord2(payload) && isPlayerCharacter(payload.character)) {
+    return payload.character;
+  }
+  return null;
+}
+async function fetchPlatformSampleCharacter(options) {
+  if (typeof fetch !== "function") {
+    return null;
+  }
+  const timeoutMs = options.sampleFetchTimeoutMs ?? DEFAULT_SAMPLE_FETCH_TIMEOUT_MS;
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timeout = controller && timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+  try {
+    const response = await fetch(
+      options.sampleCharacterUrl ?? DEFAULT_SAMPLE_CHARACTER_URL,
+      {
+        signal: controller?.signal
+      }
+    );
+    if (!response.ok) {
+      return null;
+    }
+    return unwrapSampleCharacterResponse(await response.json());
+  } catch {
+    return null;
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
 async function getPlayerCharacter(options = {}) {
   const bridge = getBridgeWindow2();
   if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
@@ -1726,7 +1778,14 @@ async function getPlayerCharacter(options = {}) {
       options.localFallback ?? "auto"
     );
     warnMissingBridge2("getPlayerCharacter", useLocalFallback);
-    return useLocalFallback ? getSamplePlayerCharacter() : null;
+    if (!useLocalFallback) {
+      return null;
+    }
+    const platformSample = await fetchPlatformSampleCharacter(options);
+    if (platformSample) {
+      return platformSample;
+    }
+    return options.generatedFallback === false ? null : getSamplePlayerCharacter();
   }
   try {
     const result = await bridge.__oasizGetPlayerCharacter();
@@ -2990,7 +3049,7 @@ function warnMissingBridge7(methodName) {
     );
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function toFiniteNumber(value) {
@@ -3159,11 +3218,11 @@ function callBridgeFunction(bridge, name) {
   }
 }
 function readInsetObjectValue(value, side, group) {
-  if (!isRecord2(value)) {
+  if (!isRecord3(value)) {
     return void 0;
   }
   if (group) {
-    return isRecord2(value[group]) ? value[group][side] : void 0;
+    return isRecord3(value[group]) ? value[group][side] : void 0;
   }
   return value[side];
 }
@@ -3300,7 +3359,7 @@ function getBridgeWindow10() {
   }
   return window;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null;
 }
 function toFiniteNumber2(value) {
@@ -3366,7 +3425,7 @@ function normalizeMetric(value) {
     }
     return void 0;
   }
-  if (!isRecord3(value)) {
+  if (!isRecord4(value)) {
     return void 0;
   }
   const fpsCandidate = firstDefined2(

package/dist/index.d.cts

@@ -226,6 +226,19 @@ interface GetPlayerCharacterOptions {
      * missing. `"auto"` returns the sample on localhost/file URLs only.
      */
     localFallback?: boolean | "auto";
+    /**
+     * Public endpoint used for the real platform-generated local sample atlas.
+     */
+    sampleCharacterUrl?: string;
+    /**
+     * Timeout for the public sample endpoint before falling back locally.
+     */
+    sampleFetchTimeoutMs?: number;
+    /**
+     * When true, a tiny generated atlas is used if the platform sample endpoint
+     * is unavailable. Set false for strict platform-sample-only local testing.
+     */
+    generatedFallback?: boolean;
 }
 /**
  * Fetch the authenticated player's character, including a TexturePacker /

package/dist/index.d.ts

@@ -226,6 +226,19 @@ interface GetPlayerCharacterOptions {
      * missing. `"auto"` returns the sample on localhost/file URLs only.
      */
     localFallback?: boolean | "auto";
+    /**
+     * Public endpoint used for the real platform-generated local sample atlas.
+     */
+    sampleCharacterUrl?: string;
+    /**
+     * Timeout for the public sample endpoint before falling back locally.
+     */
+    sampleFetchTimeoutMs?: number;
+    /**
+     * When true, a tiny generated atlas is used if the platform sample endpoint
+     * is unavailable. Set false for strict platform-sample-only local testing.
+     */
+    generatedFallback?: boolean;
 }
 /**
  * Fetch the authenticated player's character, including a TexturePacker /

package/dist/index.js

@@ -1624,6 +1624,8 @@ function getSamplePlayerCharacter() {
 }
 
 // src/character.ts
+var DEFAULT_SAMPLE_CHARACTER_URL = "https://api.oasiz.ai/api/sdk/sample-character";
+var DEFAULT_SAMPLE_FETCH_TIMEOUT_MS = 1500;
 function isDevelopment2() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -1657,6 +1659,56 @@ function warnMissingBridge2(methodName, usingFallback) {
     );
   }
 }
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function isTextureAtlas(value) {
+  if (!isRecord2(value)) {
+    return false;
+  }
+  return typeof value.imageUrl === "string" && typeof value.imageWidth === "number" && Number.isFinite(value.imageWidth) && typeof value.imageHeight === "number" && Number.isFinite(value.imageHeight) && Array.isArray(value.frames) && Array.isArray(value.animations);
+}
+function isPlayerCharacter(value) {
+  if (!isRecord2(value)) {
+    return false;
+  }
+  return (typeof value.characterName === "string" || value.characterName === null) && typeof value.baseCharacterId === "string" && typeof value.compositionCode === "string" && isTextureAtlas(value.textureAtlas) && (value.editorTextureAtlas === null || isTextureAtlas(value.editorTextureAtlas));
+}
+function unwrapSampleCharacterResponse(payload) {
+  if (isPlayerCharacter(payload)) {
+    return payload;
+  }
+  if (isRecord2(payload) && isPlayerCharacter(payload.character)) {
+    return payload.character;
+  }
+  return null;
+}
+async function fetchPlatformSampleCharacter(options) {
+  if (typeof fetch !== "function") {
+    return null;
+  }
+  const timeoutMs = options.sampleFetchTimeoutMs ?? DEFAULT_SAMPLE_FETCH_TIMEOUT_MS;
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timeout = controller && timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+  try {
+    const response = await fetch(
+      options.sampleCharacterUrl ?? DEFAULT_SAMPLE_CHARACTER_URL,
+      {
+        signal: controller?.signal
+      }
+    );
+    if (!response.ok) {
+      return null;
+    }
+    return unwrapSampleCharacterResponse(await response.json());
+  } catch {
+    return null;
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
 async function getPlayerCharacter(options = {}) {
   const bridge = getBridgeWindow2();
   if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
@@ -1665,7 +1717,14 @@ async function getPlayerCharacter(options = {}) {
       options.localFallback ?? "auto"
     );
     warnMissingBridge2("getPlayerCharacter", useLocalFallback);
-    return useLocalFallback ? getSamplePlayerCharacter() : null;
+    if (!useLocalFallback) {
+      return null;
+    }
+    const platformSample = await fetchPlatformSampleCharacter(options);
+    if (platformSample) {
+      return platformSample;
+    }
+    return options.generatedFallback === false ? null : getSamplePlayerCharacter();
   }
   try {
     const result = await bridge.__oasizGetPlayerCharacter();
@@ -2929,7 +2988,7 @@ function warnMissingBridge7(methodName) {
     );
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function toFiniteNumber(value) {
@@ -3098,11 +3157,11 @@ function callBridgeFunction(bridge, name) {
   }
 }
 function readInsetObjectValue(value, side, group) {
-  if (!isRecord2(value)) {
+  if (!isRecord3(value)) {
     return void 0;
   }
   if (group) {
-    return isRecord2(value[group]) ? value[group][side] : void 0;
+    return isRecord3(value[group]) ? value[group][side] : void 0;
   }
   return value[side];
 }
@@ -3239,7 +3298,7 @@ function getBridgeWindow10() {
   }
   return window;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null;
 }
 function toFiniteNumber2(value) {
@@ -3305,7 +3364,7 @@ function normalizeMetric(value) {
     }
     return void 0;
   }
-  if (!isRecord3(value)) {
+  if (!isRecord4(value)) {
     return void 0;
   }
   const fpsCandidate = firstDefined2(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "1.8.5",
+  "version": "1.8.6",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",