@genex-ai/embed-sdk 0.22.3 → 0.24.0

package/README.md

@@ -48,8 +48,9 @@ return `native_unsupported` and `local_test_unsupported` until they have support
 confirmation surfaces.
 
 `GenerateOptions` requires `estimateCoins` (an integer from 1 to 1,000,000 for an API-backed selection), `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
+optional bounded `schema`, `allowExternal` (default false), `idempotencyKey`,
+`timeoutMs` (default ten minutes) and `grantId` — a standing budget the player
+already approved, which removes the popup entirely (see *Standing budgets*). 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.
@@ -107,6 +108,128 @@ nor hosts subscription credentials.
 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.
 
+## Standing budgets
+
+SDK **0.24.0+**. A one-time `generate()` asks the player once per call. When a
+feature calls the model continuously — a thinking NPC, a director rewriting
+the next encounter — ask for a **standing budget** instead: the player approves
+once, sets their own limit on a Genex slider, and the game then calls the model
+with no popup at all until the limit, a stop, or the budget's expiry.
+
+```ts
+import { requestSpendGrant, generate, getSpendGrant, stopSpendGrant, generationErrorMessage } from '@genex-ai/embed-sdk';
+
+let grantId: string | undefined;
+
+// Call it from the click, before awaiting: the approval surface is reserved
+// synchronously, exactly like generate().
+talkButton.addEventListener('click', async () => {
+  if (!grantId) {
+    const budget = await requestSpendGrant({
+      models: [model.id],
+      perCallMaxCoins: 8,        // Hard ceiling per call. The server refuses more.
+      perCallEstimateCoins: 5,   // The honest per-call price, benchmarked first.
+      disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCoinsPerPeriod: 20 },
+      maxConcurrent: 2,
+      idempotencyKey: 'npc-conversation-budget',
+    });
+    if (budget.status !== 'active') return showNotice(generationErrorMessage(budget.error));
+    grantId = budget.grantId;
+  }
+  const reply = await generate({ ...request, grantId });
+  if (reply.status === 'succeeded') applyGeneration(reply);
+  else showNotice(generationErrorMessage(reply.error));
+});
+```
+
+`requestSpendGrant()` resolves `active` once the budget can serve calls,
+`canceled` when the player closes the sheet or stops it, `expired` when the
+approval window passes, `pending` with `error: 'wait_timeout'` when the SDK
+stopped waiting (the sheet may still be open), and `failed` with a server code.
+The successful result carries `grantId` and the full server `grant` view.
+
+`generate({ grantId })` runs one call under that budget. It opens **no window,
+posts no parent message and needs no user gesture**, so it works from a game
+loop or a timer. Every other guard is unchanged: production play, a signed-in
+player, a trusted parent origin, and no native or local-test surface. The
+funding door was chosen once in the sheet, so `allowExternal` is ignored on a
+budget call. Everything else is the ordinary generation result, including the
+receipt: a started attempt is charged its fixed price whether it succeeds,
+fails, or is stopped.
+
+`getSpendGrant(id)` is the readout to draw in the game: `limitCoins`,
+`spentCoins`, `heldCoins` (admitted, not settled yet), `remainingCoins`,
+`limitCalls`, `callCount`, `status` and the frozen `terms`. Poll it on the
+cadence your HUD needs — never derive the remaining budget from your own count
+of calls, and never show a figure the server did not send. Store `grantId` the
+way you store a `generationId`; `getSpendGrant()` recovers the budget after a
+reload, and a budget whose status is no longer live simply needs a new
+approval. `stopSpendGrant(id)` releases it when your feature ends. Stopping is
+prospective: calls already started finish and are charged. The player has the
+same lever on Genex, on every page, and theirs always outranks the game's.
+
+**The disclosure is a promise, not a guess.** `disclosure` is what the Genex
+sheet shows the player, attributed to your game — Genex prints a server-computed
+worst case beside it, so an optimistic number is visible as one. Declare the
+rate you actually expect, benchmark `perCallEstimateCoins` before you declare it
+(see *Benchmark your own coin costs* below), and keep `perCallMaxCoins` a real
+ceiling. The server refuses a call whose declared price is out of proportion to
+the model's own cost (`grant_price_unreasonable`) — that check is what replaces
+the popup, so a budget is never a blank cheque. The slider's bounds, the coin
+value and the recommended headroom all come from the server; read them from
+`getGenerationModels()` (`standingGrant`, `recommendedDeclaredHeadroomBps`)
+rather than typing any of them into the game.
+
+**Handle the refusals as game states.** A budget ends for ordinary reasons and
+the game should have believable copy for each:
+`grant_limit_reached` (the player's limit is spent), `grant_stopped`,
+`grant_expired`, `grant_not_active`, `grant_concurrency` and
+`grant_rate_limited` (your own declared ceilings), `grant_insufficient_funds`
+(the wallet ran low — the budget resumes when it is topped up),
+`waiting_for_plan` (a personal plan's own rate limit; it resumes by itself),
+`grant_price_unreasonable`, `grant_already_active`, `external_grant_active` and
+`invalid_grant_limit`. `generationErrorMessage(code)` returns a player-facing
+sentence for every one of these and for every one-time code as well; show it, or
+write your own in-fiction line keyed off the same code. Never show the raw code,
+and never treat `unknown` as failure — it means the outcome is not settled yet.
+
+**The receiver pattern.** Persistence is the game's job, and it is what decides
+whether a generated thing survives a reload:
+
+- Write exactly one function, `applyGeneration(result)`, that turns an output
+  into game state and saves it through the SDK's player-state API.
+- In the click path, save the `generationId` (and `grantId`) into player state
+  **before** awaiting, then call `applyGeneration`.
+- On boot, call `waitForGeneration(savedId)` for any stored id and call the
+  *same* `applyGeneration`.
+
+One writer, two entry points: the difference between something that works once
+and something that survives a reload. Validate `result.output` against the shape
+your game expects before using it, always. It is data, never authority for
+coins, rewards or items.
+
+## Your subscription and the Genex player watcher
+
+Both approval sheets can offer the player their own Claude or ChatGPT plan
+beside coins, when the selected model's provider matches. That choice lives in
+the trusted Genex surface only — never add a plan row to the game's own model
+picker, and never ask a player for a subscription credential. Genex neither
+collects nor hosts them.
+
+A personal-plan request is answered on the player's own computer by the **Genex
+player watcher**, a small program that runs the official `claude` / `codex` CLIs
+they signed into themselves. If a player picks their plan and has not installed
+it, Genex shows them the one-time prompt: *"Install the Genex player watcher:
+run `npx @genex-ai/cli-demo@latest player install` and approve it on Genex."*
+The game does not install, start or speak to the watcher; it only reads
+`watcherOnline` on a grant or generation view when Genex includes it. A
+personal-plan result costs zero coin, is metered in requests rather than coin,
+and arrives with `source: 'external'` and `modelProvenance: 'unverified'`:
+user-supplied output, never proof that a particular model produced it, and
+never authority for money or rewards. When the player's own plan hits its rate limit
+the budget reports `waiting_for_plan` and resumes on its own; it never falls back
+to paid work.
+
 ## Registered generation workflows
 
 SDK **0.21.0+** supports multi-step generation and usage receipts through an
@@ -207,6 +330,11 @@ describes both APIs, executor authorization, recovery and connector endpoints.
 
 ## Benchmark your own coin costs on the server
 
+`npx genex llm bench` is the CLI door onto this lane: it runs the real model
+against your own coin wallet, reports what it actually charged, and recommends
+the price to declare. Reach for the API below when you want the samples in your
+own script.
+
 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

package/dist/{chunk-IFI2NYBC.js → chunk-GR56KHWN.js}

@@ -8,7 +8,7 @@ import {
   isGenerationTerminal,
   readBridgeNativeCommand,
   readNativeEntry
-} from "./chunk-Q476GJHI.js";
+} from "./chunk-VPIQVRVS.js";
 
 // src/commerce.ts
 var cfg = null;
@@ -217,7 +217,8 @@ function waitForGeneration(generationId, timeoutMs = 6e5) {
 }
 async function generate(options) {
   if (!validEstimateCoins(options.estimateCoins)) return { status: "failed", error: "invalid_estimate_coins" };
-  const { timeoutMs, idempotencyKey, ...input } = options;
+  const { timeoutMs, idempotencyKey, grantId, ...input } = options;
+  if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ?? 6e5);
   return startGeneration(
     "/generations",
     { ...input, idempotencyKey },
@@ -241,7 +242,7 @@ async function resumeWorkflow(generationId, options = {}) {
   if (!isGenerationId(generationId)) return { status: "failed", error: "invalid_generation_id" };
   return startGeneration("", {}, options.timeoutMs ?? 6e5, authorizationOutcome, void 0, generationId);
 }
-async function startGeneration(path, body, timeoutMs, readOutcome, workflow, resumeId) {
+function approvalGuards() {
   const c = must2();
   if (c.isLocalTest()) return { status: "failed", error: "local_test_unsupported" };
   if (c.isNative()) return { status: "failed", error: "native_unsupported" };
@@ -251,22 +252,32 @@ async function startGeneration(path, body, timeoutMs, readOutcome, workflow, res
   if (c.isEmbedded() && (!parentOrigin2 || !c.dashboardOrigins.includes(parentOrigin2))) {
     return { status: "failed", error: "untrusted_parent" };
   }
-  let popup = null;
+  return { parentOrigin: parentOrigin2 };
+}
+function reserveApprovalSurface(placeholder) {
+  const guarded = approvalGuards();
+  if ("status" in guarded) return guarded;
+  const c = must2();
+  if (c.isEmbedded()) return { popup: null, parentOrigin: guarded.parentOrigin };
   let dashboard;
-  if (!c.isEmbedded()) {
-    try {
-      dashboard = new URL(c.dashboardOrigins[0]);
-      if (dashboard.protocol !== "https:" && !(dashboard.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(dashboard.hostname))) throw new Error();
-    } catch {
-      return { status: "failed", error: "invalid_dashboard_origin" };
-    }
-    popup = window.open(`${dashboard.origin}/play/generate`, "_blank", "popup,width=480,height=760");
-    if (!popup) return { status: "failed", error: "popup_blocked" };
-    try {
-      popup.opener = null;
-    } catch {
-    }
+  try {
+    dashboard = new URL(c.dashboardOrigins[0]);
+    if (dashboard.protocol !== "https:" && !(dashboard.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(dashboard.hostname))) throw new Error();
+  } catch {
+    return { status: "failed", error: "invalid_dashboard_origin" };
   }
+  const popup = window.open(`${dashboard.origin}${placeholder}`, "_blank", "popup,width=480,height=760");
+  if (!popup) return { status: "failed", error: "popup_blocked" };
+  try {
+    popup.opener = null;
+  } catch {
+  }
+  return { popup, dashboard, parentOrigin: guarded.parentOrigin };
+}
+async function startGeneration(path, body, timeoutMs, readOutcome, workflow, resumeId) {
+  const surface = reserveApprovalSurface("/play/generate");
+  if ("status" in surface) return surface;
+  const { popup, dashboard, parentOrigin: parentOrigin2 } = surface;
   try {
     const view = resumeId ? await getGeneration(resumeId) : await request(path, { ...body, idempotencyKey: body.idempotencyKey ?? crypto.randomUUID() });
     if (resumeId && (view.id !== resumeId || view.kind !== "workflow")) throw new Error("invalid_generation_response");
@@ -291,6 +302,274 @@ async function startGeneration(path, body, timeoutMs, readOutcome, workflow, res
     return { status: "failed", error: error instanceof Error ? error.message : "generation_unavailable" };
   }
 }
+var LIVE_GRANT_STATUSES = ["active", "suspended_insufficient_funds", "waiting_for_plan"];
+function isGrantId(value) {
+  return isGenerationId(value);
+}
+function validCount(value, min, max) {
+  return Number.isSafeInteger(value) && value >= min && value <= max;
+}
+function invalidGrantOptions(options) {
+  if (!Array.isArray(options.models) || options.models.length < 1 || options.models.length > 8 || options.models.some((id) => typeof id !== "string" || !id || id.length > 150) || new Set(options.models).size !== options.models.length) return "invalid_models";
+  if (!validCount(options.perCallMaxCoins, 1, 1e6) || !validCount(options.perCallEstimateCoins, 1, 1e6) || options.perCallEstimateCoins > options.perCallMaxCoins) return "invalid_declared_price";
+  const d = options.disclosure;
+  if (!d || typeof d !== "object" || !["minute", "hour", "session"].includes(d.periodLabel) || !validCount(d.estimatedCallsPerPeriod, 1, 1e4) || !validCount(d.estimatedCoinsPerPeriod, 0, 1e6)) return "invalid_disclosure";
+  if (options.maxConcurrent !== void 0 && !validCount(options.maxConcurrent, 1, 8)) return "invalid_grant_terms";
+  if (options.maxCallsPerMinute !== void 0 && !validCount(options.maxCallsPerMinute, 1, 120)) return "invalid_grant_terms";
+  if (options.maxPendingExternal !== void 0 && !validCount(options.maxPendingExternal, 1, 8)) return "invalid_grant_terms";
+  if (options.allowExternal !== void 0 && typeof options.allowExternal !== "boolean") return "invalid_grant_terms";
+  if (options.idempotencyKey !== void 0 && (typeof options.idempotencyKey !== "string" || options.idempotencyKey.length < 8 || options.idempotencyKey.length > 100)) return "invalid_idempotency_key";
+  return void 0;
+}
+function grantOutcome(view) {
+  if (LIVE_GRANT_STATUSES.includes(view.status)) return { status: "active", grantId: view.id, grant: view };
+  switch (view.status) {
+    // The player closing the sheet, or stopping later, is a normal outcome.
+    case "stopped":
+      return { status: "canceled", grantId: view.id, grant: view };
+    case "expired":
+      return { status: "expired", grantId: view.id, grant: view };
+    // Spent out before it could serve this caller — a real answer, with the
+    // same code a call under an exhausted budget reports.
+    case "exhausted":
+      return { status: "failed", grantId: view.id, grant: view, error: "grant_limit_reached" };
+    default:
+      return void 0;
+  }
+}
+function getSpendGrant(grantId) {
+  if (!isGrantId(grantId)) return Promise.reject(new Error("invalid_grant_id"));
+  return request(`/grants/${encodeURIComponent(grantId)}`);
+}
+function stopSpendGrant(grantId) {
+  if (!isGrantId(grantId)) return Promise.reject(new Error("invalid_grant_id"));
+  return request(`/grants/${encodeURIComponent(grantId)}/stop`, {});
+}
+async function pollGrant(grantId, timeoutMs, popup) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const view = await getSpendGrant(grantId);
+      const result = grantOutcome(view);
+      if (result) return result;
+      if (popup?.closed && view.status === "requires_confirmation") {
+        const stopped = await request(`/grants/${encodeURIComponent(grantId)}/stop`, {});
+        const stopResult = grantOutcome(stopped);
+        if (stopResult) return stopResult;
+      }
+    } catch {
+    }
+    await new Promise((resolve) => setTimeout(resolve, 750));
+  }
+  return { status: "pending", grantId, error: "wait_timeout" };
+}
+async function requestSpendGrant(options) {
+  const invalid = invalidGrantOptions(options);
+  if (invalid) return { status: "failed", error: invalid };
+  const surface = reserveApprovalSurface("/play/grant");
+  if ("status" in surface) return surface;
+  const { popup, dashboard, parentOrigin: parentOrigin2 } = surface;
+  try {
+    const view = await request("/grants", {
+      idempotencyKey: options.idempotencyKey ?? crypto.randomUUID(),
+      models: options.models,
+      perCallMaxCoins: options.perCallMaxCoins,
+      perCallEstimateCoins: options.perCallEstimateCoins,
+      disclosure: {
+        periodLabel: options.disclosure.periodLabel,
+        estimatedCallsPerPeriod: options.disclosure.estimatedCallsPerPeriod,
+        estimatedCoinsPerPeriod: options.disclosure.estimatedCoinsPerPeriod
+      },
+      ...options.maxConcurrent !== void 0 ? { maxConcurrent: options.maxConcurrent } : {},
+      ...options.maxCallsPerMinute !== void 0 ? { maxCallsPerMinute: options.maxCallsPerMinute } : {},
+      ...options.maxPendingExternal !== void 0 ? { maxPendingExternal: options.maxPendingExternal } : {},
+      ...options.allowExternal !== void 0 ? { allowExternal: options.allowExternal } : {}
+    });
+    if (!isGrantId(view.id)) throw new Error("invalid_grant_response");
+    const settled = grantOutcome(view);
+    if (settled) {
+      popup?.close();
+      return settled;
+    }
+    if (popup && dashboard) {
+      if (!popup.closed) popup.location.href = `${dashboard.origin}/play/grant/${encodeURIComponent(view.id)}`;
+    } else if (parentOrigin2) {
+      window.parent.postMessage({ type: "genex:grant:confirm", v: 1, grantId: view.id }, parentOrigin2);
+    }
+    return pollGrant(view.id, options.timeoutMs ?? 6e5, popup);
+  } catch (error) {
+    popup?.close();
+    return { status: "failed", error: error instanceof Error ? error.message : "grant_unavailable" };
+  }
+}
+async function generateUnderGrant(grantId, input, idempotencyKey, timeoutMs) {
+  if (!isGrantId(grantId)) return { status: "failed", error: "invalid_grant_id" };
+  const guarded = approvalGuards();
+  if ("status" in guarded) return guarded;
+  const { allowExternal: _unused, ...body } = input;
+  try {
+    const view = await request(
+      `/grants/${encodeURIComponent(grantId)}/generations`,
+      { ...body, idempotencyKey: idempotencyKey ?? crypto.randomUUID() }
+    );
+    if (!isGenerationId(view.id) || view.grantId !== grantId) throw new Error("invalid_generation_response");
+    const result = outcome(view);
+    if (result) return result;
+    return poll(view.id, timeoutMs, outcome);
+  } catch (error) {
+    return { status: "failed", error: error instanceof Error ? error.message : "generation_unavailable" };
+  }
+}
+function generationErrorMessage(code) {
+  switch (code) {
+    // --- the outcome is not known yet. Never a failure sentence. ------------
+    case "unknown":
+    case "unknown_execution":
+    case "provider_outcome_unknown":
+      return "We don\u2019t know how this one ended yet \u2014 it is still being settled. Check back in a moment.";
+    case "wait_timeout":
+      return "This is taking longer than usual. It is still running \u2014 check back in a moment.";
+    // --- the player's wallet ------------------------------------------------
+    case "insufficient_balance":
+      return "There isn\u2019t enough coin in your Genex wallet for this request.";
+    case "grant_insufficient_funds":
+      return "Your budget paused because your Genex wallet ran low. Top it up and it picks up again.";
+    // --- standing budgets ---------------------------------------------------
+    case "grant_limit_reached":
+      return "This budget has reached the limit you set. Set up a new one to keep going.";
+    case "grant_stopped":
+      return "This budget was stopped. Set up a new one to keep going.";
+    case "grant_expired":
+      return "This budget has ended. Set up a new one to keep going.";
+    case "grant_not_active":
+    case "grant_not_found":
+      return "There is no budget running for this. Set one up to keep going.";
+    case "grant_price_unreasonable":
+      return "This asked to charge more for one request than your approval allows, so nothing was charged.";
+    case "grant_concurrency":
+      return "As many requests are running as your budget allows at once. Wait for one to finish.";
+    case "grant_rate_limited":
+      return "Requests are coming too quickly for this budget. Wait a moment and try again.";
+    case "grant_already_active":
+      return "A budget is already running here. Stop it on Genex before setting up another.";
+    case "external_grant_active":
+      return "A budget on your own plan is already running. Stop it on Genex before setting up another.";
+    case "invalid_grant_limit":
+      return "That limit is outside the range Genex offers. Choose one on the slider.";
+    case "waiting_for_plan":
+      return "Your own plan is at its rate limit right now. This resumes on its own once the limit resets.";
+    // --- personal plans and the player watcher ------------------------------
+    case "external_request_active":
+      return "Finish your current request on your own plan before starting another.";
+    case "external_not_allowed":
+      return "This game only generates through Genex.";
+    case "external_unavailable":
+      return "Your own plan can\u2019t answer this right now.";
+    case "player_update_required":
+      return "The Genex player watcher on your computer is out of date. Update it and try again.";
+    // --- approval, identity and the trusted surface -------------------------
+    case "popup_blocked":
+      return "Your browser blocked the Genex approval window. Allow pop-ups for this page and try again.";
+    case "no_player_session":
+    case "unauthorized":
+    case "guest_no_wallet":
+    case "player_wallet_required":
+      return "Sign in to Genex to use this.";
+    case "session_revoked":
+      return "Your Genex session ended. Sign in again to continue.";
+    case "untrusted_parent":
+    case "invalid_dashboard_origin":
+    case "forbidden_origin":
+    case "credential_scope":
+      return "This page can\u2019t reach Genex safely, so nothing was requested.";
+    case "native_unsupported":
+      return "In-game generation isn\u2019t available in the app yet.";
+    case "local_test_unsupported":
+      return "In-game generation doesn\u2019t run in local test mode.";
+    case "staging_no_generation":
+      return "Generation only works in the published game, not in a preview build.";
+    // --- quotes and terms ---------------------------------------------------
+    case "quote_expired":
+    case "generation_expired":
+    case "expired":
+      return "This request expired before it was approved. Try again.";
+    case "quote_changed":
+    case "quote_mismatch":
+    case "offering_changed":
+      return "The price changed. Start this again to see the new offer.";
+    case "billing_policy_mismatch":
+    case "billing_policy_required":
+    case "billing_policy_unsupported":
+      return "These terms need a fresh review on Genex. Reload the page and try again.";
+    case "funding_mismatch":
+    case "funding_conflict":
+      return "That payment option doesn\u2019t match this request. Start it again.";
+    case "invalid_declared_price":
+    case "invalid_estimate_coins":
+      return "This request\u2019s price isn\u2019t valid, so nothing was charged.";
+    // --- what the game asked for --------------------------------------------
+    case "model_not_allowed":
+      return "This budget doesn\u2019t cover that model. Choose one it does.";
+    case "model_not_available":
+    case "offering_unavailable":
+    case "workflow_unavailable":
+    case "runtime_models_unavailable":
+      return "That model isn\u2019t available here. Choose another.";
+    case "provider_budget_insufficient":
+    case "estimate_exceeds_provider_budget":
+      return "This request is too large for its approved budget. Make it smaller and try again.";
+    case "provider_budget_exceeded":
+    case "provider_budget_exhausted":
+    case "workflow_provider_budget_exhausted":
+    case "budget_exhausted":
+    case "budget_limit":
+    case "runtime_budget_exhausted":
+    case "provider_token_limit":
+      return "The model ran out of room before a usable answer was ready. The attempt is still charged.";
+    case "request_too_large":
+      return "That request is too long. Shorten it and try again.";
+    case "invalid_request":
+    case "invalid_schema":
+      return "This request wasn\u2019t something Genex could accept.";
+    case "generation_limit":
+      return "As many requests are running as Genex allows at once. Wait for one to finish.";
+    case "generation_not_found":
+      return "That request no longer exists.";
+    case "idempotency_conflict":
+      return "That request was already started with different details.";
+    // --- the result -----------------------------------------------------------
+    case "rejected":
+    case "invalid_output":
+    case "validation_failed":
+    case "invalid_provider_response":
+      return "The answer didn\u2019t match what this game asked for.";
+    // TWO DIFFERENT ENDINGS, and the difference is money. A budget that was
+    // stopped, expired or revoked cancels what it admitted but never
+    // dispatched, at zero cost — that is the one case where "before it ran" is
+    // true. A `canceled` row that carries this code instead comes from the
+    // cancel door closing on work already dispatched, or a workflow stopped
+    // after steps ran: a fixed-price attempt is charged in full and a metered
+    // one is charged for what it consumed. Denying the charge in the sentence a
+    // game shows was the SDK telling the player the opposite of their receipt.
+    case "player_stopped":
+    case "game_stopped":
+    case "operator_stopped":
+      return "This request was stopped before it ran, so nothing was charged for it.";
+    case "admission_revoked":
+    case "canceled":
+      return "This request was stopped. Work that had already started is still charged.";
+    case "account_erased":
+      return "This request was stopped because the account was erased.";
+    case "provider_failed":
+    case "provider_unavailable":
+    case "provider_response_unavailable":
+    case "provider_response_too_large":
+    case "context_unavailable":
+      return "The model couldn\u2019t finish this request.";
+    default:
+      return "Generation isn\u2019t available right now. Try again in a moment.";
+  }
+}
 
 // src/index.ts
 var PROTOCOL_VERSION = 1;
@@ -298,7 +577,7 @@ var RETRY_FLAG = "genex:embed:retry";
 var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
 var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
 var PLAYER_ID_KEY = "genex:player";
-var SDK_VERSION = "0.22.3";
+var SDK_VERSION = "0.24.0";
 var config2 = null;
 var state = "pending";
 var user = null;
@@ -548,12 +827,18 @@ function stateFetch(path, init = {}) {
     keepalive: init.body !== void 0 && init.body.length <= KEEPALIVE_MAX_BYTES ? true : void 0
   });
 }
+async function refusedAsStaging(res) {
+  if (res.status !== 403) return false;
+  const body = await res.json().catch(() => null);
+  return body?.error === "staging_no_save";
+}
 async function decodeSave(res) {
   if (res.status === 409) {
     const body2 = await res.json().catch(() => ({}));
     return { saved: false, conflict: true, version: body2.version };
   }
   if (!res.ok) {
+    if (await refusedAsStaging(res)) return { saved: false, staging: true };
     emit("error", { error: new Error(`genex state save failed (${res.status})`) });
     return { saved: false };
   }
@@ -566,7 +851,10 @@ async function loadPlayerState() {
     return { data: hasPendingPlayerSave ? pendingPlayerSave : null, version: 0, guest: true };
   }
   const res = await stateFetch("/state/me");
-  if (!res.ok) throw new Error(`genex load player state failed (${res.status})`);
+  if (!res.ok) {
+    if (await refusedAsStaging(res)) return { data: null, version: 0, staging: true };
+    throw new Error(`genex load player state failed (${res.status})`);
+  }
   const body = await res.json();
   return { data: body.data, version: body.version };
 }
@@ -589,7 +877,10 @@ async function loadWorldState() {
   await ensurePlayer();
   if (state === "guest") return { data: null, version: 0, guest: true };
   const res = await stateFetch("/state");
-  if (!res.ok) throw new Error(`genex load world state failed (${res.status})`);
+  if (!res.ok) {
+    if (await refusedAsStaging(res)) return { data: null, version: 0, staging: true };
+    throw new Error(`genex load world state failed (${res.status})`);
+  }
   const body = await res.json();
   lastWorldVersion = body.version;
   return { data: body.data, version: body.version };
@@ -1537,6 +1828,10 @@ export {
   generate,
   requestWorkflow,
   resumeWorkflow,
+  getSpendGrant,
+  stopSpendGrant,
+  requestSpendGrant,
+  generationErrorMessage,
   initEmbed,
   isEmbedded,
   getAuthState,

package/dist/development.js

@@ -1,7 +1,7 @@
 import {
   isGenerationId,
   isGenerationTerminal
-} from "./chunk-Q476GJHI.js";
+} from "./chunk-VPIQVRVS.js";
 
 // src/development.ts
 function assertIdentifier(value) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { RuntimeWorkflowInput, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationView, RuntimeGenerationModels, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
-export { RuntimeBillingPolicy, RuntimeExternalProvider, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationModels, RuntimeGenerationStatus, RuntimeGenerationView, RuntimeWorkflowInput, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
+import { RuntimeWorkflowInput, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGrantView, RuntimeGenerationView, RuntimeGenerationModels, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
+export { RuntimeBillingPolicy, RuntimeExternalProvider, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationModels, RuntimeGenerationStatus, RuntimeGenerationView, RuntimeGrantStatus, RuntimeGrantTerms, RuntimeGrantView, RuntimeWorkflowInput, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
 
 /** A thing the game sells. Resolved server-side; the game never sets a price. */
 interface ShopItem {
@@ -134,6 +134,13 @@ interface GenerateOptions {
     idempotencyKey?: string;
     /** Waiting time only. Reaching it does not cancel an accepted generation. */
     timeoutMs?: number;
+    /**
+     * A standing budget from requestSpendGrant(). With one, the call is admitted
+     * by the budget the player already approved: no popup, no parent modal and no
+     * user gesture. Every other guard still applies, and `allowExternal` is
+     * ignored because the funding door was chosen once, in the sheet.
+     */
+    grantId?: string;
 }
 interface RuntimeGenerationResult extends RuntimeGenerationBilling {
     status: 'succeeded' | 'failed' | 'unknown' | 'canceled' | 'expired' | 'pending';
@@ -176,6 +183,9 @@ declare function waitForGeneration(generationId: string, timeoutMs?: number): Pr
  * asynchronous work, so standalone games retain the browser's user gesture.
  * The player approves on Genex. Cancellation resolves normally; only API state
  * can return an output. Store generationId to recover a pending result on boot.
+ *
+ * With `grantId`, the player already approved a standing budget: the call needs
+ * no popup and no user gesture, and may run from a loop or a timer.
  */
 declare function generate(options: GenerateOptions): Promise<RuntimeGenerationResult>;
 /**
@@ -189,6 +199,71 @@ declare function requestWorkflow(options: RequestWorkflowOptions): Promise<Runti
 declare function resumeWorkflow(generationId: string, options?: {
     timeoutMs?: number;
 }): Promise<RuntimeWorkflowAuthorization>;
+interface SpendGrantDisclosure {
+    /** The period the estimate below is expressed in. */
+    periodLabel: 'minute' | 'hour' | 'session';
+    /** Honest expected calls per period. The sheet shows the player a worst case beside it. */
+    estimatedCallsPerPeriod: number;
+    /** Honest expected coin per period, attributed to the game, never as a Genex figure. */
+    estimatedCoinsPerPeriod: number;
+}
+interface SpendGrantOptions {
+    /** Models this budget may spend on, from getGenerationModels(). One to eight. */
+    models: string[];
+    /** Hard per-call ceiling. The server refuses a call declaring more. */
+    perCallMaxCoins: number;
+    /** The honest per-call price the disclosure is built on. At most perCallMaxCoins. */
+    perCallEstimateCoins: number;
+    disclosure: SpendGrantDisclosure;
+    /** Calls this budget may have in flight at once. Server default applies when omitted. */
+    maxConcurrent?: number;
+    /** Calls this budget may start per minute. Server default applies when omitted. */
+    maxCallsPerMinute?: number;
+    /** Personal-plan jobs that may be queued at once. Server default applies when omitted. */
+    maxPendingExternal?: number;
+    /** Offer the player's own Claude/ChatGPT plan beside coins. Defaults off. */
+    allowExternal?: boolean;
+    /** Reuse for the same budget request across retries and reloads. */
+    idempotencyKey?: string;
+    /** Approval waiting time only. A timeout neither cancels nor charges. */
+    timeoutMs?: number;
+}
+interface SpendGrantResult {
+    /** `active` means the budget is approved and generate({ grantId }) may run. */
+    status: 'active' | 'canceled' | 'expired' | 'failed' | 'pending';
+    grantId?: string;
+    /** The authoritative server view: limit, spend, counts and the frozen terms. */
+    grant?: RuntimeGrantView;
+    error?: string;
+}
+/** Read a budget: limit, spend, calls and status. Scoped to this player AND this game. */
+declare function getSpendGrant(grantId: string): Promise<RuntimeGrantView>;
+/**
+ * Release a budget when the feature that needed it ends. Stopping is
+ * PROSPECTIVE: calls already started finish and are charged. The player has the
+ * same lever on Genex and it always outranks the game's.
+ */
+declare function stopSpendGrant(grantId: string): Promise<RuntimeGrantView>;
+/**
+ * Ask the player for a standing budget. Call it directly from a click handler,
+ * before awaiting anything: the trusted surface is reserved synchronously, just
+ * like generate(). The player picks the limit and the funding door on Genex —
+ * the game never sees or chooses either.
+ *
+ * Resolves `active` once the budget can serve calls; pass its `grantId` to
+ * generate() from then on. A player who closes the sheet resolves `canceled`.
+ * Store the id: getSpendGrant(id) recovers the budget after a reload.
+ */
+declare function requestSpendGrant(options: SpendGrantOptions): Promise<SpendGrantResult>;
+/**
+ * A player-facing sentence for any code this lane can put in `result.error`.
+ *
+ * Show it, or write your own in-fiction line keyed off the same code — never
+ * the raw code. Two rules the copy keeps: an uncertain outcome reads as
+ * uncertain rather than as failure, and no sentence here states a price, an
+ * allowance or a plan name. Those are the server's to show, in the Genex sheet.
+ */
+declare function generationErrorMessage(code: string | undefined): string;
 
 interface EmbedConfig {
     /** This game's own slug (GENEX.slug) — identifies the project to /play/authorize. */
@@ -222,11 +297,20 @@ interface PlayerStateResult {
     version: number;
     /** True when the current identity is a guest (server storage untouched). */
     guest?: boolean;
+    /**
+     * True when the build is running on the PREVIEW channel — the owner's draft
+     * workspace, any `preview--<slug>` URL. Server saves are off there by design,
+     * so nothing was read: keep progress in localStorage and say "preview build",
+     * never "offline".
+     */
+    staging?: boolean;
 }
 interface WorldStateResult {
     data: unknown;
     version: number;
     guest?: boolean;
+    /** True on the preview channel — see PlayerStateResult.staging. */
+    staging?: boolean;
 }
 interface SaveStateResult {
     /** True when the write landed on the server. */
@@ -239,6 +323,13 @@ interface SaveStateResult {
     guest?: boolean;
     /** True when the value was queued to auto-flush if this guest signs in mid-game. */
     queued?: boolean;
+    /**
+     * True when the build is running on the PREVIEW channel (the owner's draft
+     * workspace, `preview--<slug>`): the server refused the write by policy, not
+     * by failure — nothing is queued, no `error` event fires. Keep the value in
+     * localStorage and tell the player it is a preview build.
+     */
+    staging?: boolean;
 }
 interface SubmitScoreResult {
     submitted: boolean;
@@ -355,14 +446,19 @@ declare function on(event: EmbedEvent, cb: (ctx?: EventContext) => void): () =>
  * Load THIS player's own save slot (per-player, per-game — another player can
  * never read or clobber it). Resolves { data: null, version: 0 } when they
  * never saved. Guests get their queued pending save (if any) so a round-trip
- * works mid-session; the server is untouched. Await-safe from boot: resolves
- * after identity exists, rejects only when the session is blocked.
+ * works mid-session; the server is untouched. On the preview channel (the
+ * owner's draft workspace) resolves { data: null, version: 0, staging: true }
+ * — server saves are off there by design, and that is not an error. Await-safe
+ * from boot: resolves after identity exists, rejects only when the session is
+ * blocked.
  */
 declare function loadPlayerState(): Promise<PlayerStateResult>;
 /**
  * Save THIS player's own slot (any JSON ≤ 256KB; last-write-wins on their own
  * row). Guests: the value is QUEUED in memory and auto-flushed if they sign in
  * mid-game ({ saved: false, guest: true, queued: true }) — no extra game code.
+ * On the preview channel: { saved: false, staging: true }, nothing queued
+ * (nothing would ever flush it) and no `error` event — keep it in localStorage.
  * Pass { ifVersion } (from the last load/save) to detect same-account
  * two-device races: a losing write resolves { conflict: true, version } —
  * reload, merge, retry. Small saves survive tab close (fetch keepalive).
@@ -374,7 +470,8 @@ declare function savePlayerState(data: unknown, opts?: {
  * Load the game's SHARED world slot (one blob per game — every player reads
  * the same world). Guests resolve { data: null, guest: true } — the server
  * refuses guest reads; in multiplayer, guests receive the live world through
- * the room instead.
+ * the room instead. The preview channel resolves { data: null, version: 0,
+ * staging: true } for the same reason the player slot does.
  */
 declare function loadWorldState(): Promise<WorldStateResult>;
 /**
@@ -429,4 +526,4 @@ declare function __resetForTests(overrides?: {
     heartbeatIntervalMs?: number;
 }): void;
 
-export { type AuthState, type EmbedConfig, type EmbedEvent, type EmbedUser, type Entitlement, type GenerateOptions, type Leaderboard, type LeaderboardEntry, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type RequestWorkflowOptions, type RuntimeGenerationResult, type RuntimeWorkflowAuthorization, type SaveStateResult, type ShopItem, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, buy, consumeEntitlement, generate, getAuthState, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getGeneration, getGenerationModels, getLeaderboard, getShop, getUser, getWorkflowOfferings, initEmbed, isEmbedded, loadPlayerState, loadWorldState, on, requestWorkflow, resumeWorkflow, savePlayerState, saveWorldState, submitScore, waitForAuth, waitForGeneration, waitForPlayer };
+export { type AuthState, type EmbedConfig, type EmbedEvent, type EmbedUser, type Entitlement, type GenerateOptions, type Leaderboard, type LeaderboardEntry, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type RequestWorkflowOptions, type RuntimeGenerationResult, type RuntimeWorkflowAuthorization, type SaveStateResult, type ShopItem, type SpendGrantDisclosure, type SpendGrantOptions, type SpendGrantResult, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, buy, consumeEntitlement, generate, generationErrorMessage, getAuthState, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getGeneration, getGenerationModels, getLeaderboard, getShop, getSpendGrant, getUser, getWorkflowOfferings, initEmbed, isEmbedded, loadPlayerState, loadWorldState, on, requestSpendGrant, requestWorkflow, resumeWorkflow, savePlayerState, saveWorldState, stopSpendGrant, submitScore, waitForAuth, waitForGeneration, waitForPlayer };

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   buy,
   consumeEntitlement,
   generate,
+  generationErrorMessage,
   getAuthState,
   getColyseusAuth,
   getColyseusUrls,
@@ -13,6 +14,7 @@ import {
   getGenerationModels,
   getLeaderboard,
   getShop,
+  getSpendGrant,
   getUser,
   getWorkflowOfferings,
   initEmbed,
@@ -20,22 +22,25 @@ import {
   loadPlayerState,
   loadWorldState,
   on,
+  requestSpendGrant,
   requestWorkflow,
   resumeWorkflow,
   savePlayerState,
   saveWorldState,
+  stopSpendGrant,
   submitScore,
   waitForAuth,
   waitForGeneration,
   waitForPlayer
-} from "./chunk-IFI2NYBC.js";
-import "./chunk-Q476GJHI.js";
+} from "./chunk-GR56KHWN.js";
+import "./chunk-VPIQVRVS.js";
 export {
   __resetForTests,
   _stashTicketFromUrl,
   buy,
   consumeEntitlement,
   generate,
+  generationErrorMessage,
   getAuthState,
   getColyseusAuth,
   getColyseusUrls,
@@ -45,6 +50,7 @@ export {
   getGenerationModels,
   getLeaderboard,
   getShop,
+  getSpendGrant,
   getUser,
   getWorkflowOfferings,
   initEmbed,
@@ -52,10 +58,12 @@ export {
   loadPlayerState,
   loadWorldState,
   on,
+  requestSpendGrant,
   requestWorkflow,
   resumeWorkflow,
   savePlayerState,
   saveWorldState,
+  stopSpendGrant,
   submitScore,
   waitForAuth,
   waitForGeneration,

package/dist/sentry.js

@@ -2,8 +2,8 @@ import {
   _stashTicketFromUrl,
   getUser,
   on
-} from "./chunk-IFI2NYBC.js";
-import "./chunk-Q476GJHI.js";
+} from "./chunk-GR56KHWN.js";
+import "./chunk-VPIQVRVS.js";
 
 // src/sentry.ts
 import * as Sentry from "@sentry/browser";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/embed-sdk",
-  "version": "0.22.3",
+  "version": "0.24.0",
   "description": "Player identity + durable game state for genex games \u2014 signed-in or guest play, per-player save slots, shared world state, and soft-trust leaderboards.",
   "type": "module",
   "main": "./dist/index.js",