@genex-ai/embed-sdk 0.16.0 → 0.21.0

package/dist/development.d.ts

@@ -0,0 +1,44 @@
+import { RuntimeWorkflowInput, RuntimeGenerationView } from '@genex/embed-protocol';
+
+/** Server-only benchmarks spend the authenticated creator's own coin wallet. */
+
+interface DevelopmentGenerationConfig {
+    apiUrl: string;
+    /** Full creator bearer credential, kept only in your server or local script. */
+    creatorToken: string;
+    projectId: string;
+}
+interface DevelopmentGenerationOptions extends DevelopmentGenerationConfig {
+    /** Explicit maximum reservation in your own coins. Actual usage is charged. */
+    maxCoins: number;
+    request: {
+        modelId: string;
+        prompt: string;
+        outputFormat: 'text' | 'json';
+        schema?: Record<string, unknown>;
+        idempotencyKey?: string;
+    };
+    /** Waiting time only; timeout returns the last server view without canceling. */
+    timeoutMs?: number;
+}
+interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig {
+    workflowId: string;
+    maxCoins: number;
+    request: {
+        offeringId: string;
+        input: RuntimeWorkflowInput;
+        idempotencyKey?: string;
+    };
+}
+/** Create a generic benchmark and wait for execution and its actual-usage receipt. */
+declare function developmentGenerate(options: DevelopmentGenerationOptions): Promise<RuntimeGenerationView>;
+/** Returns the accepted workflow so its trusted executor can enqueue before waiting. */
+declare function developmentRequestWorkflow(options: DevelopmentWorkflowOptions): Promise<RuntimeGenerationView>;
+/** Recover a benchmark with the same creator and project; no play token is used. */
+declare function getDevelopmentGeneration(config: DevelopmentGenerationConfig, generationId: string): Promise<RuntimeGenerationView>;
+/** Acknowledges cancellation; the returned receipt determines the charge or remaining hold. */
+declare function cancelDevelopmentGeneration(config: DevelopmentGenerationConfig, generationId: string): Promise<RuntimeGenerationView>;
+/** Wait for execution and final billing; timeout preserves the latest pending receipt. */
+declare function waitForDevelopmentGeneration(config: DevelopmentGenerationConfig, generationId: string, timeoutMs?: number): Promise<RuntimeGenerationView>;
+
+export { type DevelopmentGenerationConfig, type DevelopmentGenerationOptions, type DevelopmentWorkflowOptions, cancelDevelopmentGeneration, developmentGenerate, developmentRequestWorkflow, getDevelopmentGeneration, waitForDevelopmentGeneration };

package/dist/development.js

@@ -0,0 +1,99 @@
+import {
+  isGenerationId,
+  isGenerationTerminal
+} from "./chunk-Q476GJHI.js";
+
+// src/development.ts
+function assertIdentifier(value) {
+  if (!/^[A-Za-z0-9_.:-]{1,120}$/.test(value) || value === "." || value === "..") throw new Error("invalid_development_identifier");
+}
+function baseUrl(config) {
+  if (typeof window !== "undefined") throw new Error("development_server_only");
+  assertIdentifier(config.projectId);
+  if (!config.creatorToken || /\s/.test(config.creatorToken)) throw new Error("creator_token_required");
+  const url = new URL(config.apiUrl);
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) {
+    throw new Error("invalid_api_url");
+  }
+  return url.origin + "/api/runtime/development/projects/" + encodeURIComponent(config.projectId);
+}
+function validateMaximum(maxCoins) {
+  if (!Number.isSafeInteger(maxCoins) || maxCoins <= 0 || maxCoins > 1e6) throw new Error("invalid_max_coins");
+}
+async function request(config, path, body) {
+  const response = await fetch(baseUrl(config) + path, {
+    method: body === void 0 ? "GET" : "POST",
+    credentials: "omit",
+    cache: "no-store",
+    redirect: "error",
+    headers: { Authorization: "Bearer " + config.creatorToken, ...body === void 0 ? {} : { "Content-Type": "application/json" } },
+    ...body === void 0 ? {} : { body: JSON.stringify(body) }
+  });
+  const result = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(typeof result.error === "string" ? result.error : "development_generation_unavailable");
+  const view = result;
+  if (!isGenerationId(view.id) || view.projectId !== config.projectId || view.development !== true || view.quote?.billingPolicy !== "consumed-v1" || view.funding !== "coins") throw new Error("invalid_development_response");
+  return view;
+}
+async function developmentGenerate(options) {
+  validateMaximum(options.maxCoins);
+  if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) throw new Error("invalid_timeout");
+  const input = options.request;
+  const view = await request(options, "/generations", { maxCoins: options.maxCoins, request: {
+    modelId: input.modelId,
+    prompt: input.prompt,
+    outputFormat: input.outputFormat,
+    ...input.schema === void 0 ? {} : { schema: input.schema },
+    idempotencyKey: input.idempotencyKey ?? crypto.randomUUID()
+  } });
+  return wait(options, view, options.timeoutMs ?? 6e5);
+}
+async function developmentRequestWorkflow(options) {
+  validateMaximum(options.maxCoins);
+  assertIdentifier(options.workflowId);
+  assertIdentifier(options.request.offeringId);
+  const view = await request(options, "/workflows/" + encodeURIComponent(options.workflowId) + "/requests", {
+    maxCoins: options.maxCoins,
+    request: {
+      offeringId: options.request.offeringId,
+      input: options.request.input,
+      idempotencyKey: options.request.idempotencyKey ?? crypto.randomUUID()
+    }
+  });
+  if (view.kind !== "workflow" || view.workflow?.id !== options.workflowId || view.workflow.offeringId !== options.request.offeringId) {
+    throw new Error("invalid_development_response");
+  }
+  return view;
+}
+async function getDevelopmentGeneration(config, generationId) {
+  if (!isGenerationId(generationId)) throw new Error("invalid_generation_id");
+  const view = await request(config, "/generations/" + encodeURIComponent(generationId));
+  if (view.id !== generationId) throw new Error("invalid_development_response");
+  return view;
+}
+async function cancelDevelopmentGeneration(config, generationId) {
+  if (!isGenerationId(generationId)) throw new Error("invalid_generation_id");
+  const view = await request(config, "/generations/" + encodeURIComponent(generationId) + "/cancel", {});
+  if (view.id !== generationId) throw new Error("invalid_development_response");
+  return view;
+}
+async function wait(config, initial, timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error("invalid_timeout");
+  const deadline = Date.now() + timeoutMs;
+  let view = initial;
+  while (!(isGenerationTerminal(view.status) && view.billingStatus === "final") && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, Math.min(750, deadline - Date.now())));
+    view = await getDevelopmentGeneration(config, view.id);
+  }
+  return view;
+}
+async function waitForDevelopmentGeneration(config, generationId, timeoutMs = 6e5) {
+  return wait(config, await getDevelopmentGeneration(config, generationId), timeoutMs);
+}
+export {
+  cancelDevelopmentGeneration,
+  developmentGenerate,
+  developmentRequestWorkflow,
+  getDevelopmentGeneration,
+  waitForDevelopmentGeneration
+};

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+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';
+
 /** A thing the game sells. Resolved server-side; the game never sets a price. */
 interface ShopItem {
     id: string;
@@ -118,6 +121,75 @@ declare function buy(opts: {
     timeoutMs?: number;
 }): Promise<PurchaseResult>;
 
+interface GenerateOptions {
+    /** Fixed coin price of a started attempt. Zero is accepted only for server-authorized free options. */
+    estimateCoins: number;
+    modelId: string;
+    prompt: string;
+    outputFormat: 'text' | 'json';
+    schema?: Record<string, unknown>;
+    /** Allow player-supplied results through their own configured Claude or ChatGPT account. Defaults off. */
+    allowExternal?: boolean;
+    /** Reuse for retries of the same operation, including after a game reload. */
+    idempotencyKey?: string;
+    /** Waiting time only. Reaching it does not cancel an accepted generation. */
+    timeoutMs?: number;
+}
+interface RuntimeGenerationResult extends RuntimeGenerationBilling {
+    status: 'succeeded' | 'failed' | 'unknown' | 'canceled' | 'expired' | 'pending';
+    generationId?: string;
+    output?: unknown;
+    /** External output is user-supplied; never use it as authority for rewards or money. */
+    source?: 'openrouter' | 'external';
+    modelProvenance?: 'unverified';
+    error?: string;
+}
+interface RequestWorkflowOptions {
+    /** Fixed coin price of a started attempt, including failed or canceled work. */
+    estimateCoins: number;
+    /** Offer configured personal Claude/ChatGPT funding on the same quote. Defaults off. */
+    allowExternal?: boolean;
+    workflowId: string;
+    offeringId: string;
+    input: RuntimeWorkflowInput;
+    /** Reuse for the exact same operation after sign-in, cancellation or reload. */
+    idempotencyKey?: string;
+    /** Approval waiting time only. A timeout does not cancel an accepted request. */
+    timeoutMs?: number;
+}
+interface RuntimeWorkflowAuthorization extends RuntimeGenerationBilling {
+    status: 'authorized' | 'canceled' | 'expired' | 'failed' | 'pending';
+    generationId?: string;
+    funding?: RuntimeGenerationFunding;
+    error?: string;
+}
+/** Available models and pricing; the confirmation always uses a fresh server quote. */
+declare function getGenerationModels(): Promise<RuntimeGenerationModels>;
+/** Server-owned estimates, reservation maxima and availability. Confirmation seals the quote. */
+declare function getWorkflowOfferings(workflowId: string): Promise<RuntimeWorkflowOfferings>;
+/** Recover an operation by ID after a reload. Scoped to this player AND this game. */
+declare function getGeneration(generationId: string): Promise<RuntimeGenerationView>;
+/** Resume waiting for execution. A terminal result can still carry pending billing; read getGeneration() for settlement. */
+declare function waitForGeneration(generationId: string, timeoutMs?: number): Promise<RuntimeGenerationResult>;
+/**
+ * Call directly from a click handler. The trusted popup is reserved BEFORE any
+ * 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.
+ */
+declare function generate(options: GenerateOptions): Promise<RuntimeGenerationResult>;
+/**
+ * Call directly from the player's click, before awaiting anything. Returns when
+ * Genex authorizes the entire workflow, so the game can enqueue its executor.
+ * Personal-provider instructions stay open after authorization. Store the ID;
+ * getGeneration()/waitForGeneration() recover the eventual result without a new charge.
+ */
+declare function requestWorkflow(options: RequestWorkflowOptions): Promise<RuntimeWorkflowAuthorization>;
+/** Reopen a saved approval without repricing or submitting a new request. Call directly from a click. */
+declare function resumeWorkflow(generationId: string, options?: {
+    timeoutMs?: number;
+}): Promise<RuntimeWorkflowAuthorization>;
+
 interface EmbedConfig {
     /** This game's own slug (GENEX.slug) — identifies the project to /play/authorize. */
     slug: string;
@@ -258,7 +330,9 @@ declare function getColyseusUrls(): string[];
  * session ends up blocked. THE gate for /state saves and any account-bound
  * feature. In a guest session this stays PENDING (it is not rejected —
  * a live upgrade resolves it), so never gate scene boot or connect() on it:
- * use waitForPlayer() for those.
+ * use waitForPlayer() for those. Call initEmbed() FIRST: parked before it,
+ * this logs one console line and, unattended, ends `blocked` after the
+ * handshake budget instead of hanging.
  */
 declare function waitForAuth(): Promise<{
     user: EmbedUser;
@@ -266,7 +340,10 @@ declare function waitForAuth(): Promise<{
 /**
  * Resolves with the current player — guest OR signed-in — as soon as either
  * identity exists; rejects only if the session ends up blocked. THE gate for
- * multiplayer connect() and player-name UI.
+ * multiplayer connect() and player-name UI. Call initEmbed() FIRST — and draw
+ * a frame before awaiting this: parked before init, it logs one console line
+ * and, unattended, ends `blocked` after the handshake budget instead of
+ * leaving the page black.
  */
 declare function waitForPlayer(): Promise<{
     user: EmbedUser;
@@ -352,4 +429,4 @@ declare function __resetForTests(overrides?: {
     heartbeatIntervalMs?: number;
 }): void;
 
-export { type AuthState, type EmbedConfig, type EmbedEvent, type EmbedUser, type Entitlement, type Leaderboard, type LeaderboardEntry, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type SaveStateResult, type ShopItem, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, buy, consumeEntitlement, getAuthState, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getLeaderboard, getShop, getUser, initEmbed, isEmbedded, loadPlayerState, loadWorldState, on, savePlayerState, saveWorldState, submitScore, waitForAuth, 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 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 };

package/dist/index.js

@@ -3,46 +3,61 @@ import {
   _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
-} from "./chunk-ALBFRX3L.js";
+} from "./chunk-WJ4KFQLC.js";
+import "./chunk-Q476GJHI.js";
 export {
   __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
 };

package/dist/sentry.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genex-ai/embed-sdk",
-  "version": "0.16.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.",
+  "version": "0.21.0",
+  "description": "Player identity + durable game state for genex games — signed-in or guest play, per-player save slots, shared world state, and soft-trust leaderboards.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,6 +15,12 @@
       "@genex-ai/source": "./src/sentry.ts",
       "types": "./dist/sentry.d.ts",
       "import": "./dist/sentry.js"
+    },
+    "./development": {
+      "types": "./dist/development.d.ts",
+      "browser": null,
+      "@genex-ai/source": "./src/development.ts",
+      "import": "./dist/development.js"
     }
   },
   "files": [