@genex-ai/embed-sdk 0.26.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
@@ -26,7 +26,7 @@ generateButton.addEventListener('click', async () => {
26
26
  if (!model) return;
27
27
  const result = await generate({
28
28
  modelId: model.id,
29
- estimateCoins: 5, // Fixed price for a started attempt, chosen after benchmarking.
29
+ maxCredits: 5, // This call's ceiling in the player's credits — benchmark it (genex llm bench).
30
30
  prompt: 'Invent a friendly creature. Return its name and color as JSON.',
31
31
  outputFormat: 'json',
32
32
  schema: {
@@ -50,42 +50,85 @@ trusted Genex parent to show its modal. Native WebViews and local-test identity
50
50
  return `native_unsupported` and `local_test_unsupported` until they have supported
51
51
  confirmation surfaces.
52
52
 
53
- `GenerateOptions` requires `estimateCoins` (an integer from 1 to 1,000,000 for an API-backed selection), `modelId`, `prompt`, `outputFormat: 'text' | 'json'`,
54
- optional bounded `schema`, `allowExternal` (default false), `idempotencyKey`,
55
- `timeoutMs` (default ten minutes) and `grantId` — a standing budget the player
53
+ `GenerateOptions` requires `maxCredits` (SDK **0.27.0+**; an integer from 1 to
54
+ 1,000,000 — the call's ceiling in the player's credits; `estimateCoins`, its old
55
+ name, is still accepted as the same number), `modelId`, `prompt`, `outputFormat: 'text' | 'json'`,
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
56
59
  already approved, which removes the popup entirely (see *Standing budgets*). Reuse an idempotency key only for the same
57
60
  operation; store it if you need retries to survive a reload. Only models returned
58
61
  by Genex are accepted. This first adapter generates text and JSON, including
59
62
  creature descriptions, dialogue, rules and other structured game data.
60
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
+
61
95
  SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
62
96
  `output` plus `source` on success. Cancellation is a normal `canceled` result,
63
97
  but it does not imply that consumed work was free. `pending` with
64
98
  `error: 'wait_timeout'` means the SDK stopped waiting; it does not cancel or charge
65
99
  again. Persist `generationId` and resume with `waitForGeneration(id)`, or inspect
66
100
  the current server state with `getGeneration(id)`. Results also carry the
67
- server's `billingStatus: 'pending'|'final'`, `chargedCoins`,
68
- `chargedDisplayUsdCents`, `reservedCoins` and `reservedDisplayUsdCents` when
69
- available, including on failures. These USD amounts use the frozen coin value;
101
+ server's `billingStatus: 'pending'|'final'`, `currency`, `chargedCredits`,
102
+ `reservedCredits`, `maxCredits`, `chargedDisplayUsdCents` and
103
+ `reservedDisplayUsdCents` when available, including on failures (`chargedCoins`
104
+ and `reservedCoins` stay present, and 0, on a credit receipt, for code written
105
+ before credits). These USD amounts use the frozen credit value;
70
106
  never derive them from an estimate or the current catalog. An execution can end
71
107
  while billing remains pending. `waitForGeneration()` waits for execution;
72
108
  continue reading `getGeneration(id)` for later billing settlement. Missing
73
109
  receipt fields mean unavailable information, not zero cost.
74
110
 
75
- The Genex modal shows the fixed attempt price, its USD equivalent, the game and
76
- the frozen request before approval. New public quotes carry
77
- `quote.billingPolicy: 'declared-v1'` and `kind: 'fixed'`, with
78
- `maxCoins = priceCoins = estimateCoins`. Despite its name, `estimateCoins`
79
- is the developer-declared **fixed price of a started attempt**: declaring 5 coins
80
- charges 5 even when actual usage would cost 2. Failure, cancellation or reaching
81
- the budget limit after work starts also charges the full price; a usable result
82
- is not guaranteed. No model work means zero charge; an unsuccessful attempt with
83
- verified zero model cost is also uncharged. Every Genex API model
84
- requires a positive price, including Gemini and GLM. Personal funding chosen in
85
- the trusted approval modal remains zero coin.
86
-
87
- The provider hard budget is derived from that price after the frozen platform
88
- tariff, then capped by operator limits. Output is clipped to remaining funding;
111
+ **In-game calls are paid from the player's Genex credits and billed as used.**
112
+ The Genex modal shows the game, the frozen request and "billed as used, up to N
113
+ credits" with its USD equivalent before approval. New quotes carry
114
+ `quote.billingPolicy: 'metered-credits-v1'`, `kind: 'metered'`, `currency:
115
+ 'credits'` and `quote.maxCredits` — the call's quoted maximum with the Genex
116
+ fee, never above your `maxCredits`. Approval holds that many credits; when the
117
+ call settles it is charged its REAL model cost plus the Genex fee, rounded up
118
+ to a whole credit (so a very small one-time call costs one credit), and the rest
119
+ is released. Model work that fails or is canceled is still charged for what it
120
+ used; a request the provider refused before any work, or verified zero model
121
+ cost, is free. `maxCredits` is a ceiling, not a price: it caps what one call
122
+ may reach and funds how long its answer may be. Every Genex API model needs a
123
+ positive ceiling, including Gemini and GLM. A player who has not verified their
124
+ email is refused (`credits_unverified`), one short of credits sees
125
+ `insufficient_credits`, and Genex may pause paid generation platform-wide
126
+ (`generation_paused`). Personal funding chosen in the trusted approval modal
127
+ costs nothing on Genex. Quotes issued before 0.27's server change — `declared-v1`,
128
+ a fixed coin price per started attempt — keep their terms.
129
+
130
+ The provider hard budget is derived from that ceiling after the frozen platform
131
+ fee, then capped by operator limits. Output is clipped to remaining funding;
89
132
  an input that cannot fit is refused before a call. Unresolved provider expense
90
133
  keeps billing pending and the reservation held until verified. The trusted UI
91
134
  must acknowledge the quote's exact `billingPolicy` at confirmation; an old UI
@@ -96,10 +139,10 @@ unconfirmed zero-price API quote needs a fresh price review before coin approval
96
139
  never silently replace its price or start a paid request during recovery.
97
140
 
98
141
  With `allowExternal: true`, Genex can offer the configured personal plan matching
99
- the selected model alongside coins: Claude for `anthropic/` models, ChatGPT for
142
+ the selected model alongside credits: Claude for `anthropic/` models, ChatGPT for
100
143
  `openai/` models, and neither for other models. This choice appears only in the
101
144
  trusted Genex approval modal; never add a "Your Plan" model row in the game.
102
- Each personal choice costs zero coin and its own plan and usage limits apply.
145
+ Each personal choice costs nothing on Genex and its own plan and usage limits apply.
103
146
  New quotes freeze the matching choices; connector metadata stays server-owned.
104
147
  Old unapproved quotes are narrowed to the matching provider before confirmation;
105
148
  approved personal requests retain their connector for recovery. Once chosen,
@@ -130,9 +173,9 @@ talkButton.addEventListener('click', async () => {
130
173
  if (!grantId) {
131
174
  const budget = await requestSpendGrant({
132
175
  models: [model.id],
133
- perCallMaxCoins: 8, // Hard ceiling per call. The server refuses more.
134
- perCallEstimateCoins: 5, // The honest per-call price, benchmarked first.
135
- disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCoinsPerPeriod: 20 },
176
+ perCallMaxCredits: 8, // Hard ceiling per call. The server refuses a call asking more.
177
+ perCallEstimateCredits: 2, // The honest per-call estimate, benchmarked first.
178
+ disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCreditsPerPeriod: 8 },
136
179
  maxConcurrent: 2,
137
180
  idempotencyKey: 'npc-conversation-budget',
138
181
  });
@@ -156,13 +199,19 @@ posts no parent message and needs no user gesture**, so it works from a game
156
199
  loop or a timer. Every other guard is unchanged: production play, a signed-in
157
200
  player, a trusted parent origin, and no native or local-test surface. The
158
201
  funding door was chosen once in the sheet, so `allowExternal` is ignored on a
159
- budget call. Everything else is the ordinary generation result, including the
160
- receipt: a started attempt is charged its fixed price whether it succeeds,
161
- fails, or is stopped.
162
-
163
- `getSpendGrant(id)` is the readout to draw in the game: `limitCoins`,
164
- `spentCoins`, `heldCoins` (admitted, not settled yet), `remainingCoins`,
165
- `limitCalls`, `callCount`, `status` and the frozen `terms`. Poll it on the
202
+ budget call. Every call is **billed as used on the budget**: its real model
203
+ cost plus the Genex fee accrues there, and the player's credits move one whole
204
+ credit at a time as calls add up — a call's own receipt carries
205
+ `metered.chargedUsdPicos` (what it added) and `chargedCredits: 0`, and when the
206
+ budget ends any remainder is one credit. The per-call ceiling is `maxCredits`,
207
+ at most the budget's `perCallMaxCredits`.
208
+
209
+ `getSpendGrant(id)` is the readout to draw in the game: `limitCredits`,
210
+ `spentCredits`, `heldCredits` (what the budget holds for calls not settled yet,
211
+ and for a remainder under one credit), `remainingCredits`, `limitCalls`,
212
+ `callCount`, `status` and the frozen `terms` (a budget approved before credits
213
+ reports the same in `limitCoins`/`spentCoins`/…, and a credit budget keeps
214
+ those at 0). Poll it on the
166
215
  cadence your HUD needs — never derive the remaining budget from your own count
167
216
  of calls, and never show a figure the server did not send. Store `grantId` the
168
217
  way you store a `generationId`; `getSpendGrant()` recovers the budget after a
@@ -174,21 +223,25 @@ same lever on Genex, on every page, and theirs always outranks the game's.
174
223
  **The disclosure is a promise, not a guess.** `disclosure` is what the Genex
175
224
  sheet shows the player, attributed to your game — Genex prints a server-computed
176
225
  worst case beside it, so an optimistic number is visible as one. Declare the
177
- rate you actually expect, benchmark `perCallEstimateCoins` before you declare it
178
- (see *Benchmark your own coin costs* below), and keep `perCallMaxCoins` a real
179
- ceiling. The server refuses a call whose declared price is out of proportion to
180
- the model's own cost (`grant_price_unreasonable`) — that check is what replaces
181
- the popup, so a budget is never a blank cheque. The slider's bounds, the coin
182
- value and the recommended headroom all come from the server; read them from
183
- `getGenerationModels()` (`standingGrant`, `recommendedDeclaredHeadroomBps`)
184
- rather than typing any of them into the game.
226
+ rate you actually expect, benchmark `perCallEstimateCredits` before you declare
227
+ it (see *Benchmark your own costs* below), and keep `perCallMaxCredits` a real
228
+ ceiling. The server refuses a call whose ceiling passes it
229
+ (`grant_price_unreasonable`) — that check is what replaces the popup, so a
230
+ budget is never a blank cheque. `perCallMaxCoins`, `perCallEstimateCoins` and
231
+ `estimatedCoinsPerPeriod` (before 0.27) are accepted as the same credit numbers.
232
+ The slider's bounds, the credit value, the fee and the recommended headroom all
233
+ come from the server; read them from `getGenerationModels()`
234
+ (`standingCreditGrant`, `usdCentsPerCredit`, `feeBps`,
235
+ `recommendedDeclaredHeadroomBps`) rather than typing any of them into the game.
185
236
 
186
237
  **Handle the refusals as game states.** A budget ends for ordinary reasons and
187
238
  the game should have believable copy for each:
188
239
  `grant_limit_reached` (the player's limit is spent), `grant_stopped`,
189
240
  `grant_expired`, `grant_not_active`, `grant_concurrency` and
190
241
  `grant_rate_limited` (your own declared ceilings), `grant_insufficient_funds`
191
- (the wallet ran low — the budget resumes when it is topped up),
242
+ (the player's credits ran low — the budget resumes when they top up),
243
+ `credits_unverified` (verify the email on Genex), `generation_paused` (Genex
244
+ paused paid generation; retry later),
192
245
  `waiting_for_plan` (a personal plan's own rate limit; it resumes by itself),
193
246
  `grant_price_unreasonable`, `grant_already_active`, `external_grant_active` and
194
247
  `invalid_grant_limit`. `generationErrorMessage(code)` returns a player-facing
@@ -235,8 +288,8 @@ It resolves to **the same result `generate()` gives** — status, output, receip
235
288
  — and that result, not the pieces, is the answer. Pieces are provisional: a call
236
289
  can still fail after text has arrived (the model broke off, or a JSON answer
237
290
  did not match the schema), so let the resolved status decide what the game
238
- keeps. The price is the same fixed price: a started attempt is charged whether
239
- it succeeds, fails, or the player walks away mid-sentence.
291
+ keeps. It is billed exactly as a budget `generate()` call is — as used, on the
292
+ budget — whether it succeeds, fails, or the player walks away mid-sentence.
240
293
 
241
294
  For `outputFormat: 'json'`, `onPartialField(name, partialText)` reports the
242
295
  **first top-level string property of `schema`** as far as the model has written
@@ -276,19 +329,19 @@ classifier typed questions and gets calibrated probabilities back, typically in
276
329
  about a third of a second. It writes no prose and invents no numbers, which is
277
330
  exactly what makes it a steadier referee than a chat model asked to classify.
278
331
 
279
- It is **grant-only** and **billed as used**: a call costs a small fraction of a
280
- coin, so it is never charged a coin of its own. The budget holds a coin, calls
281
- add up against it, and a whole coin is taken each time they reach one; when the
282
- budget ends, a remainder is one coin and anything still held goes back. Ask for
283
- it when you request the budget:
332
+ It is **grant-only** and **billed as used**, on the same budget as its
333
+ generations: a call costs a small fraction of a credit, so it is never charged
334
+ a credit of its own. Calls add up on the budget, and a whole credit is taken
335
+ each time they reach one; when the budget ends, a remainder is one credit and
336
+ anything still held goes back. Ask for it when you request the budget:
284
337
 
285
338
  ```ts
286
339
  import { requestSpendGrant, judge, generationErrorMessage } from '@genex-ai/embed-sdk';
287
340
 
288
341
  const budget = await requestSpendGrant({
289
342
  models: [model.id], // or [] for a judge-only budget
290
- perCallMaxCoins: 8, perCallEstimateCoins: 5,
291
- disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCoinsPerPeriod: 20 },
343
+ perCallMaxCredits: 8, perCallEstimateCredits: 2,
344
+ disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCreditsPerPeriod: 8 },
292
345
  judge: { enabled: true, estimatedCallsPerPeriod: 30 }, // honest checks per period
293
346
  });
294
347
 
@@ -324,24 +377,26 @@ it opens no window. The answer arrives in the same response; reuse an
324
377
  out (`timeoutMs`, 1000–20000) is `unknown` and billed at its maximum, because
325
378
  the work may have run. The refusals to handle as game states:
326
379
  `judge_requires_grant` (no budget), `judge_not_enabled` (the budget was approved
327
- without the judge — request a new one), `judge_requires_coins`,
380
+ without the judge — request a new one), `judge_requires_credits` (and, on a
381
+ budget approved before credits, `judge_requires_coins`),
328
382
  `judge_period_limit` (the checks reached the per-period ceiling the player was
329
383
  shown — it rolls, so try again shortly), `judge_busy` and `judge_paused` (the
330
384
  platform's, retry later), `request_too_large` (state and questions over the
331
385
  byte bound), and every budget code above — `grant_concurrency` now also means
332
- "fits once calls in flight land", never an ended budget. The receipt is on `verdict.billing` (`chargedCoins` is always
333
- 0; `chargedUsdPicos` is what this call added); the budget's `spentCoins` and
334
- `heldCoins` are the numbers to show.
386
+ "fits once calls in flight land", never an ended budget. The receipt is on `verdict.billing` (`chargedCredits` and `chargedCoins` are
387
+ always 0; `chargedUsdPicos` is what this call added; `billingPolicy` is
388
+ `metered-credits-v1`); the budget's `spentCredits` and `heldCredits` are the
389
+ numbers to show.
335
390
 
336
- Benchmark on your own coins with `developmentJudge()` from
337
- `@genex-ai/embed-sdk/development` (same shape, `{ maxCoins, request }`). It is
338
- billed one whole coin a call on your wallet — a player's budget, which meters,
339
- spends far less for the same calls.
391
+ Benchmark on your own credits with `developmentJudge()` from
392
+ `@genex-ai/embed-sdk/development` (same shape, `{ maxCredits, request }`). It is
393
+ billed one whole credit a call — a player's budget, which meters, spends far
394
+ less for the same calls.
340
395
 
341
396
  ## Your subscription and the Genex player watcher
342
397
 
343
398
  Both approval sheets can offer the player their own Claude or ChatGPT plan
344
- beside coins, when the selected model's provider matches. That choice lives in
399
+ beside credits, when the selected model's provider matches. That choice lives in
345
400
  the trusted Genex surface only — never add a plan row to the game's own model
346
401
  picker, and never ask a player for a subscription credential. Genex neither
347
402
  collects nor hosts them.
@@ -353,7 +408,7 @@ it, Genex shows them the one-time prompt: *"Install the Genex player watcher:
353
408
  run `npx @genex-ai/cli-demo@latest player install` and approve it on Genex."*
354
409
  The game does not install, start or speak to the watcher; it only reads
355
410
  `watcherOnline` on a grant or generation view when Genex includes it. A
356
- personal-plan result costs zero coin, is metered in requests rather than coin,
411
+ personal-plan result costs nothing on Genex, is metered in requests rather than credits,
357
412
  and arrives with `source: 'external'` and `modelProvenance: 'unverified'`:
358
413
  user-supplied output, never proof that a particular model produced it, and
359
414
  never authority for money or rewards. When the player's own plan hits its rate limit
@@ -365,8 +420,17 @@ to paid work.
365
420
  SDK **0.21.0+** supports multi-step generation and usage receipts through an
366
421
  operator-registered workflow. This requires the game's trusted server executor;
367
422
  an ordinary creator API key cannot register a workflow or dispatch its steps.
368
- `generate()` and `requestWorkflow()` both require the fixed `estimateCoins`
369
- price and use the declared-attempt policy above.
423
+ **Which wallet a workflow bills is its executor's registration.** An executor
424
+ left on `funding: 'coins'` (every executor registered before credits, by
425
+ default) keeps the fixed-price coin terms below: `requestWorkflow()` requires the
426
+ fixed `estimateCoins` price, and offerings and quotes are `declared-v1` with a
427
+ multiplier of 2 or 3. An executor switched to `funding: 'credits'` issues
428
+ `metered-credits-v1` offerings and quotes instead — `estimatedCredits`,
429
+ `maxCredits`, `feeBps`, `currency: 'credits'`, coin fields 0, and the
430
+ registered `priceMultiplier` served unchanged but pricing nothing: the run is
431
+ billed its steps' real cost plus the Genex fee, rounded up to a whole credit.
432
+ Pass `maxCredits` (or `estimateCoins`, read as the same ceiling) to such a
433
+ workflow. A game must accept the new policy before its executor is switched.
370
434
 
371
435
  ```ts
372
436
  import { getWorkflowOfferings, requestWorkflow, getEmbedToken } from '@genex-ai/embed-sdk';
@@ -413,14 +477,14 @@ Recovering local state never starts a fresh charge without another player click.
413
477
  Read a fresh embed token when sending an approved run to the game backend; never
414
478
  persist or log the token.
415
479
 
416
- The catalog's `estimatedCoins` and `priceCoins` are suggested price aliases,
480
+ On a COIN executor, the catalog's `estimatedCoins` and `priceCoins` are suggested price aliases,
417
481
  and its maximum describes operator limits. Choose the game's fixed attempt price
418
482
  after development benchmarks, pass it as `estimateCoins`, and show coin plus USD.
419
483
  The player's final approval always uses the server quote. Preserve the selected
420
484
  model, bundle, funding, availability and operator-owned tariff; the game cannot
421
485
  change provider prices, dispatch costs or settlement.
422
486
 
423
- For new public workflow quotes, `maxCoins` is the same fixed amount as
487
+ For a coin executor's new public workflow quotes, `maxCoins` is the same fixed amount as
424
488
  `priceCoins`, not a promise to bill actual usage. The operator-owned multiplier
425
489
  (2 or 3, default 3) determines how much model work that fixed price can fund.
426
490
  The whole started attempt is charged once, including failed or canceled work;
@@ -431,7 +495,7 @@ artifact; the browser cannot settle it.
431
495
  Use `resumeWorkflow(generationId, { timeoutMs? })` directly from a click to
432
496
  reopen a saved approval. It reads the original request without creating a quote
433
497
  or requiring a new price, including pre-0.21 consumed and legacy approvals.
434
- Use `requestWorkflow()` with required `estimateCoins` for new operations.
498
+ Use `requestWorkflow()` with `estimateCoins` (a coin executor) or `maxCredits` (a credit executor) for new operations.
435
499
 
436
500
  Legacy quotes without `billingPolicy` retain their original fixed-price and
437
501
  refund terms. Never replace a saved quote's policy with the current catalog's
@@ -458,11 +522,11 @@ The [runtime API contract](../../CLI_INTEGRATION.md#10-player-funded-runtime-gen
458
522
  describes both APIs, executor authorization, recovery and connector endpoints.
459
523
 
460
524
 
461
- ## Benchmark your own coin costs on the server
525
+ ## Benchmark your own costs on the server
462
526
 
463
527
  `npx genex llm bench` is the CLI door onto this lane: it runs the real model
464
- against your own coin wallet, reports what it actually charged, and recommends
465
- the price to declare. Reach for the API below when you want the samples in your
528
+ against your own credits, reports what it actually cost and charged, and
529
+ recommends the per-call ceiling to declare. Reach for the API below when you want the samples in your
466
530
  own script.
467
531
 
468
532
  SDK **0.21.0+** provides `@genex-ai/embed-sdk/development`. Use it only in a
@@ -472,11 +536,13 @@ player wallet. Restricted API keys and personal-only offerings are refused.
472
536
  Keep the credential out of game code, browser environment variables and logs;
473
537
  the subpath is disabled for browser resolution and rejects browser execution.
474
538
 
475
- `maxCoins` is an explicit positive maximum from your own wallet. Development
476
- uses `consumed-v1`: actual model usage at the frozen normal tariff, including
477
- failed usage, up to that maximum. Gemini/GLM models use this normal paid tariff
478
- too. Actual zero cost is zero coin;
479
- unknown expense remains held. No personal or paid fallback occurs.
539
+ `maxCredits` (SDK 0.27.0+; `maxCoins` is the same number under its old name) is
540
+ an explicit positive maximum from your own credits. Development uses
541
+ `metered-credits-v1`: actual model usage plus the Genex fee, rounded up to a
542
+ whole credit per call, including failed usage, up to that maximum (a workflow
543
+ whose executor still bills coin uses `consumed-v1` on your coin wallet).
544
+ Gemini/GLM models are paid too. Actual zero cost is free; unknown expense
545
+ remains held. No personal or paid fallback occurs.
480
546
 
481
547
  ```ts
482
548
  import { developmentGenerate } from '@genex-ai/embed-sdk/development';
@@ -485,33 +551,37 @@ const receipt = await developmentGenerate({
485
551
  apiUrl: process.env.GENEX_API_URL!,
486
552
  creatorToken: process.env.GENEX_CREATOR_TOKEN!,
487
553
  projectId: process.env.GENEX_PROJECT_ID!,
488
- maxCoins: 5,
554
+ maxCredits: 5,
489
555
  request: {
490
556
  modelId: 'your-configured-model-id',
491
557
  prompt: 'Invent a friendly creature name.',
492
558
  outputFormat: 'text',
559
+ // maxOutputTokens: 24_000, // 0.28.0+: bench exactly what the game will ask for
493
560
  idempotencyKey: 'calibration-sample-001',
494
561
  },
495
562
  });
496
- // A 5-coin maximum can return chargedCoins: 2. Use repeated samples to choose
497
- // the public fixed estimateCoins price; public fixed 5 still charges 5.
498
- if (receipt.billingStatus === 'final') useForCalibration(receipt.chargedCoins, receipt.usage);
563
+ // A 5-credit maximum can return chargedCredits: 1 for a small call. Use the
564
+ // actual cost of repeated samples (usage.costUsdPicos) and usage.fitCredits to
565
+ // choose the ceiling your game declares as maxCredits.
566
+ if (receipt.billingStatus === 'final') useForCalibration(receipt.chargedCredits, receipt.usage);
499
567
  ```
500
568
 
501
569
  The full receipt includes execution status, output on success, charged/reserved
502
- coins and USD, plus development-only `usage: { costUsdPicos, costUsd,
570
+ credits and USD, plus development-only `usage: { costUsdPicos, costUsd,
503
571
  maxProviderUsdPicos, unknownProviderUsdPicos }`. Unknown cost is null rather
504
572
  than zero; workflow cost aggregates known actual step costs and reports remaining
505
573
  unknown exposure separately. No token counts are inferred: SDK 0.24.3+ types the
506
574
  counts the provider REPORTED (`usage.inputTokens`, `usage.outputTokens`, null
507
- when none), the call's own `usage.maxOutputTokens`, and `usage.fitCoins` — the
508
- smallest declared price whose funded output allowance holds that answer plus
509
- the stand's headroom. The declared price also decides how long the answer may
510
- be, so calibrate to at least the p95 `fitCoins` of your settled samples, not
511
- the charged coins alone. `usage.truncated` marks an answer the model had to stop
512
- writing (`error: 'provider_token_limit'`, still charged: re-run with a higher
513
- `maxCoins`), and `usage.fitExceedsCap` an answer longer than one call on that
514
- stand may produce (ask for a shorter one). When the provider
575
+ when none), the call's own `usage.maxOutputTokens`, and `usage.fitCredits` (SDK
576
+ 0.27.0+; `usage.fitCoins` on a coin row) — the smallest per-call ceiling whose
577
+ funded output allowance holds that answer plus the stand's headroom. The
578
+ ceiling also decides how long the answer may be, so declare at least the p95
579
+ `fitCredits` of your settled samples, not the charged credits alone.
580
+ `usage.truncated` marks an answer the model had to stop writing (`error:
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
515
585
  refused the request before running it (a rejected key, an unknown model, a rate
516
586
  limit — `error: 'provider_http_<status>'`), nothing is charged, the hold is
517
587
  released, and SDK 0.24.2+ types `providerMessage`: the provider's own words,
@@ -522,8 +592,8 @@ and every in-game call there answers `provider_http_401` until an operator
522
592
  replaces it — check it before a benchmark, not after.
523
593
 
524
594
  For a registered workflow, call `developmentRequestWorkflow({ apiUrl,
525
- creatorToken, projectId, workflowId, maxCoins, request: { offeringId, input,
526
- idempotencyKey? } })`. It returns the accepted, claimed workflow immediately so
595
+ creatorToken, projectId, workflowId, maxCredits, request: { offeringId, input,
596
+ idempotencyKey? } })` (on a coin executor the same number is its coin cap). It returns the accepted, claimed workflow immediately so
527
597
  your trusted executor can enqueue it. After enqueueing, call
528
598
  `waitForDevelopmentGeneration(config, id, timeoutMs?)`. Both generic and workflow
529
599
  benchmarks are recoverable with `getDevelopmentGeneration(config, id)` and
@@ -268,6 +268,18 @@ async function request(path, body) {
268
268
  function validEstimateCoins(value) {
269
269
  return Number.isSafeInteger(value) && value >= 0 && value <= 1e6;
270
270
  }
271
+ function ceilingField(options) {
272
+ const credits = options.maxCredits, coins = options.estimateCoins;
273
+ if (credits !== void 0 && !validEstimateCoins(credits)) return { error: "invalid_max_credits" };
274
+ if (coins !== void 0 && !validEstimateCoins(coins)) return { error: "invalid_estimate_coins" };
275
+ if (credits === void 0 && coins === void 0) return { error: "invalid_max_credits" };
276
+ if (credits !== void 0 && coins !== void 0 && credits !== coins) return { error: "invalid_max_credits" };
277
+ return { field: credits !== void 0 ? { maxCredits: credits } : { estimateCoins: coins } };
278
+ }
279
+ function validMaxOutputTokens(value) {
280
+ return value === void 0 || Number.isSafeInteger(value) && value >= 1;
281
+ }
282
+ var GENERATION_WAIT_MS = 12e5;
271
283
  function getGenerationModels() {
272
284
  return request("/models");
273
285
  }
@@ -299,6 +311,10 @@ function outcome(view) {
299
311
  function billingReceipt(view) {
300
312
  return {
301
313
  ...view.billingStatus !== void 0 ? { billingStatus: view.billingStatus } : {},
314
+ ...view.currency !== void 0 ? { currency: view.currency } : {},
315
+ ...view.maxCredits !== void 0 ? { maxCredits: view.maxCredits } : {},
316
+ ...view.reservedCredits !== void 0 ? { reservedCredits: view.reservedCredits } : {},
317
+ ...view.chargedCredits !== void 0 ? { chargedCredits: view.chargedCredits } : {},
302
318
  ...view.reservedCoins !== void 0 ? { reservedCoins: view.reservedCoins } : {},
303
319
  ...view.reservedDisplayUsdCents !== void 0 ? { reservedDisplayUsdCents: view.reservedDisplayUsdCents } : {},
304
320
  ...view.chargedCoins !== void 0 ? { chargedCoins: view.chargedCoins } : {},
@@ -335,29 +351,33 @@ async function poll(generationId, timeoutMs, readOutcome, popup) {
335
351
  }
336
352
  return { status: "pending", generationId, error: "wait_timeout" };
337
353
  }
338
- function waitForGeneration(generationId, timeoutMs = 6e5) {
354
+ function waitForGeneration(generationId, timeoutMs = GENERATION_WAIT_MS) {
339
355
  if (!isGenerationId(generationId)) return Promise.resolve({ status: "failed", error: "invalid_generation_id" });
340
356
  return poll(generationId, timeoutMs, outcome);
341
357
  }
342
358
  async function generate(options) {
343
- if (!validEstimateCoins(options.estimateCoins)) return { status: "failed", error: "invalid_estimate_coins" };
344
- const { timeoutMs, idempotencyKey, grantId, ...input } = options;
345
- if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ?? 6e5);
359
+ const ceiling = ceilingField(options);
360
+ if ("error" in ceiling) return { status: "failed", error: ceiling.error };
361
+ if (!validMaxOutputTokens(options.maxOutputTokens)) return { status: "failed", error: "invalid_max_output_tokens" };
362
+ const { timeoutMs, idempotencyKey, grantId, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
363
+ const input = { ...rest, ...ceiling.field };
364
+ if (grantId !== void 0) return generateUnderGrant(grantId, input, idempotencyKey, timeoutMs ?? GENERATION_WAIT_MS);
346
365
  return startGeneration(
347
366
  "/generations",
348
367
  { ...input, idempotencyKey },
349
- timeoutMs ?? 6e5,
368
+ timeoutMs ?? GENERATION_WAIT_MS,
350
369
  outcome
351
370
  );
352
371
  }
353
372
  async function requestWorkflow(options) {
354
- if (!validEstimateCoins(options.estimateCoins)) return { status: "failed", error: "invalid_estimate_coins" };
373
+ const ceiling = ceilingField(options);
374
+ if ("error" in ceiling) return { status: "failed", error: ceiling.error };
355
375
  if (!isWorkflowIdentifier(options.workflowId)) return { status: "failed", error: "invalid_workflow_id" };
356
376
  if (!isWorkflowIdentifier(options.offeringId)) return { status: "failed", error: "invalid_offering_id" };
357
377
  return startGeneration(`/workflows/${encodeURIComponent(options.workflowId)}/requests`, {
358
378
  offeringId: options.offeringId,
359
379
  input: options.input,
360
- estimateCoins: options.estimateCoins,
380
+ ...ceiling.field,
361
381
  ...options.allowExternal !== void 0 ? { allowExternal: options.allowExternal } : {},
362
382
  idempotencyKey: options.idempotencyKey
363
383
  }, options.timeoutMs ?? 6e5, authorizationOutcome, options);
@@ -409,7 +429,7 @@ async function startGeneration(path, body, timeoutMs, readOutcome, workflow, res
409
429
  throw new Error("invalid_generation_response");
410
430
  }
411
431
  const result = readOutcome(view);
412
- const needsReceipt = view.billingStatus === "pending" || view.quote?.billingPolicy !== void 0 && (view.chargedCoins ?? 0) > 0;
432
+ const needsReceipt = view.billingStatus === "pending" || view.quote?.billingPolicy !== void 0 && ((view.chargedCoins ?? 0) > 0 || (view.chargedCredits ?? 0) > 0);
413
433
  if (result && result.status !== "authorized" && !needsReceipt) {
414
434
  popup?.close();
415
435
  return result;
@@ -437,9 +457,12 @@ function invalidGrantOptions(options) {
437
457
  const judge2 = options.judge;
438
458
  if (judge2 !== void 0 && (typeof judge2 !== "object" || judge2 === null || typeof judge2.enabled !== "boolean" || !validCount(judge2.estimatedCallsPerPeriod, 1, 1e5))) return "invalid_judge_terms";
439
459
  if (!Array.isArray(options.models) || options.models.length < (judge2?.enabled ? 0 : 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";
440
- if (!validCount(options.perCallMaxCoins, 1, 1e6) || !validCount(options.perCallEstimateCoins, 1, 1e6) || options.perCallEstimateCoins > options.perCallMaxCoins) return "invalid_declared_price";
460
+ const max = options.perCallMaxCredits ?? options.perCallMaxCoins;
461
+ const estimate = options.perCallEstimateCredits ?? options.perCallEstimateCoins;
462
+ if (!validCount(max, 1, 1e6) || estimate !== void 0 && (!validCount(estimate, 1, 1e6) || estimate > max) || options.perCallMaxCredits !== void 0 && options.perCallMaxCoins !== void 0 && options.perCallMaxCredits !== options.perCallMaxCoins || options.perCallEstimateCredits !== void 0 && options.perCallEstimateCoins !== void 0 && options.perCallEstimateCredits !== options.perCallEstimateCoins) return "invalid_declared_price";
441
463
  const d = options.disclosure;
442
- if (!d || typeof d !== "object" || !["minute", "hour", "session"].includes(d.periodLabel) || !validCount(d.estimatedCallsPerPeriod, 1, 1e4) || !validCount(d.estimatedCoinsPerPeriod, 0, 1e6)) return "invalid_disclosure";
464
+ const perPeriod = d && typeof d === "object" ? d.estimatedCreditsPerPeriod ?? d.estimatedCoinsPerPeriod : void 0;
465
+ if (!d || typeof d !== "object" || !["minute", "hour", "session"].includes(d.periodLabel) || !validCount(d.estimatedCallsPerPeriod, 1, 1e4) || !validCount(perPeriod, 0, 1e6)) return "invalid_disclosure";
443
466
  if (options.maxConcurrent !== void 0 && !validCount(options.maxConcurrent, 1, 8)) return "invalid_grant_terms";
444
467
  if (options.maxCallsPerMinute !== void 0 && !validCount(options.maxCallsPerMinute, 1, 120)) return "invalid_grant_terms";
445
468
  if (options.maxPendingExternal !== void 0 && !validCount(options.maxPendingExternal, 1, 8)) return "invalid_grant_terms";
@@ -496,15 +519,16 @@ async function requestSpendGrant(options) {
496
519
  if ("status" in surface) return surface;
497
520
  const { popup, dashboard, parentOrigin: parentOrigin2 } = surface;
498
521
  try {
522
+ const estimate = options.perCallEstimateCredits ?? options.perCallEstimateCoins;
499
523
  const view = await request("/grants", {
500
524
  idempotencyKey: options.idempotencyKey ?? crypto.randomUUID(),
501
525
  models: options.models,
502
- perCallMaxCoins: options.perCallMaxCoins,
503
- perCallEstimateCoins: options.perCallEstimateCoins,
526
+ perCallMaxCredits: options.perCallMaxCredits ?? options.perCallMaxCoins,
527
+ ...estimate !== void 0 ? { perCallEstimateCredits: estimate } : {},
504
528
  disclosure: {
505
529
  periodLabel: options.disclosure.periodLabel,
506
530
  estimatedCallsPerPeriod: options.disclosure.estimatedCallsPerPeriod,
507
- estimatedCoinsPerPeriod: options.disclosure.estimatedCoinsPerPeriod
531
+ estimatedCreditsPerPeriod: options.disclosure.estimatedCreditsPerPeriod ?? options.disclosure.estimatedCoinsPerPeriod
508
532
  },
509
533
  ...options.maxConcurrent !== void 0 ? { maxConcurrent: options.maxConcurrent } : {},
510
534
  ...options.maxCallsPerMinute !== void 0 ? { maxCallsPerMinute: options.maxCallsPerMinute } : {},
@@ -548,8 +572,11 @@ async function generateUnderGrant(grantId, input, idempotencyKey, timeoutMs) {
548
572
  }
549
573
  }
550
574
  async function generateStream(options) {
551
- if (!validEstimateCoins(options.estimateCoins)) return { status: "failed", error: "invalid_estimate_coins" };
552
- const { timeoutMs, idempotencyKey, grantId, onDelta, onPartialField, signal, allowExternal: _unused, ...body } = options;
575
+ const ceiling = ceilingField(options);
576
+ if ("error" in ceiling) return { status: "failed", error: ceiling.error };
577
+ if (!validMaxOutputTokens(options.maxOutputTokens)) return { status: "failed", error: "invalid_max_output_tokens" };
578
+ const { timeoutMs, idempotencyKey, grantId, onDelta, onPartialField, signal, allowExternal: _unused, maxCredits: _credits, estimateCoins: _coins, ...rest } = options;
579
+ const body = { ...rest, ...ceiling.field };
553
580
  if (grantId === void 0 || grantId === null) return { status: "failed", error: "stream_requires_grant" };
554
581
  if (!isGrantId(grantId)) return { status: "failed", error: "invalid_grant_id" };
555
582
  const guarded = approvalGuards();
@@ -635,9 +662,9 @@ async function generateStream(options) {
635
662
  if (done) {
636
663
  const view = done;
637
664
  if (!isGenerationId(view.id) || view.grantId !== grantId || generationId !== void 0 && view.id !== generationId) throw new Error("invalid_generation_response");
638
- 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));
639
666
  }
640
- if (generationId) return finish(await poll(generationId, timeoutMs ?? 6e5, outcome));
667
+ if (generationId) return finish(await poll(generationId, timeoutMs ?? GENERATION_WAIT_MS, outcome));
641
668
  return { status: "failed", error: "generation_unavailable" };
642
669
  } catch (error) {
643
670
  if (signal?.aborted) return aborted();
@@ -704,11 +731,19 @@ function generationErrorMessage(code) {
704
731
  return "We don\u2019t know how this one ended yet \u2014 it is still being settled. Check back in a moment.";
705
732
  case "wait_timeout":
706
733
  return "This is taking longer than usual. It is still running \u2014 check back in a moment.";
707
- // --- the player's wallet ------------------------------------------------
734
+ // --- the player's credits -----------------------------------------------
735
+ case "insufficient_credits":
736
+ return "You don\u2019t have enough Genex credits for this request. Top up on Genex and try again.";
737
+ case "credits_unverified":
738
+ return "Verify your email on Genex to use your credits here.";
739
+ case "generation_paused":
740
+ return "Genex has paused generation for now. Try again later.";
741
+ case "payer_busy":
742
+ return "Genex is busy with your account for a moment. Try again shortly.";
708
743
  case "insufficient_balance":
709
- return "There isn\u2019t enough coin in your Genex wallet for this request.";
744
+ return "There isn\u2019t enough in your Genex wallet for this request.";
710
745
  case "grant_insufficient_funds":
711
- return "Your budget paused because your Genex wallet ran low. Top it up and it picks up again.";
746
+ return "Your budget paused because your Genex credits ran low. Top them up and it picks up again.";
712
747
  // --- standing budgets ---------------------------------------------------
713
748
  case "grant_limit_reached":
714
749
  return "This budget has reached the limit you set. Set up a new one to keep going.";
@@ -737,7 +772,8 @@ function generationErrorMessage(code) {
737
772
  case "judge_not_enabled":
738
773
  return "This budget doesn\u2019t cover the game\u2019s quick checks. Set up a new one to keep going.";
739
774
  case "judge_requires_coins":
740
- return "The game\u2019s quick checks are paid from your Genex wallet, not your own plan.";
775
+ case "judge_requires_credits":
776
+ return "The game\u2019s quick checks are paid from your Genex credits, not your own plan.";
741
777
  case "invalid_judge_terms":
742
778
  return "This budget request isn\u2019t valid, so nothing was requested.";
743
779
  case "judge_period_limit":
@@ -801,7 +837,8 @@ function generationErrorMessage(code) {
801
837
  return "That payment option doesn\u2019t match this request. Start it again.";
802
838
  case "invalid_declared_price":
803
839
  case "invalid_estimate_coins":
804
- return "This request\u2019s price isn\u2019t valid, so nothing was charged.";
840
+ case "invalid_max_credits":
841
+ return "This request\u2019s spending limit isn\u2019t valid, so nothing was charged.";
805
842
  // --- what the game asked for --------------------------------------------
806
843
  case "model_not_allowed":
807
844
  return "This budget doesn\u2019t cover that model. Choose one it does.";
@@ -822,9 +859,14 @@ function generationErrorMessage(code) {
822
859
  case "provider_token_limit":
823
860
  return "The model ran out of room before a usable answer was ready. The attempt is still charged.";
824
861
  case "request_too_large":
862
+ case "prompt_too_large":
863
+ case "schema_too_large":
825
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.";
826
867
  case "invalid_request":
827
868
  case "invalid_schema":
869
+ case "invalid_max_output_tokens":
828
870
  return "This request wasn\u2019t something Genex could accept.";
829
871
  case "generation_limit":
830
872
  return "As many requests are running as Genex allows at once. Wait for one to finish.";
@@ -872,7 +914,7 @@ var RETRY_FLAG = "genex:embed:retry";
872
914
  var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
873
915
  var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
874
916
  var PLAYER_ID_KEY = "genex:player";
875
- var SDK_VERSION = "0.26.0";
917
+ var SDK_VERSION = "0.28.0";
876
918
  var config2 = null;
877
919
  var state = "pending";
878
920
  var user = null;
@@ -1,6 +1,11 @@
1
1
  import { RuntimeJudgeQuestion, RuntimeWorkflowInput, RuntimeGenerationView } from '@genex/embed-protocol';
2
2
 
3
- /** Server-only benchmarks spend the authenticated creator's own coin wallet. */
3
+ /**
4
+ * Server-only benchmarks spend the authenticated creator's OWN CREDITS
5
+ * (`metered-credits-v1` since SDK 0.27: the real model cost plus the Genex fee,
6
+ * rounded up to a whole credit per call) — or, for a workflow whose executor
7
+ * still bills coin, their own coin wallet (`consumed-v1`).
8
+ */
4
9
 
5
10
  interface DevelopmentGenerationConfig {
6
11
  apiUrl: string;
@@ -8,22 +13,30 @@ interface DevelopmentGenerationConfig {
8
13
  creatorToken: string;
9
14
  projectId: string;
10
15
  }
11
- interface DevelopmentGenerationOptions extends DevelopmentGenerationConfig {
12
- /** Explicit maximum reservation in your own coins. Actual usage is charged. */
13
- maxCoins: number;
16
+ /** The builder's own cap on one call: `maxCredits`, or the old `maxCoins` (the same number). */
17
+ interface DevelopmentCap {
18
+ /** Explicit maximum reservation in your own credits. Actual usage is charged. */
19
+ maxCredits?: number;
20
+ /** @deprecated Since 0.27: the same number as `maxCredits` (a coin workflow's coin cap). */
21
+ maxCoins?: number;
22
+ }
23
+ interface DevelopmentGenerationOptions extends DevelopmentGenerationConfig, DevelopmentCap {
14
24
  request: {
15
25
  modelId: string;
16
26
  prompt: string;
17
27
  outputFormat: 'text' | 'json';
18
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;
19
32
  idempotencyKey?: string;
20
33
  };
21
- /** 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. */
22
36
  timeoutMs?: number;
23
37
  }
24
- interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig {
38
+ interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig, DevelopmentCap {
25
39
  workflowId: string;
26
- maxCoins: number;
27
40
  request: {
28
41
  offeringId: string;
29
42
  input: RuntimeWorkflowInput;
@@ -32,10 +45,7 @@ interface DevelopmentWorkflowOptions extends DevelopmentGenerationConfig {
32
45
  }
33
46
  /** Create a generic benchmark and wait for execution and its actual-usage receipt. */
34
47
  declare function developmentGenerate(options: DevelopmentGenerationOptions): Promise<RuntimeGenerationView>;
35
- interface DevelopmentJudgeOptions extends DevelopmentGenerationConfig {
36
- /** Explicit maximum reservation in your own coins. Each call is charged at the
37
- * lane's one-coin minimum (`consumed-v1`), a refusal before any work at zero. */
38
- maxCoins: number;
48
+ interface DevelopmentJudgeOptions extends DevelopmentGenerationConfig, DevelopmentCap {
39
49
  request: {
40
50
  state: unknown;
41
51
  questions: Record<string, RuntimeJudgeQuestion>;
@@ -45,10 +55,10 @@ interface DevelopmentJudgeOptions extends DevelopmentGenerationConfig {
45
55
  };
46
56
  }
47
57
  /**
48
- * The judge on the creator's OWN wallet, answered in the same response. Unlike
49
- * a player's budget — which meters judge calls and moves whole coins only as
50
- * they add up — a development call is billed at the one-coin minimum, so a
51
- * bench here overstates what a budget would spend on the same calls.
58
+ * The judge on the creator's OWN credits, answered in the same response. Unlike
59
+ * a player's budget — which meters judge calls and moves a whole credit only as
60
+ * they add up to one — a development call is rounded up to a whole credit on
61
+ * its own, so a bench here overstates what a budget would spend on the same calls.
52
62
  */
53
63
  declare function developmentJudge(options: DevelopmentJudgeOptions): Promise<RuntimeGenerationView>;
54
64
  /** Returns the accepted workflow so its trusted executor can enqueue before waiting. */
@@ -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
  }
@@ -17,8 +18,17 @@ function baseUrl(config) {
17
18
  }
18
19
  return url.origin + "/api/runtime/development/projects/" + encodeURIComponent(config.projectId);
19
20
  }
20
- function validateMaximum(maxCoins) {
21
- if (!Number.isSafeInteger(maxCoins) || maxCoins <= 0 || maxCoins > 1e6) throw new Error("invalid_max_coins");
21
+ function maximum(options) {
22
+ const valid = (value) => Number.isSafeInteger(value) && value > 0 && value <= 1e6;
23
+ if (options.maxCredits !== void 0) {
24
+ if (!valid(options.maxCredits) || options.maxCoins !== void 0 && options.maxCoins !== options.maxCredits) throw new Error("invalid_max_credits");
25
+ return { maxCredits: options.maxCredits };
26
+ }
27
+ if (!valid(options.maxCoins)) throw new Error(options.maxCoins === void 0 ? "invalid_max_credits" : "invalid_max_coins");
28
+ return { maxCoins: options.maxCoins };
29
+ }
30
+ function developmentTerms(view) {
31
+ return view.quote?.billingPolicy === "metered-credits-v1" && view.funding === "credits" || view.quote?.billingPolicy === "consumed-v1" && view.funding === "coins";
22
32
  }
23
33
  async function request(config, path, body) {
24
34
  const response = await fetch(baseUrl(config) + path, {
@@ -32,27 +42,29 @@ async function request(config, path, body) {
32
42
  const result = await response.json().catch(() => ({}));
33
43
  if (!response.ok) throw new Error(typeof result.error === "string" ? result.error : "development_generation_unavailable");
34
44
  const view = result;
35
- 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");
45
+ if (!isGenerationId(view.id) || view.projectId !== config.projectId || view.development !== true || !developmentTerms(view)) throw new Error("invalid_development_response");
36
46
  return view;
37
47
  }
38
48
  async function developmentGenerate(options) {
39
- validateMaximum(options.maxCoins);
49
+ const cap = maximum(options);
40
50
  if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) throw new Error("invalid_timeout");
41
51
  const input = options.request;
42
- const view = await request(options, "/generations", { maxCoins: options.maxCoins, request: {
52
+ if (input.maxOutputTokens !== void 0 && (!Number.isSafeInteger(input.maxOutputTokens) || input.maxOutputTokens < 1)) throw new Error("invalid_max_output_tokens");
53
+ const view = await request(options, "/generations", { ...cap, request: {
43
54
  modelId: input.modelId,
44
55
  prompt: input.prompt,
45
56
  outputFormat: input.outputFormat,
46
57
  ...input.schema === void 0 ? {} : { schema: input.schema },
58
+ ...input.maxOutputTokens === void 0 ? {} : { maxOutputTokens: input.maxOutputTokens },
47
59
  idempotencyKey: input.idempotencyKey ?? crypto.randomUUID()
48
60
  } });
49
- return wait(options, view, options.timeoutMs ?? 6e5);
61
+ return wait(options, view, options.timeoutMs ?? DEVELOPMENT_WAIT_MS);
50
62
  }
51
63
  async function developmentJudge(options) {
52
- validateMaximum(options.maxCoins);
64
+ const cap = maximum(options);
53
65
  const input = options.request;
54
66
  if (!input || input.state === void 0 || !input.questions || typeof input.questions !== "object") throw new Error("invalid_request");
55
- const view = await request(options, "/judgments", { maxCoins: options.maxCoins, request: {
67
+ const view = await request(options, "/judgments", { ...cap, request: {
56
68
  state: input.state,
57
69
  questions: input.questions,
58
70
  ...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
@@ -62,11 +74,11 @@ async function developmentJudge(options) {
62
74
  return view;
63
75
  }
64
76
  async function developmentRequestWorkflow(options) {
65
- validateMaximum(options.maxCoins);
77
+ const cap = maximum(options);
66
78
  assertIdentifier(options.workflowId);
67
79
  assertIdentifier(options.request.offeringId);
68
80
  const view = await request(options, "/workflows/" + encodeURIComponent(options.workflowId) + "/requests", {
69
- maxCoins: options.maxCoins,
81
+ ...cap,
70
82
  request: {
71
83
  offeringId: options.request.offeringId,
72
84
  input: options.request.input,
@@ -100,7 +112,7 @@ async function wait(config, initial, timeoutMs) {
100
112
  }
101
113
  return view;
102
114
  }
103
- async function waitForDevelopmentGeneration(config, generationId, timeoutMs = 6e5) {
115
+ async function waitForDevelopmentGeneration(config, generationId, timeoutMs = DEVELOPMENT_WAIT_MS) {
104
116
  return wait(config, await getDevelopmentGeneration(config, generationId), timeoutMs);
105
117
  }
106
118
  export {
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { RuntimeJudgeQuestion, RuntimeJudgeAnswer, RuntimeJudgmentView, RuntimeWorkflowInput, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGrantView, RuntimeGenerationView, RuntimeGenerationModels, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
2
- export { RuntimeBillingPolicy, RuntimeExternalProvider, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationModels, RuntimeGenerationStatus, RuntimeGenerationStreamEvent, RuntimeGenerationView, RuntimeGrantJudgeTerms, RuntimeGrantStatus, RuntimeGrantTerms, RuntimeGrantView, RuntimeJudgeAnswer, RuntimeJudgeCriterion, RuntimeJudgeQuestion, RuntimeJudgmentView, RuntimeWorkflowInput, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
2
+ export { RuntimeBillingPolicy, RuntimeCurrency, RuntimeExternalProvider, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationModels, RuntimeGenerationStatus, RuntimeGenerationStreamEvent, RuntimeGenerationView, RuntimeGrantJudgeTerms, RuntimeGrantStatus, RuntimeGrantTerms, RuntimeGrantView, RuntimeJudgeAnswer, RuntimeJudgeCriterion, RuntimeJudgeQuestion, RuntimeJudgmentView, RuntimeWorkflowInput, RuntimeWorkflowOfferings } from '@genex/embed-protocol';
3
3
 
4
4
  /** A thing the game sells. Resolved server-side; the game never sets a price. */
5
5
  interface ShopItem {
@@ -122,17 +122,40 @@ declare function buy(opts: {
122
122
  }): Promise<PurchaseResult>;
123
123
 
124
124
  interface GenerateOptions {
125
- /** Fixed coin price of a started attempt. Zero is accepted only for server-authorized free options. */
126
- estimateCoins: number;
125
+ /**
126
+ * The call's CEILING in the player's Genex credits (SDK 0.27+). Not a price:
127
+ * the call is billed AS USED — its real model cost plus the Genex fee, and a
128
+ * one-time call rounds that up to a whole credit — and never past this. The
129
+ * ceiling also funds how long the answer may be, so benchmark it
130
+ * (`genex llm bench`) rather than guess. Pass this or `estimateCoins`.
131
+ */
132
+ maxCredits?: number;
133
+ /** @deprecated Since 0.27: the same number as `maxCredits`, read by the server
134
+ * as the call's credit ceiling. Kept so games built on earlier versions work. */
135
+ estimateCoins?: number;
127
136
  modelId: string;
128
137
  prompt: string;
129
138
  outputFormat: 'text' | 'json';
130
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;
131
149
  /** Allow player-supplied results through their own configured Claude or ChatGPT account. Defaults off. */
132
150
  allowExternal?: boolean;
133
151
  /** Reuse for retries of the same operation, including after a game reload. */
134
152
  idempotencyKey?: string;
135
- /** 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
+ */
136
159
  timeoutMs?: number;
137
160
  /**
138
161
  * A standing budget from requestSpendGrant(). With one, the call is admitted
@@ -153,8 +176,15 @@ interface RuntimeGenerationResult extends RuntimeGenerationBilling {
153
176
  error?: string;
154
177
  }
155
178
  interface RequestWorkflowOptions {
156
- /** Fixed coin price of a started attempt, including failed or canceled work. */
157
- estimateCoins: number;
179
+ /**
180
+ * The operation's ceiling. A workflow whose executor bills coin (the default
181
+ * for every executor registered before credits) reads it as its fixed coin
182
+ * price of a started attempt; one whose executor bills credits reads it as the
183
+ * credit ceiling of a request billed as used. Pass this or `maxCredits`.
184
+ */
185
+ estimateCoins?: number;
186
+ /** The credit ceiling, for a workflow whose executor bills credits (SDK 0.27+). */
187
+ maxCredits?: number;
158
188
  /** Offer configured personal Claude/ChatGPT funding on the same quote. Defaults off. */
159
189
  allowExternal?: boolean;
160
190
  workflowId: string;
@@ -205,16 +235,30 @@ interface SpendGrantDisclosure {
205
235
  periodLabel: 'minute' | 'hour' | 'session';
206
236
  /** Honest expected calls per period. The sheet shows the player a worst case beside it. */
207
237
  estimatedCallsPerPeriod: number;
208
- /** Honest expected coin per period, attributed to the game, never as a Genex figure. */
209
- estimatedCoinsPerPeriod: number;
238
+ /** Honest expected credits per period, attributed to the game, never as a
239
+ * Genex figure (SDK 0.27+). Pass this or `estimatedCoinsPerPeriod`. */
240
+ estimatedCreditsPerPeriod?: number;
241
+ /** @deprecated Since 0.27: the same number as `estimatedCreditsPerPeriod`. */
242
+ estimatedCoinsPerPeriod?: number;
210
243
  }
211
244
  interface SpendGrantOptions {
212
245
  /** Models this budget may spend on, from getGenerationModels(). One to eight. */
213
246
  models: string[];
214
- /** Hard per-call ceiling. The server refuses a call declaring more. */
215
- perCallMaxCoins: number;
216
- /** The honest per-call price the disclosure is built on. At most perCallMaxCoins. */
217
- perCallEstimateCoins: number;
247
+ /**
248
+ * Hard per-call CEILING in credits (SDK 0.27+): the server refuses a call
249
+ * whose `maxCredits` is higher. Calls are billed as used on the budget, so
250
+ * this bounds what one call may reach, not what it costs. Pass this or
251
+ * `perCallMaxCoins`.
252
+ */
253
+ perCallMaxCredits?: number;
254
+ /** The honest per-call estimate, in credits, the disclosure and a personal
255
+ * plan's request count are built on — never a price. At most the ceiling;
256
+ * defaults to it. */
257
+ perCallEstimateCredits?: number;
258
+ /** @deprecated Since 0.27: the same number as `perCallMaxCredits`. */
259
+ perCallMaxCoins?: number;
260
+ /** @deprecated Since 0.27: the same number as `perCallEstimateCredits`. */
261
+ perCallEstimateCoins?: number;
218
262
  disclosure: SpendGrantDisclosure;
219
263
  /** Calls this budget may have in flight at once. Server default applies when omitted. */
220
264
  maxConcurrent?: number;
@@ -222,14 +266,14 @@ interface SpendGrantOptions {
222
266
  maxCallsPerMinute?: number;
223
267
  /** Personal-plan jobs that may be queued at once. Server default applies when omitted. */
224
268
  maxPendingExternal?: number;
225
- /** Offer the player's own Claude/ChatGPT plan beside coins. Defaults off. */
269
+ /** Offer the player's own Claude/ChatGPT plan beside credits. Defaults off. */
226
270
  allowExternal?: boolean;
227
271
  /**
228
- * The game also calls judge() — a fast classifier billed as used rather than
229
- * per request. The sheet tells the player so, beside the server's own worst
230
- * case for `estimatedCallsPerPeriod` calls per `disclosure.periodLabel`. A
231
- * budget with the judge is coin-funded: `allowExternal` offers nothing on it.
232
- * With `enabled: true`, `models` may be empty for a judge-only budget.
272
+ * The game also calls judge() — a fast classifier billed as used, like every
273
+ * call on the budget. The sheet tells the player so, beside the server's own
274
+ * worst case for `estimatedCallsPerPeriod` calls per `disclosure.periodLabel`.
275
+ * A budget with the judge is paid in credits: `allowExternal` offers nothing
276
+ * on it. With `enabled: true`, `models` may be empty for a judge-only budget.
233
277
  */
234
278
  judge?: {
235
279
  enabled: boolean;
@@ -318,7 +362,7 @@ interface JudgeResult {
318
362
  /** One typed answer per question; present only on `succeeded`. */
319
363
  answers?: Record<string, RuntimeJudgeAnswer>;
320
364
  error?: string;
321
- /** Where the call's money went: never a coin of its own, always the budget's meter. */
365
+ /** Where the call's money went: never a credit of its own, always the budget's meter. */
322
366
  billing?: RuntimeJudgmentView['billing'];
323
367
  }
324
368
  /**
package/dist/index.js CHANGED
@@ -34,7 +34,7 @@ import {
34
34
  waitForAuth,
35
35
  waitForGeneration,
36
36
  waitForPlayer
37
- } from "./chunk-KEPAMDTE.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-KEPAMDTE.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.26.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",