@genex-ai/embed-sdk 0.27.0 → 0.28.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
@@ -53,13 +53,45 @@ confirmation surfaces.
53
53
  `GenerateOptions` requires `maxCredits` (SDK **0.27.0+**; an integer from 1 to
54
54
  1,000,000 — the call's ceiling in the player's credits; `estimateCoins`, its old
55
55
  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
56
+ optional bounded `schema`, `maxOutputTokens` (SDK **0.28.0+**, see *How long a
57
+ call may be*), `allowExternal` (default false), `idempotencyKey`,
58
+ `timeoutMs` (default twenty minutes since 0.28.0; ten before) and `grantId` — a standing budget the player
58
59
  already approved, which removes the popup entirely (see *Standing budgets*). Reuse an idempotency key only for the same
59
60
  operation; store it if you need retries to survive a reload. Only models returned
60
61
  by Genex are accepted. This first adapter generates text and JSON, including
61
62
  creature descriptions, dialogue, rules and other structured game data.
62
63
 
64
+ ### How long a call may be
65
+
66
+ SDK **0.28.0+**. A call's size is the stand's, served by
67
+ `getGenerationModels()` as `limits`: `maxPromptBytes` and `maxSchemaBytes`
68
+ (UTF-8 bytes), `defaultOutputTokens` (the answer's budget when you name none),
69
+ `maxOutputTokens` (the most you may ask for) and `maxOutputBytes` (the answer,
70
+ JSON-encoded). Read them; do not copy numbers into the game. A game that writes
71
+ long answers — generated code, a whole scene — asks for room:
72
+
73
+ ```ts
74
+ const { limits } = await getGenerationModels();
75
+ const reply = await generate({
76
+ ...request, // modelId, prompt, outputFormat
77
+ maxOutputTokens: Math.min(24_000, limits?.maxOutputTokens ?? 24_000),
78
+ maxCredits: benchmarkedCeiling, // must FUND that length
79
+ grantId,
80
+ });
81
+ ```
82
+
83
+ `maxOutputTokens` is a ceiling, not a purchase: the call is quoted on it, and
84
+ the answer gets only as many tokens as `maxCredits` funds (the ceiling also
85
+ buys the length). Under a budget the call's ceiling still may not pass the
86
+ `perCallMaxCredits` the player approved. Benchmark with the same
87
+ `maxOutputTokens` (`developmentGenerate({ request: { maxOutputTokens } })`).
88
+ Over a limit the call fails before anything is quoted or charged:
89
+ `prompt_too_large`, `schema_too_large` or `output_tokens_too_large`; a malformed
90
+ `maxOutputTokens` is `invalid_max_output_tokens` before the network. The server
91
+ gives a call time in proportion to the output it may write (minutes for the
92
+ longest answers), so the default wait is twenty minutes; answers that take
93
+ minutes are best streamed (`generateStream()`).
94
+
63
95
  SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
64
96
  `output` plus `source` on success. Cancellation is a normal `canceled` result,
65
97
  but it does not imply that consumed work was free. `pending` with
@@ -524,6 +556,7 @@ const receipt = await developmentGenerate({
524
556
  modelId: 'your-configured-model-id',
525
557
  prompt: 'Invent a friendly creature name.',
526
558
  outputFormat: 'text',
559
+ // maxOutputTokens: 24_000, // 0.28.0+: bench exactly what the game will ask for
527
560
  idempotencyKey: 'calibration-sample-001',
528
561
  },
529
562
  });
@@ -545,8 +578,10 @@ funded output allowance holds that answer plus the stand's headroom. The
545
578
  ceiling also decides how long the answer may be, so declare at least the p95
546
579
  `fitCredits` of your settled samples, not the charged credits alone.
547
580
  `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
581
+ 'provider_token_limit'`, still charged: re-run with a higher `maxCredits`), and
582
+ `usage.fitExceedsCap` an answer longer than the output cap the call asked for
583
+ (its `maxOutputTokens`, else the stand's default): ask for more room, up to
584
+ `limits.maxOutputTokens`, or for a shorter answer. When the provider
550
585
  refused the request before running it (a rejected key, an unknown model, a rate
551
586
  limit — `error: 'provider_http_<status>'`), nothing is charged, the hold is
552
587
  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();
@@ -853,9 +859,14 @@ function generationErrorMessage(code) {
853
859
  case "provider_token_limit":
854
860
  return "The model ran out of room before a usable answer was ready. The attempt is still charged.";
855
861
  case "request_too_large":
862
+ case "prompt_too_large":
863
+ case "schema_too_large":
856
864
  return "That request is too long. Shorten it and try again.";
865
+ case "output_tokens_too_large":
866
+ return "This request asks for a longer answer than Genex allows. Ask for a shorter one.";
857
867
  case "invalid_request":
858
868
  case "invalid_schema":
869
+ case "invalid_max_output_tokens":
859
870
  return "This request wasn\u2019t something Genex could accept.";
860
871
  case "generation_limit":
861
872
  return "As many requests are running as Genex allows at once. Wait for one to finish.";
@@ -903,7 +914,7 @@ var RETRY_FLAG = "genex:embed:retry";
903
914
  var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
904
915
  var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
905
916
  var PLAYER_ID_KEY = "genex:player";
906
- var SDK_VERSION = "0.27.0";
917
+ var SDK_VERSION = "0.28.0";
907
918
  var config2 = null;
908
919
  var state = "pending";
909
920
  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-WSJ5XPEF.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-WSJ5XPEF.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.28.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",