@genex-ai/embed-sdk 0.17.0 → 0.21.1

package/README.md

@@ -0,0 +1,250 @@
+# 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`, Genex can offer the configured personal plan matching
+the selected model alongside coins: Claude for `anthropic/` models, ChatGPT for
+`openai/` models, and neither for other models. This choice appears only in the
+trusted Genex approval modal; never add a "Your Plan" model row in the game.
+Each personal choice costs zero coin and its own plan and usage limits apply.
+New quotes freeze the matching choices; connector metadata stays server-owned.
+Old unapproved quotes are narrowed to the matching provider before confirmation;
+approved personal requests retain their connector for recovery. Once chosen,
+funding never switches providers or falls back to paid generation. Historical
+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);
+// Public offerings contain API/model rows, including sponsored free models.
+// Personal plan funding is offered only by the trusted Genex approval modal.
+// 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
+cost **0 coins**. Personal Claude/ChatGPT funding choices in the Genex approval
+modal also cost **0 coins** and use the player's own account through 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. Both APIs restrict personal funding to the selected model's provider.
+
+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.