@genex-ai/embed-sdk 0.17.0 → 0.21.0

package/README.md

@@ -0,0 +1,243 @@
+# Genex embed SDK
+
+`@genex-ai/embed-sdk` connects a game to player identity, saves, commerce and
+player-funded generation. Initialize it with your game's slug, API URL and
+trusted dashboard origins before using player APIs. See
+[the play-identity contract](../../CLI_INTEGRATION.md#6-durable-game-state--leaderboards--play-identity)
+for identity and storage.
+
+## Generate during play
+
+Runtime generation requires a signed-in player in a production game and an
+enabled Genex runtime service. Each player approves their own payment on Genex.
+The game never handles an OpenRouter key or confirms a charge itself.
+
+```ts
+import { generate, getGenerationModels } from '@genex-ai/embed-sdk';
+
+// After initEmbed() and player sign-in, populate your model picker from Genex.
+const { models } = await getGenerationModels();
+const model = models[0];
+
+generateButton.addEventListener('click', async () => {
+  if (!model) return;
+  const result = await generate({
+    modelId: model.id,
+    estimateCoins: 5, // Fixed price for a started attempt, chosen after benchmarking.
+    prompt: 'Invent a friendly creature. Return its name and color as JSON.',
+    outputFormat: 'json',
+    schema: {
+      type: 'object',
+      properties: { name: { type: 'string' }, color: { type: 'string' } },
+      required: ['name', 'color'],
+      additionalProperties: false,
+    },
+    allowExternal: true,
+  });
+  if (result.status === 'succeeded') {
+    // Validate the shape your game expects before rendering it as data.
+    showCreature(result.output);
+  }
+});
+```
+
+Call `generate()` directly inside the click handler: a standalone game must
+reserve a confirmation popup before asynchronous work. Embedded games ask the
+trusted Genex parent to show its modal. Native WebViews and local-test identity
+return `native_unsupported` and `local_test_unsupported` until they have supported
+confirmation surfaces.
+
+`GenerateOptions` requires `estimateCoins` (an integer from 0 to 1,000,000), `modelId`, `prompt`, `outputFormat: 'text' | 'json'`,
+optional bounded `schema`, `allowExternal` (default false), `idempotencyKey` and
+`timeoutMs` (default ten minutes). Reuse an idempotency key only for the same
+operation; store it if you need retries to survive a reload. Only models returned
+by Genex are accepted. This first adapter generates text and JSON, including
+creature descriptions, dialogue, rules and other structured game data.
+
+SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
+`output` plus `source` on success. Cancellation is a normal `canceled` result,
+but it does not imply that consumed work was free. `pending` with
+`error: 'wait_timeout'` means the SDK stopped waiting; it does not cancel or charge
+again. Persist `generationId` and resume with `waitForGeneration(id)`, or inspect
+the current server state with `getGeneration(id)`. Results also carry the
+server's `billingStatus: 'pending'|'final'`, `chargedCoins`,
+`chargedDisplayUsdCents`, `reservedCoins` and `reservedDisplayUsdCents` when
+available, including on failures. These USD amounts use the frozen coin value;
+never derive them from an estimate or the current catalog. An execution can end
+while billing remains pending. `waitForGeneration()` waits for execution;
+continue reading `getGeneration(id)` for later billing settlement. Missing
+receipt fields mean unavailable information, not zero cost.
+
+The Genex modal shows the fixed attempt price, its USD equivalent, the game and
+the frozen request before approval. New public quotes carry
+`quote.billingPolicy: 'declared-v1'` and `kind: 'fixed'`, with
+`maxCoins = priceCoins = estimateCoins`. Despite its name, `estimateCoins`
+is the developer-declared **fixed price of a started attempt**: declaring 5 coins
+charges 5 even when actual usage would cost 2. Failure, cancellation or reaching
+the budget limit after work starts also charges the full price; a usable result
+is not guaranteed. No model work means zero charge. Zero is accepted only for a
+server-authorized free or personal-only option.
+
+The provider hard budget is derived from that price after the frozen platform
+tariff, then capped by operator limits. Output is clipped to remaining funding;
+an input that cannot fit is refused before a call. Unresolved provider expense
+keeps billing pending and the reservation held until verified. The trusted UI
+must acknowledge the quote's exact `billingPolicy` at confirmation; an old UI
+cannot approve new terms. Previously issued `consumed-v1` quotes keep actual-
+usage billing and quotes without a policy keep their original promise.
+
+With `allowExternal: true`, the same quote can offer configured personal Claude
+and ChatGPT connections alongside coins. Each personal choice costs zero coin;
+its own plan and usage limits apply. Funding choices are frozen by the quote; connector metadata remains server-owned
+and follows the current provider configuration. Once chosen, funding never switches providers
+or falls back to paid generation. Personal-only offerings never gain free coin
+execution. Genex neither collects nor hosts subscription credentials.
+
+`source: 'external'` means user-supplied output, not proof that a particular model
+generated it; `modelProvenance: 'unverified'` makes that explicit. Treat every generated output as data. Never execute returned code
+or use a claimed model/source as authority to mint coins, rewards or items.
+
+## Registered generation workflows
+
+SDK **0.21.0+** supports multi-step generation and usage receipts through an
+operator-registered workflow. This requires the game's trusted server executor;
+an ordinary creator API key cannot register a workflow or dispatch its steps.
+`generate()` and `requestWorkflow()` both require the fixed `estimateCoins`
+price and use the declared-attempt policy above.
+
+```ts
+import { getWorkflowOfferings, requestWorkflow, getEmbedToken } from '@genex-ai/embed-sdk';
+
+// Load from this game's registered workflow before enabling the model picker.
+const catalog = await getWorkflowOfferings(configuredWorkflowId);
+// Keep the complete selected offering: availability, funding, model and prices.
+renderModelPicker(catalog.offerings);
+
+createButton.addEventListener('click', async () => {
+  // Save the selected offering, exact input and benchmarked fixed price together.
+  const { offeringId, input, estimateCoins, idempotencyKey } = pendingCreation;
+  const approval = await requestWorkflow({
+    workflowId: catalog.workflowId, offeringId, input, estimateCoins, allowExternal: true, idempotencyKey,
+  });
+  if (approval.generationId) saveGenerationId(approval.generationId);
+  if (approval.status !== 'authorized' || !approval.generationId) return;
+  // Application-specific endpoint: the game backend verifies and claims the
+  // approved Genex run, binds it to one durable job, and enqueues its executor.
+  await enqueueApprovedWorkflow({
+    generationId: approval.generationId, embedToken: getEmbedToken(), input,
+  });
+});
+```
+
+Call `requestWorkflow()` directly from the click, before an earlier `await`, so
+the SDK can reserve the standalone popup. It returns **approval**, not the
+finished creature: `{ status: 'authorized'|'canceled'|'expired'|'failed'|'pending',
+generationId?, funding?, error? }`, plus available billing receipt fields.
+Waiting for completion before the backend
+claims and enqueues the run would deadlock. Authorized replay also covers an
+already-completed run, allowing the backend to recover the same job or artifact.
+Personal-provider instructions remain open after authorization.
+
+`input` is `{ operation: 'create'|'refactor', description, bundleId, creatureId?,
+revisionDigest? }`; refactors require both creature identity and its revision
+digest. Persist this input, offering and idempotency key before submission; reuse
+them only for the same operation after sign-in or reload. Persist the returned
+generation ID. Read with `getGeneration(id)` and wait with
+`waitForGeneration(id)` after enqueueing. A wait timeout does not cancel work.
+Recovering local state never starts a fresh charge without another player click.
+Read a fresh embed token when sending an approved run to the game backend; never
+persist or log the token.
+
+The catalog's `estimatedCoins` and `priceCoins` are suggested price aliases,
+and its maximum describes operator limits. Choose the game's fixed attempt price
+after development benchmarks, pass it as `estimateCoins`, and show coin plus USD.
+The player's final approval always uses the server quote. Preserve the selected
+model, bundle, funding, availability and operator-owned tariff; the game cannot
+change provider prices, dispatch costs or settlement.
+
+For new public workflow quotes, `maxCoins` is the same fixed amount as
+`priceCoins`, not a promise to bill actual usage. The operator-owned multiplier
+(2 or 3, default 3) determines how much model work that fixed price can fund.
+The whole started attempt is charged once, including failed or canceled work;
+no model work is zero and unknown expense keeps the hold pending. Only the
+selected model is admitted. The trusted executor validates and delivers the
+artifact; the browser cannot settle it.
+
+Use `resumeWorkflow(generationId, { timeoutMs? })` directly from a click to
+reopen a saved approval. It reads the original request without creating a quote
+or requiring a new price, including pre-0.21 consumed and legacy approvals.
+Use `requestWorkflow()` with required `estimateCoins` for new operations.
+
+Legacy quotes without `billingPolicy` retain their original fixed-price and
+refund terms. Never replace a saved quote's policy with the current catalog's
+policy, infer a missing multiplier, or reprice an approved operation.
+
+The designated `google/gemini-3.8-flash` and `z-ai/glm-5.3-flash` offerings,
+and personal Claude/ChatGPT offerings, cost **0 coins**. Personal-provider
+offerings use the player's own account through provider-specific, Genex-owned
+MCP connectors. Claude uses `/player/mcp`; ChatGPT uses `/player/chatgpt/mcp`.
+ChatGPT connector availability depends on account and workspace policy. One
+external request may be active per player across both providers. Follow the
+trusted instructions to fetch and submit each exact stage and attempt; no
+subscription credentials pass through the game and no paid fallback is allowed.
+Submitted results remain user-supplied; the executor must validate them before
+delivery. Generic and workflow `allowExternal` can offer both configured providers.
+
+These workflow endpoints still require signed-in production play, including
+zero-coin offerings. Airena's existing sponsored free guest path is separate;
+do not weaken the workflow's player/session checks to reproduce it.
+
+The [runtime API contract](../../CLI_INTEGRATION.md#10-player-funded-runtime-generation)
+describes both APIs, executor authorization, recovery and connector endpoints.
+
+
+## Benchmark your own coin costs on the server
+
+SDK **0.21.0+** provides `@genex-ai/embed-sdk/development`. Use it only in a
+local Node script or trusted server with your own full creator bearer credential
+and an owned `projectId`. It needs no production play token and cannot choose a
+player wallet. Restricted API keys and personal-only offerings are refused.
+Keep the credential out of game code, browser environment variables and logs;
+the subpath is disabled for browser resolution and rejects browser execution.
+
+`maxCoins` is an explicit positive maximum from your own wallet. Development
+uses `consumed-v1`: actual model usage at the frozen normal tariff, including
+failed usage, up to that maximum. Public-sponsored Gemini/GLM models also use
+this normal paid tariff when benchmarking. Actual zero cost is zero coin;
+unknown expense remains held. No personal or paid fallback occurs.
+
+```ts
+import { developmentGenerate } from '@genex-ai/embed-sdk/development';
+
+const receipt = await developmentGenerate({
+  apiUrl: process.env.GENEX_API_URL!,
+  creatorToken: process.env.GENEX_CREATOR_TOKEN!,
+  projectId: process.env.GENEX_PROJECT_ID!,
+  maxCoins: 5,
+  request: {
+    modelId: 'your-configured-model-id',
+    prompt: 'Invent a friendly creature name.',
+    outputFormat: 'text',
+    idempotencyKey: 'calibration-sample-001',
+  },
+});
+// A 5-coin maximum can return chargedCoins: 2. Use repeated samples to choose
+// the public fixed estimateCoins price; public fixed 5 still charges 5.
+if (receipt.billingStatus === 'final') useForCalibration(receipt.chargedCoins, receipt.usage);
+```
+
+The full receipt includes execution status, output on success, charged/reserved
+coins and USD, plus development-only `usage: { costUsdPicos, costUsd,
+maxProviderUsdPicos, unknownProviderUsdPicos }`. Unknown cost is null rather
+than zero; workflow cost aggregates known actual step costs and reports remaining
+unknown exposure separately. No token counts are inferred.
+
+For a registered workflow, call `developmentRequestWorkflow({ apiUrl,
+creatorToken, projectId, workflowId, maxCoins, request: { offeringId, input,
+idempotencyKey? } })`. It returns the accepted, claimed workflow immediately so
+your trusted executor can enqueue it. After enqueueing, call
+`waitForDevelopmentGeneration(config, id, timeoutMs?)`. Both generic and workflow
+benchmarks are recoverable with `getDevelopmentGeneration(config, id)` and
+`cancelDevelopmentGeneration(config, id)`. The wait ends at execution plus final
+billing, or returns the latest server view at timeout; timeout does not cancel
+or claim a refund. Save the operation ID and idempotency key for recovery.

package/dist/chunk-Q476GJHI.js

@@ -0,0 +1,249 @@
+// ../embed-protocol/src/constants.ts
+var NATIVE_CHANNEL = "genex-native";
+var NATIVE_PROTOCOL_VERSION = 1;
+var NATIVE_MARKER_PARAM = "genex_native";
+var NATIVE_MARKER_VALUE = "1";
+var NATIVE_PROTOCOL_PARAM = "genex_protocol";
+var NATIVE_ATTEMPT_PARAM = "genex_attempt";
+var NATIVE_NONCE_PARAM = "genex_nonce";
+var NATIVE_RECEIVER = "__genexNative";
+var MAX_BRIDGE_MESSAGE_BYTES = 4096;
+var BRIDGE_ID_RE = /^[0-9a-f]{32}$/;
+var SLUG_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+function isBridgeId(value) {
+  return typeof value === "string" && BRIDGE_ID_RE.test(value);
+}
+function isBridgeSlug(value) {
+  return typeof value === "string" && SLUG_RE.test(value);
+}
+
+// ../embed-protocol/src/base64url.ts
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+var LOOKUP = (() => {
+  const table = new Array(128).fill(-1);
+  for (let i = 0; i < ALPHABET.length; i++) table[ALPHABET.charCodeAt(i)] = i;
+  return table;
+})();
+function utf8Bytes(text) {
+  const out = [];
+  for (let i = 0; i < text.length; i++) {
+    let code = text.charCodeAt(i);
+    if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        code = 65536 + (code - 55296 << 10) + (next - 56320);
+        i++;
+      } else {
+        code = 65533;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      code = 65533;
+    }
+    if (code < 128) out.push(code);
+    else if (code < 2048) out.push(192 | code >> 6, 128 | code & 63);
+    else if (code < 65536) {
+      out.push(224 | code >> 12, 128 | code >> 6 & 63, 128 | code & 63);
+    } else {
+      out.push(
+        240 | code >> 18,
+        128 | code >> 12 & 63,
+        128 | code >> 6 & 63,
+        128 | code & 63
+      );
+    }
+  }
+  return out;
+}
+function utf8Text(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; ) {
+    const b0 = bytes[i];
+    let code;
+    let size;
+    if (b0 < 128) {
+      code = b0;
+      size = 1;
+    } else if ((b0 & 224) === 192) {
+      code = b0 & 31;
+      size = 2;
+    } else if ((b0 & 240) === 224) {
+      code = b0 & 15;
+      size = 3;
+    } else if ((b0 & 248) === 240) {
+      code = b0 & 7;
+      size = 4;
+    } else return null;
+    if (i + size > bytes.length) return null;
+    for (let k = 1; k < size; k++) {
+      const b = bytes[i + k];
+      if ((b & 192) !== 128) return null;
+      code = code << 6 | b & 63;
+    }
+    if (size === 2 && code < 128) return null;
+    if (size === 3 && (code < 2048 || code >= 55296 && code <= 57343)) return null;
+    if (size === 4 && (code < 65536 || code > 1114111)) return null;
+    if (code > 65535) {
+      const v = code - 65536;
+      out += String.fromCharCode(55296 + (v >> 10), 56320 + (v & 1023));
+    } else {
+      out += String.fromCharCode(code);
+    }
+    i += size;
+  }
+  return out;
+}
+function utf8ByteLength(text) {
+  return utf8Bytes(text).length;
+}
+function encodeBase64UrlJson(value) {
+  const bytes = utf8Bytes(JSON.stringify(value));
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = bytes[i + 1];
+    const b2 = bytes[i + 2];
+    out += ALPHABET[b0 >> 2];
+    out += ALPHABET[(b0 & 3) << 4 | (b1 ?? 0) >> 4];
+    if (b1 === void 0) break;
+    out += ALPHABET[(b1 & 15) << 2 | (b2 ?? 0) >> 6];
+    if (b2 === void 0) break;
+    out += ALPHABET[b2 & 63];
+  }
+  return out;
+}
+function decodeBase64UrlJson(encoded) {
+  if (encoded.length % 4 === 1) return void 0;
+  const bytes = [];
+  let buffer = 0;
+  let bits = 0;
+  for (let i = 0; i < encoded.length; i++) {
+    const code = encoded.charCodeAt(i);
+    const value = code < 128 ? LOOKUP[code] : -1;
+    if (value < 0) return void 0;
+    buffer = buffer << 6 | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push(buffer >> bits & 255);
+    }
+  }
+  if (bits > 0 && (buffer & (1 << bits) - 1) !== 0) return void 0;
+  const text = utf8Text(bytes);
+  if (text === null) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+
+// ../embed-protocol/src/messages.ts
+var MAX_TICKET_LENGTH = 2048;
+var MAX_EXPIRES_AT_LENGTH = 32;
+var ISO_INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+  const own = Object.keys(value);
+  if (own.length !== keys.length) return false;
+  for (const key of keys) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) return false;
+  }
+  return true;
+}
+var BASE_KEYS = ["channel", "v", "type", "slug", "attemptId", "nonce"];
+function envelopeBaseIsValid(value) {
+  return value.channel === NATIVE_CHANNEL && value.v === NATIVE_PROTOCOL_VERSION && isBridgeSlug(value.slug) && isBridgeId(value.attemptId) && isBridgeId(value.nonce);
+}
+function parseBridgeNativeCommand(value) {
+  if (!isRecord(value) || !envelopeBaseIsValid(value)) return void 0;
+  switch (value.type) {
+    case "ticket":
+      if (!hasExactKeys(value, [...BASE_KEYS, "ticket", "expiresAt"])) return void 0;
+      if (typeof value.ticket !== "string" || value.ticket.length === 0 || value.ticket.length > MAX_TICKET_LENGTH) {
+        return void 0;
+      }
+      if (typeof value.expiresAt !== "string" || value.expiresAt.length > MAX_EXPIRES_AT_LENGTH || !ISO_INSTANT_RE.test(value.expiresAt)) {
+        return void 0;
+      }
+      return value;
+    case "guest":
+    case "cancel":
+      if (!hasExactKeys(value, BASE_KEYS)) return void 0;
+      return value;
+    case "foreground":
+      if (!hasExactKeys(value, [...BASE_KEYS, "active"])) return void 0;
+      if (typeof value.active !== "boolean") return void 0;
+      return value;
+    case "network":
+      if (!hasExactKeys(value, [...BASE_KEYS, "online"])) return void 0;
+      if (typeof value.online !== "boolean") return void 0;
+      return value;
+    default:
+      return void 0;
+  }
+}
+
+// ../embed-protocol/src/transport.ts
+function read(raw, parse) {
+  if (typeof raw !== "string" || raw.length === 0) return { ok: false, reason: "undecodable" };
+  if (utf8ByteLength(raw) > MAX_BRIDGE_MESSAGE_BYTES) return { ok: false, reason: "too-large" };
+  const decoded = decodeBase64UrlJson(raw);
+  if (decoded === void 0) return { ok: false, reason: "undecodable" };
+  const message = parse(decoded);
+  if (message === void 0) return { ok: false, reason: "invalid" };
+  return { ok: true, message };
+}
+function readBridgeNativeCommand(raw) {
+  return read(raw, parseBridgeNativeCommand);
+}
+function encodeBridgeMessage(message) {
+  const encoded = encodeBase64UrlJson(message);
+  if (encoded.length > MAX_BRIDGE_MESSAGE_BYTES) return void 0;
+  return encoded;
+}
+
+// ../embed-protocol/src/entry-url.ts
+function readParam(search, key) {
+  const query = search.charAt(0) === "?" ? search.slice(1) : search;
+  if (query.length === 0) return null;
+  for (const pair of query.split("&")) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) continue;
+    if (pair.slice(0, eq) === key) return pair.slice(eq + 1);
+  }
+  return null;
+}
+function hasNativeMarker(search) {
+  return readParam(search, NATIVE_MARKER_PARAM) === NATIVE_MARKER_VALUE;
+}
+function readNativeEntry(search) {
+  if (!hasNativeMarker(search)) return null;
+  const attemptId = readParam(search, NATIVE_ATTEMPT_PARAM);
+  const nonce = readParam(search, NATIVE_NONCE_PARAM);
+  const protocol = Number(readParam(search, NATIVE_PROTOCOL_PARAM));
+  if (!isBridgeId(attemptId) || !isBridgeId(nonce)) return null;
+  if (protocol !== NATIVE_PROTOCOL_VERSION) return null;
+  return { attemptId, nonce, protocol };
+}
+
+// ../embed-protocol/src/runtime-generation.ts
+function isGenerationId(value) {
+  return typeof value === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+}
+function isGenerationTerminal(status) {
+  return ["succeeded", "failed", "unknown", "canceled", "expired"].includes(status);
+}
+
+export {
+  NATIVE_CHANNEL,
+  NATIVE_PROTOCOL_VERSION,
+  NATIVE_RECEIVER,
+  readBridgeNativeCommand,
+  encodeBridgeMessage,
+  hasNativeMarker,
+  readNativeEntry,
+  isGenerationId,
+  isGenerationTerminal
+};