@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 +50 -7
- package/dist/{chunk-7SWNXF5V.js → chunk-SJLIF32C.js} +22 -8
- package/dist/development.d.ts +5 -1
- package/dist/development.js +5 -2
- package/dist/index.d.ts +15 -1
- package/dist/index.js +1 -1
- package/dist/sentry.js +1 -1
- package/package.json +1 -1
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
|
|
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`, `
|
|
57
|
-
`
|
|
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:
|
|
168
|
-
player, a trusted parent origin, and no
|
|
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
|
|
549
|
-
|
|
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 =
|
|
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 ??
|
|
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 ??
|
|
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 ??
|
|
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 ??
|
|
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 "
|
|
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.
|
|
920
|
+
var SDK_VERSION = "0.29.0";
|
|
907
921
|
var config2 = null;
|
|
908
922
|
var state = "pending";
|
|
909
923
|
var user = null;
|
package/dist/development.d.ts
CHANGED
|
@@ -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 {
|
package/dist/development.js
CHANGED
|
@@ -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 ??
|
|
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 =
|
|
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
|
-
/**
|
|
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
package/dist/sentry.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@genex-ai/embed-sdk",
|
|
3
|
-
"version": "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",
|