@genex-ai/embed-sdk 0.27.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,10 +8,17 @@ for identity and storage.
8
8
 
9
9
  ## Generate during play
10
10
 
11
- Runtime generation requires a signed-in player in a production game and an
11
+ Runtime generation requires a signed-in player in a published game and an
12
12
  enabled Genex runtime service. Each player approves their own payment on Genex.
13
13
  The game never handles an OpenRouter key or confirms a charge itself.
14
14
 
15
+ **Test builds.** On the build `genex preview` ships, the game's OWNER can use
16
+ every call below before any player sees it: the same approval sheet (marked
17
+ "test build"), the same terms, billed to the owner's own credits or plan. Anyone
18
+ else signed in on a test build, and every guest on any build, is refused with
19
+ `player_wallet_required`; `waitForPlayer().guest` tells the two apart, and from
20
+ SDK 0.29.0 `generationErrorMessage('player_wallet_required')` names both.
21
+
15
22
  ```ts
16
23
  import { generate, getGenerationModels } from '@genex-ai/embed-sdk';
17
24
 
@@ -53,13 +60,45 @@ confirmation surfaces.
53
60
  `GenerateOptions` requires `maxCredits` (SDK **0.27.0+**; an integer from 1 to
54
61
  1,000,000 — the call's ceiling in the player's credits; `estimateCoins`, its old
55
62
  name, is still accepted as the same number), `modelId`, `prompt`, `outputFormat: 'text' | 'json'`,
56
- optional bounded `schema`, `allowExternal` (default false), `idempotencyKey`,
57
- `timeoutMs` (default ten minutes) and `grantId` — a standing budget the player
63
+ optional bounded `schema`, `maxOutputTokens` (SDK **0.28.0+**, see *How long a
64
+ call may be*), `allowExternal` (default false), `idempotencyKey`,
65
+ `timeoutMs` (default twenty minutes since 0.28.0; ten before) and `grantId` — a standing budget the player
58
66
  already approved, which removes the popup entirely (see *Standing budgets*). Reuse an idempotency key only for the same
59
67
  operation; store it if you need retries to survive a reload. Only models returned
60
68
  by Genex are accepted. This first adapter generates text and JSON, including
61
69
  creature descriptions, dialogue, rules and other structured game data.
62
70
 
71
+ ### How long a call may be
72
+
73
+ SDK **0.28.0+**. A call's size is the stand's, served by
74
+ `getGenerationModels()` as `limits`: `maxPromptBytes` and `maxSchemaBytes`
75
+ (UTF-8 bytes), `defaultOutputTokens` (the answer's budget when you name none),
76
+ `maxOutputTokens` (the most you may ask for) and `maxOutputBytes` (the answer,
77
+ JSON-encoded). Read them; do not copy numbers into the game. A game that writes
78
+ long answers — generated code, a whole scene — asks for room:
79
+
80
+ ```ts
81
+ const { limits } = await getGenerationModels();
82
+ const reply = await generate({
83
+ ...request, // modelId, prompt, outputFormat
84
+ maxOutputTokens: Math.min(24_000, limits?.maxOutputTokens ?? 24_000),
85
+ maxCredits: benchmarkedCeiling, // must FUND that length
86
+ grantId,
87
+ });
88
+ ```
89
+
90
+ `maxOutputTokens` is a ceiling, not a purchase: the call is quoted on it, and
91
+ the answer gets only as many tokens as `maxCredits` funds (the ceiling also
92
+ buys the length). Under a budget the call's ceiling still may not pass the
93
+ `perCallMaxCredits` the player approved. Benchmark with the same
94
+ `maxOutputTokens` (`developmentGenerate({ request: { maxOutputTokens } })`).
95
+ Over a limit the call fails before anything is quoted or charged:
96
+ `prompt_too_large`, `schema_too_large` or `output_tokens_too_large`; a malformed
97
+ `maxOutputTokens` is `invalid_max_output_tokens` before the network. The server
98
+ gives a call time in proportion to the output it may write (minutes for the
99
+ longest answers), so the default wait is twenty minutes; answers that take
100
+ minutes are best streamed (`generateStream()`).
101
+
63
102
  SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
64
103
  `output` plus `source` on success. Cancellation is a normal `canceled` result,
65
104
  but it does not imply that consumed work was free. `pending` with
@@ -164,8 +203,9 @@ The successful result carries `grantId` and the full server `grant` view.
164
203
 
165
204
  `generate({ grantId })` runs one call under that budget. It opens **no window,
166
205
  posts no parent message and needs no user gesture**, so it works from a game
167
- loop or a timer. Every other guard is unchanged: production play, a signed-in
168
- player, a trusted parent origin, and no native or local-test surface. The
206
+ loop or a timer. Every other guard is unchanged: the published game (or its
207
+ owner on a test build), a signed-in player, a trusted parent origin, and no
208
+ native or local-test surface. The
169
209
  funding door was chosen once in the sheet, so `allowExternal` is ignored on a
170
210
  budget call. Every call is **billed as used on the budget**: its real model
171
211
  cost plus the Genex fee accrues there, and the player's credits move one whole
@@ -524,6 +564,7 @@ const receipt = await developmentGenerate({
524
564
  modelId: 'your-configured-model-id',
525
565
  prompt: 'Invent a friendly creature name.',
526
566
  outputFormat: 'text',
567
+ // maxOutputTokens: 24_000, // 0.28.0+: bench exactly what the game will ask for
527
568
  idempotencyKey: 'calibration-sample-001',
528
569
  },
529
570
  });
@@ -545,8 +586,10 @@ funded output allowance holds that answer plus the stand's headroom. The
545
586
  ceiling also decides how long the answer may be, so declare at least the p95
546
587
  `fitCredits` of your settled samples, not the charged credits alone.
547
588
  `usage.truncated` marks an answer the model had to stop writing (`error:
548
- 'provider_token_limit'`, still charged: re-run with a higher `maxCredits`), and `usage.fitExceedsCap` an answer longer than one call on that
549
- stand may produce (ask for a shorter one). When the provider
589
+ 'provider_token_limit'`, still charged: re-run with a higher `maxCredits`), and
590
+ `usage.fitExceedsCap` an answer longer than the output cap the call asked for
591
+ (its `maxOutputTokens`, else the stand's default): ask for more room, up to
592
+ `limits.maxOutputTokens`, or for a shorter answer. When the provider
550
593
  refused the request before running it (a rejected key, an unknown model, a rate
551
594
  limit — `error: 'provider_http_<status>'`), nothing is charged, the hold is
552
595
  released, and SDK 0.24.2+ types `providerMessage`: the provider's own words,
@@ -276,6 +276,10 @@ function ceilingField(options) {
276
276
  if (credits !== void 0 && coins !== void 0 && credits !== coins) return { error: "invalid_max_credits" };
277
277
  return { field: credits !== void 0 ? { maxCredits: credits } : { estimateCoins: coins } };
278
278
  }
279
+ function validMaxOutputTokens(value) {
280
+ return value === void 0 || Number.isSafeInteger(value) && value >= 1;
281
+ }
282
+ var GENERATION_WAIT_MS = 12e5;
279
283
  function getGenerationModels() {
280
284
  return request("/models");
281
285
  }
@@ -347,20 +351,21 @@ async function poll(generationId, timeoutMs, readOutcome, popup) {
347
351
  }
348
352
  return { status: "pending", generationId, error: "wait_timeout" };
349
353
  }
350
- function waitForGeneration(generationId, timeoutMs = 6e5) {
354
+ function waitForGeneration(generationId, timeoutMs = GENERATION_WAIT_MS) {
351
355
  if (!isGenerationId(generationId)) return Promise.resolve({ status: "failed", error: "invalid_generation_id" });
352
356
  return poll(generationId, timeoutMs, outcome);
353
357
  }
354
358
  async function generate(options) {
355
359
  const ceiling = ceilingField(options);
356
360
  if ("error" in ceiling) return { status: "failed", error: ceiling.error };
361
+ if (!validMaxOutputTokens(options.maxOutputTokens)) return { status: "failed", error: "invalid_max_output_tokens" };
357
362
  const { timeoutMs, idempotencyKey, grantId, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
358
363
  const input = { ...rest, ...ceiling.field };
359
- if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ?? 6e5);
364
+ if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ?? GENERATION_WAIT_MS);
360
365
  return startGeneration(
361
366
  "/generations",
362
367
  { ...input, idempotencyKey },
363
- timeoutMs ?? 6e5,
368
+ timeoutMs ?? GENERATION_WAIT_MS,
364
369
  outcome
365
370
  );
366
371
  }
@@ -569,6 +574,7 @@ async function generateUnderGrant(grantId, input, idempotencyKey, timeoutMs) {
569
574
  async function generateStream(options) {
570
575
  const ceiling = ceilingField(options);
571
576
  if ("error" in ceiling) return { status: "failed", error: ceiling.error };
577
+ if (!validMaxOutputTokens(options.maxOutputTokens)) return { status: "failed", error: "invalid_max_output_tokens" };
572
578
  const { timeoutMs, idempotencyKey, grantId, onDelta, onPartialField, signal, allowExternal: _unused, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
573
579
  const body = { ...rest, ...ceiling.field };
574
580
  if (grantId === void 0 || grantId === null) return { status: "failed", error: "stream_requires_grant" };
@@ -656,9 +662,9 @@ async function generateStream(options) {
656
662
  if (done) {
657
663
  const view = done;
658
664
  if (!isGenerationId(view.id) || view.grantId !== grantId || generationId !== void 0 && view.id !== generationId) throw new Error("invalid_generation_response");
659
- return finish(outcome(view) ?? await poll(view.id, timeoutMs ?? 6e5, outcome));
665
+ return finish(outcome(view) ?? await poll(view.id, timeoutMs ?? GENERATION_WAIT_MS, outcome));
660
666
  }
661
- if (generationId) return finish(await poll(generationId, timeoutMs ?? 6e5, outcome));
667
+ if (generationId) return finish(await poll(generationId, timeoutMs ?? GENERATION_WAIT_MS, outcome));
662
668
  return { status: "failed", error: "generation_unavailable" };
663
669
  } catch (error) {
664
670
  if (signal?.aborted) return aborted();
@@ -798,8 +804,11 @@ function generationErrorMessage(code) {
798
804
  case "no_player_session":
799
805
  case "unauthorized":
800
806
  case "guest_no_wallet":
801
- case "player_wallet_required":
802
807
  return "Sign in to Genex to use this.";
808
+ // ONE code for a guest anywhere and for anybody but the owner on a TEST
809
+ // build (`genex preview`), so the sentence has to be true for both.
810
+ case "player_wallet_required":
811
+ return "Sign in to Genex to use this. Only the game\u2019s owner can use this on a test build.";
803
812
  case "session_revoked":
804
813
  return "Your Genex session ended. Sign in again to continue.";
805
814
  case "untrusted_parent":
@@ -812,7 +821,7 @@ function generationErrorMessage(code) {
812
821
  case "local_test_unsupported":
813
822
  return "In-game generation doesn\u2019t run in local test mode.";
814
823
  case "staging_no_generation":
815
- return "Generation only works in the published game, not in a preview build.";
824
+ return "Only the game\u2019s owner can use this on a test build.";
816
825
  // --- quotes and terms ---------------------------------------------------
817
826
  case "quote_expired":
818
827
  case "generation_expired":
@@ -853,9 +862,14 @@ function generationErrorMessage(code) {
853
862
  case "provider_token_limit":
854
863
  return "The model ran out of room before a usable answer was ready. The attempt is still charged.";
855
864
  case "request_too_large":
865
+ case "prompt_too_large":
866
+ case "schema_too_large":
856
867
  return "That request is too long. Shorten it and try again.";
868
+ case "output_tokens_too_large":
869
+ return "This request asks for a longer answer than Genex allows. Ask for a shorter one.";
857
870
  case "invalid_request":
858
871
  case "invalid_schema":
872
+ case "invalid_max_output_tokens":
859
873
  return "This request wasn\u2019t something Genex could accept.";
860
874
  case "generation_limit":
861
875
  return "As many requests are running as Genex allows at once. Wait for one to finish.";
@@ -903,7 +917,7 @@ var RETRY_FLAG = "genex:embed:retry";
903
917
  var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
904
918
  var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
905
919
  var PLAYER_ID_KEY = "genex:player";
906
- var SDK_VERSION = "0.27.0";
920
+ var SDK_VERSION = "0.29.0";
907
921
  var config2 = null;
908
922
  var state = "pending";
909
923
  var user = null;
@@ -26,9 +26,13 @@ interface DevelopmentGenerationOptions extends DevelopmentGenerationConfig, Deve
26
26
  prompt: string;
27
27
  outputFormat: 'text' | 'json';
28
28
  schema?: Record<string, unknown>;
29
+ /** The most output tokens the benchmarked call may write, exactly as the
30
+ * game will ask (`generate({ maxOutputTokens })`); omit for the stand's default. */
31
+ maxOutputTokens?: number;
29
32
  idempotencyKey?: string;
30
33
  };
31
- /** Waiting time only; timeout returns the last server view without canceling. */
34
+ /** Waiting time only; timeout returns the last server view without canceling.
35
+ * Defaults to 20 minutes, longer than the lane's longest dispatch. */
32
36
  timeoutMs?: number;
33
37
  }
34
38
  interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig, DevelopmentCap {
@@ -4,6 +4,7 @@ import {
4
4
  } from "./chunk-MJPLBT3T.js";
5
5
 
6
6
  // src/development.ts
7
+ var DEVELOPMENT_WAIT_MS = 12e5;
7
8
  function assertIdentifier(value) {
8
9
  if (!/^[A-Za-z0-9_.:-]{1,120}$/.test(value) || value === "." || value === "..") throw new Error("invalid_development_identifier");
9
10
  }
@@ -48,14 +49,16 @@ async function developmentGenerate(options) {
48
49
  const cap = maximum(options);
49
50
  if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) throw new Error("invalid_timeout");
50
51
  const input = options.request;
52
+ if (input.maxOutputTokens !== void 0 && (!Number.isSafeInteger(input.maxOutputTokens) || input.maxOutputTokens < 1)) throw new Error("invalid_max_output_tokens");
51
53
  const view = await request(options, "/generations", { ...cap, request: {
52
54
  modelId: input.modelId,
53
55
  prompt: input.prompt,
54
56
  outputFormat: input.outputFormat,
55
57
  ...input.schema === void 0 ? {} : { schema: input.schema },
58
+ ...input.maxOutputTokens === void 0 ? {} : { maxOutputTokens: input.maxOutputTokens },
56
59
  idempotencyKey: input.idempotencyKey ?? crypto.randomUUID()
57
60
  } });
58
- return wait(options, view, options.timeoutMs ?? 6e5);
61
+ return wait(options, view, options.timeoutMs ?? DEVELOPMENT_WAIT_MS);
59
62
  }
60
63
  async function developmentJudge(options) {
61
64
  const cap = maximum(options);
@@ -109,7 +112,7 @@ async function wait(config, initial, timeoutMs) {
109
112
  }
110
113
  return view;
111
114
  }
112
- async function waitForDevelopmentGeneration(config, generationId, timeoutMs = 6e5) {
115
+ async function waitForDevelopmentGeneration(config, generationId, timeoutMs = DEVELOPMENT_WAIT_MS) {
113
116
  return wait(config, await getDevelopmentGeneration(config, generationId), timeoutMs);
114
117
  }
115
118
  export {
package/dist/index.d.ts CHANGED
@@ -137,11 +137,25 @@ interface GenerateOptions {
137
137
  prompt: string;
138
138
  outputFormat: 'text' | 'json';
139
139
  schema?: Record<string, unknown>;
140
+ /**
141
+ * The most output tokens this call may write. Omit it for the stand's modest
142
+ * default; ask for more when the answer is long (generated code, a whole
143
+ * scene). Bounded by the stand's cap — `getGenerationModels().limits` serves
144
+ * both numbers, above the cap is `output_tokens_too_large` — and by what
145
+ * the ceiling (`maxCredits`) funds: the ceiling also buys the answer's
146
+ * length, so a long answer needs a ceiling that pays for it (benchmark it).
147
+ */
148
+ maxOutputTokens?: number;
140
149
  /** Allow player-supplied results through their own configured Claude or ChatGPT account. Defaults off. */
141
150
  allowExternal?: boolean;
142
151
  /** Reuse for retries of the same operation, including after a game reload. */
143
152
  idempotencyKey?: string;
144
- /** Waiting time only. Reaching it does not cancel an accepted generation. */
153
+ /**
154
+ * Waiting time only. Reaching it does not cancel an accepted generation:
155
+ * the result is `pending` with `wait_timeout`, and waitForGeneration(id)
156
+ * resumes. Defaults to 20 minutes — longer than the lane's longest dispatch
157
+ * (a 10-minute provider cap on the longest answers) behind a queue wait.
158
+ */
145
159
  timeoutMs?: number;
146
160
  /**
147
161
  * A standing budget from requestSpendGrant(). With one, the call is admitted
package/dist/index.js CHANGED
@@ -34,7 +34,7 @@ import {
34
34
  waitForAuth,
35
35
  waitForGeneration,
36
36
  waitForPlayer
37
- } from "./chunk-7SWNXF5V.js";
37
+ } from "./chunk-SJLIF32C.js";
38
38
  import "./chunk-MJPLBT3T.js";
39
39
  export {
40
40
  __resetForTests,
package/dist/sentry.js CHANGED
@@ -2,7 +2,7 @@ import {
2
2
  _stashTicketFromUrl,
3
3
  getUser,
4
4
  on
5
- } from "./chunk-7SWNXF5V.js";
5
+ } from "./chunk-SJLIF32C.js";
6
6
  import "./chunk-MJPLBT3T.js";
7
7
 
8
8
  // src/sentry.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@genex-ai/embed-sdk",
3
- "version": "0.27.0",
3
+ "version": "0.29.0",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",