@genex-ai/embed-sdk 0.30.1 → 0.32.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 +249 -3
- package/dist/{chunk-FBJN7DGJ.js → chunk-NBCL5P5V.js} +809 -67
- package/dist/chunk-QBCWKMVQ.js +534 -0
- package/dist/development.d.ts +1 -1
- package/dist/development.js +1 -1
- package/dist/index.d.ts +276 -10
- package/dist/index.js +26 -2
- package/dist/{runtime-generation-sXuSFc3c.d.ts → runtime-generation-B3oFDmCp.d.ts} +8 -0
- package/dist/sentry.js +2 -2
- package/package.json +1 -1
- package/dist/chunk-MJPLBT3T.js +0 -264
package/README.md
CHANGED
|
@@ -40,6 +40,220 @@ sees; anyone else there resolves `{ staging: true }`. Names match
|
|
|
40
40
|
`^[a-z0-9_-]{1,64}$`. Limits, quotas and endpoints:
|
|
41
41
|
[§6a](../../CLI_INTEGRATION.md#6a-shared-collections--event-streams).
|
|
42
42
|
|
|
43
|
+
## Entry URL and shells
|
|
44
|
+
|
|
45
|
+
SDK **0.32.0+**. The link a visitor opened is the game's: an invite
|
|
46
|
+
(`?room=abc`), a seed, a route (`#lobby`). The SDK keeps it across sign-in and
|
|
47
|
+
gives it back the same way wherever the game runs.
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { getEntry, getShell, onShellClosing, savePlayerState } from "@genex-ai/embed-sdk";
|
|
51
|
+
|
|
52
|
+
const entry = getEntry(); // safe before initEmbed()
|
|
53
|
+
const room = entry.params.get("room"); // ?room=abc -> "abc"
|
|
54
|
+
const route = entry.hash; // #lobby -> "#lobby"
|
|
55
|
+
const from = entry.referrer; // "https://example.com", or null
|
|
56
|
+
|
|
57
|
+
if (getShell() === "app") hideInstallBanner();
|
|
58
|
+
onShellClosing(() => void savePlayerState(progress));
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`getShell()` answers which of the four shells the page is in. It is a fact
|
|
62
|
+
about the page, not a permission and not who is signed in.
|
|
63
|
+
|
|
64
|
+
| `getShell()` | The game is | `search` and `hash` are | `referrer` is |
|
|
65
|
+
| --- | --- | --- | --- |
|
|
66
|
+
| `page` | in a frame: its Genex game page, or any other page that embeds it | the frame's own address | the origin the game page passed on the frame's address |
|
|
67
|
+
| `standalone` | on its own address in a browser tab | its own address, with the fragment restored after the sign-in round trip | the origin carried through that round trip |
|
|
68
|
+
| `app` | inside the Genex mobile app | the address the app opened | `null`: the app passes none |
|
|
69
|
+
| `local` | on a dev server (`localhost`), in local test mode | the URL you typed | `document.referrer`'s origin |
|
|
70
|
+
|
|
71
|
+
`page` means a frame, whoever made it. Framed by another site, a game still
|
|
72
|
+
reads `page`, and the calls that need Genex around the frame
|
|
73
|
+
(`openExternal()`, `saveFile()`) resolve `unsupported`. `app` is read off the
|
|
74
|
+
WebView the Genex app runs games in (a top-level page with
|
|
75
|
+
`window.ReactNativeWebView`), whichever way the app opened the game; any other
|
|
76
|
+
React Native WebView reads the same, and the `app` answers below are the Genex
|
|
77
|
+
app's: in another wrapper `keepAwake(true)` still resolves `ok` without holding
|
|
78
|
+
the screen on.
|
|
79
|
+
|
|
80
|
+
**Read your link from `getEntry()`, not from `location` or
|
|
81
|
+
`document.referrer`.** A standalone visit goes through one sign-in round trip
|
|
82
|
+
(`/play/authorize`) and comes back with Genex's own fragment in the address
|
|
83
|
+
bar. `initEmbed()` removes it and puts the game's fragment back, but that
|
|
84
|
+
rewrite fires no `hashchange`, so code that read `location.hash` first saw the
|
|
85
|
+
wrong value and is never told. After the round trip `document.referrer` is
|
|
86
|
+
Genex, and inside the game page it always is. `getEntry()` gives the same
|
|
87
|
+
answer before and after `initEmbed()`.
|
|
88
|
+
|
|
89
|
+
What survives, and what does not:
|
|
90
|
+
|
|
91
|
+
- **Query.** The same pairs, in order and byte for byte (`?film` stays `?film`,
|
|
92
|
+
`%20` stays `%20`). Up to 1024 characters, not counting the `?`; a longer
|
|
93
|
+
query is dropped whole, never cut.
|
|
94
|
+
- **Fragment.** Up to 4096 characters.
|
|
95
|
+
- **Referrer.** The origin only, `http` or `https`, never a path or a query.
|
|
96
|
+
It is resolved once per browser tab and kept in the tab's `sessionStorage`,
|
|
97
|
+
so a reload answers the same; a second arrival in the same tab keeps the
|
|
98
|
+
first answer. Where the browser withholds that storage from the game (site
|
|
99
|
+
data blocked), nothing is kept and a reload answers `null`, or Genex's own
|
|
100
|
+
origin, not the site the visitor first came from. Treat it as attribution,
|
|
101
|
+
not proof: a link can claim any origin.
|
|
102
|
+
- **Reserved names.** `embed` and every key that starts with `genex_` belong to
|
|
103
|
+
the platform everywhere, in the query and in the fragment. `getEntry()`
|
|
104
|
+
leaves them out, and a fragment that contains `genex_` is not carried at
|
|
105
|
+
all. On a link to the game's page on Genex, and in the Genex app, `ref`,
|
|
106
|
+
`s`, `from`, `remix` and `slug` are the platform's too and do not reach the
|
|
107
|
+
game, though they do on the game's own address. On the game page the
|
|
108
|
+
fragment `#credits` opens Genex's own settings and is not carried either. A
|
|
109
|
+
link that has to work everywhere uses other names.
|
|
110
|
+
|
|
111
|
+
The platform is updated separately from your game. Where the game page, the
|
|
112
|
+
app or the sign-in round trip does not pass a value yet, `getEntry()` returns
|
|
113
|
+
`''` or `null` for it, never an error. A game published on an SDK older than
|
|
114
|
+
0.32.0 does not get its fragment or referrer back: republish to pick this up.
|
|
115
|
+
On the game's own address Genex decides that from the range in the game's
|
|
116
|
+
`package.json` as `genex preview` / `genex publish` recorded it for the build:
|
|
117
|
+
`^0.32.0` counts, `^0.31.0` does not even when 0.32 is what got installed, and
|
|
118
|
+
`workspace:*` or `latest` do not.
|
|
119
|
+
|
|
120
|
+
`onShellClosing(cb)` runs `cb` when the page is being taken away: the
|
|
121
|
+
browser's `pagehide` (tab closed, reloaded, navigated away) and the Genex app
|
|
122
|
+
closing the game. It is called once per closing and returns an unsubscribe
|
|
123
|
+
function. On the browser's `pagehide` a small `savePlayerState()` started
|
|
124
|
+
there still lands. In the app that is not verified: the app takes the game
|
|
125
|
+
away a moment after the call. So it is the last chance to save, not the only
|
|
126
|
+
one, and a phone can also drop a backgrounded tab without telling the page:
|
|
127
|
+
save as the game goes. A game cannot block the close or ask the player to
|
|
128
|
+
confirm it.
|
|
129
|
+
|
|
130
|
+
## Platform capabilities
|
|
131
|
+
|
|
132
|
+
SDK **0.32.0+**. The browser gives a page different powers in each shell. The
|
|
133
|
+
Genex game page frames a game in a sandbox that withholds new windows,
|
|
134
|
+
downloads and navigating the page around it, and the Genex app is one WebView
|
|
135
|
+
that never leaves the game. So `window.open()` or a click on `<a download>`
|
|
136
|
+
works on the game's own link and silently does nothing on Genex. Use these
|
|
137
|
+
instead: one call each, the same in every shell.
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
import { share, copyText, openExternal, saveFile, setFullscreen, keepAwake, haptic, supports } from "@genex-ai/embed-sdk";
|
|
141
|
+
|
|
142
|
+
inviteButton.addEventListener("click", async () => {
|
|
143
|
+
const { status, url } = await share({ text: "Join my room", params: { room } });
|
|
144
|
+
if (status === "copied") toast("Link copied");
|
|
145
|
+
if (status === "unavailable") showLink(url);
|
|
146
|
+
});
|
|
147
|
+
|
|
148
|
+
discordButton.addEventListener("click", async () => {
|
|
149
|
+
const result = await openExternal("https://discord.gg/my-server");
|
|
150
|
+
if (!result.ok && result.error !== "dismissed") showLink("discord.gg/my-server");
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**Call them from a click or tap handler, before any `await`.** The browser
|
|
155
|
+
lets a page share, copy, open a tab or go fullscreen only while a click is
|
|
156
|
+
being handled, and one click buys one action. Inside the game page that same
|
|
157
|
+
click is what lets Genex act for the game, so the SDK sends its request before
|
|
158
|
+
the call returns.
|
|
159
|
+
|
|
160
|
+
Every function resolves. None rejects, so there is nothing to `catch`. A call
|
|
161
|
+
that waits for Genex waits against a timer (`timeout` below). `share()` is the
|
|
162
|
+
one wait without a timer: it resolves when the player picks a target in the
|
|
163
|
+
system share sheet or closes it, however long they keep it open. `share()`
|
|
164
|
+
resolves `{ status, url }`; the others resolve `{ ok: true }` or
|
|
165
|
+
`{ ok: false, error }`; `haptic()` returns nothing.
|
|
166
|
+
|
|
167
|
+
| Function | On the Genex game page (`page`) | On its own address (`standalone`, `local`) | In the Genex app (`app`) |
|
|
168
|
+
| --- | --- | --- | --- |
|
|
169
|
+
| `share({ text?, params? })` | the system share sheet where the browser offers one, else the link is copied | the same | the same |
|
|
170
|
+
| `copyText(text)` | the clipboard | the clipboard | the clipboard, where the app's web view has one |
|
|
171
|
+
| `keepAwake(on)` | a screen wake lock | a screen wake lock | `ok`: the app already keeps the screen on |
|
|
172
|
+
| `haptic(kind)` | a vibration where the browser has one | the same | nothing |
|
|
173
|
+
| `openExternal(url)` | Genex asks the player, then opens a new tab | a new tab | `unsupported` |
|
|
174
|
+
| `saveFile(blob, name)` | Genex asks the player, then saves the file | a download | `unsupported` |
|
|
175
|
+
| `setFullscreen(on)` | the game page's own fullscreen | the browser's fullscreen | `unsupported`: the game already has the whole screen |
|
|
176
|
+
|
|
177
|
+
- **`share()`** builds the link itself; a game never supplies it. It is the
|
|
178
|
+
game's page on Genex where Genex serves the live build or frames the game,
|
|
179
|
+
and otherwise the address the game is on: a creator's domain, a preview
|
|
180
|
+
address, a dev server, or a frame on another site. Your `params` are added
|
|
181
|
+
to it, and whoever opens the link reads them back with `getEntry().params`.
|
|
182
|
+
`embed`, `ref`, `s`, `from`, `remix`, `slug` and every name starting
|
|
183
|
+
`genex_` are reserved and left out, and params that would make the query
|
|
184
|
+
longer than 1024 characters (not counting the `?`) are left out whole (one
|
|
185
|
+
console warning says so). `text` goes to the share sheet only. `status` is
|
|
186
|
+
`shared`, `copied`, `dismissed` (the player closed the sheet) or
|
|
187
|
+
`unavailable` (show `url` yourself). In local test mode the sheet is never
|
|
188
|
+
opened, so an automated browser is not left waiting on it: the link is
|
|
189
|
+
copied.
|
|
190
|
+
- **`openExternal()`** takes an absolute `https://` URL of at most 2048
|
|
191
|
+
characters. On the game page Genex shows the player where the link goes and
|
|
192
|
+
opens it on their click; `dismissed` is their no.
|
|
193
|
+
- **`saveFile()`** takes a `Blob` of at most 50 MB whose `type` is PNG, JPEG,
|
|
194
|
+
WebP, WebM, MP4, JSON or plain text, and a file name of 1 to 128 characters
|
|
195
|
+
with no `/` or `\` in it. The same bounds apply in every shell, so a save
|
|
196
|
+
that works on the game's own link works on Genex. The saved file's extension
|
|
197
|
+
follows the type: `saveFile(pngBlob, "boss fight")` saves `boss fight.png`.
|
|
198
|
+
- **`setFullscreen()`** on the game page is the page's fullscreen, the one its
|
|
199
|
+
own button gives, with the page's controls on top of the game. A game's own
|
|
200
|
+
`requestFullscreen()` still works there for the frame's document. Entering
|
|
201
|
+
needs the player's click, tap or key press inside the game, and a click on
|
|
202
|
+
the page around the game in the five seconds before does not count; leaving
|
|
203
|
+
needs nothing. Nothing stays fullscreen while Genex shows the player a sheet
|
|
204
|
+
(a link, a file, a purchase): a fullscreen asked for in the same tick as one
|
|
205
|
+
of those is left again and answers `busy`.
|
|
206
|
+
- **`keepAwake(true)`** holds until `keepAwake(false)`. The browser drops the
|
|
207
|
+
lock whenever the tab is hidden, and the SDK takes it again when the player
|
|
208
|
+
comes back.
|
|
209
|
+
- **`haptic(kind)`** takes `selection`, `light`, `medium`, `heavy`, `success`,
|
|
210
|
+
`warning` or `error`. It buzzes on Android browsers after the player's first
|
|
211
|
+
tap, and does nothing on an iPhone or in the Genex app. Never make it the
|
|
212
|
+
only signal that something happened.
|
|
213
|
+
|
|
214
|
+
**Pointer lock.** Genex asks the player on a sheet drawn around the game, and
|
|
215
|
+
the player needs a cursor to answer. A game that holds the pointer (mouse
|
|
216
|
+
look) keeps it, hidden, until the lock ends, and only the game's own document
|
|
217
|
+
can end it. So on the game page the SDK calls `document.exitPointerLock()`
|
|
218
|
+
before it asks for a link (`openExternal()`), a file (`saveFile()`), a
|
|
219
|
+
purchase (`buy()`), a generation approval or a budget. The game hears
|
|
220
|
+
`pointerlockchange`, as it does when the player presses Escape: take the lock
|
|
221
|
+
again on the next click. `setFullscreen()` does not release it. A game built
|
|
222
|
+
on an SDK older than 0.32.0 does not do this: its lock stays until the player
|
|
223
|
+
presses Escape.
|
|
224
|
+
|
|
225
|
+
`supports(name)` answers, synchronously, whether a call can do its job here:
|
|
226
|
+
`share`, `copy` (`copyText`), `awake` (`keepAwake`), `haptic`, `open`
|
|
227
|
+
(`openExternal`), `save` (`saveFile`), `fullscreen` (`setFullscreen`). Use it
|
|
228
|
+
to decide whether to draw a button. On the game page the answer for `open`,
|
|
229
|
+
`save` and the page's fullscreen arrives with the identity handshake, so ask
|
|
230
|
+
after `waitForPlayer()`. It is a hint; the call's own result is the truth.
|
|
231
|
+
|
|
232
|
+
Why a call did not happen, as `error`:
|
|
233
|
+
|
|
234
|
+
| `error` | It means | What to do |
|
|
235
|
+
| --- | --- | --- |
|
|
236
|
+
| `unsupported` | this shell or this browser cannot do it | hide the button, or show the link or the data another way |
|
|
237
|
+
| `needs_gesture` | the browser wants a click or a tap behind the call. On the game page `setFullscreen(true)` also answers it when no click, tap or key press of the player's INSIDE the game stands behind it, which includes the five seconds after they clicked or typed on the page around the game | call it straight from the handler, before any `await`, and keep the button up: the player's next click in the game works |
|
|
238
|
+
| `dismissed` | the player said no | nothing; it is not an error |
|
|
239
|
+
| `busy` | another request is still waiting for the player's answer, or a `setFullscreen(true)` the browser has not answered yet | ignore the extra click |
|
|
240
|
+
| `rate_limited` | the game asked too often | do not call these on a timer |
|
|
241
|
+
| `invalid_request` | the arguments are outside the bounds above | fix the call |
|
|
242
|
+
| `too_large` | the file is over 50 MB | save something smaller |
|
|
243
|
+
| `timeout` | Genex did not answer: within 3 seconds for fullscreen, three minutes for a link or a file, which wait for the player | treat it like `unsupported` for this click |
|
|
244
|
+
|
|
245
|
+
`unsupported` and `timeout` are normal answers, not bugs. The platform is
|
|
246
|
+
updated separately from your game: on a game page that does not take these
|
|
247
|
+
requests yet, `openExternal()` and `saveFile()` resolve `unsupported` without
|
|
248
|
+
asking, and `setFullscreen()` fullscreens the frame's own document as a game
|
|
249
|
+
could before.
|
|
250
|
+
|
|
251
|
+
What has no call here, on purpose. `alert()`, `confirm()`, `prompt()` and
|
|
252
|
+
"Leave site?" prompts show nothing on the game page: draw dialogs in the game,
|
|
253
|
+
and save from `onShellClosing()`. Reading the clipboard is not available: listen
|
|
254
|
+
for the `paste` event. Sign-in popups for other services, notifications and
|
|
255
|
+
the tab's title are not available to a framed game.
|
|
256
|
+
|
|
43
257
|
## Generate during play
|
|
44
258
|
|
|
45
259
|
Runtime generation requires a signed-in player in a published game and an
|
|
@@ -235,6 +449,38 @@ approval window passes, `pending` with `error: 'wait_timeout'` when the SDK
|
|
|
235
449
|
stopped waiting (the sheet may still be open), and `failed` with a server code.
|
|
236
450
|
The successful result carries `grantId` and the full server `grant` view.
|
|
237
451
|
|
|
452
|
+
**One live budget per player per game, and the newest approval wins.** Genex
|
|
453
|
+
never runs two budgets of one game for one player (per payment door). If you
|
|
454
|
+
ask while one is already running, the Genex sheet tells the player before they
|
|
455
|
+
approve that the new budget replaces the running one (and what it has used);
|
|
456
|
+
approving it stops the old budget and starts the new one in one step. Calls
|
|
457
|
+
the old budget already started still finish and are charged to it; a game
|
|
458
|
+
still holding the old id is refused `grant_stopped`, and `getSpendGrant(oldId)`
|
|
459
|
+
reads `stopped` with `stopReason: 'replaced'`. So don't ask every session —
|
|
460
|
+
reuse the running budget first (SDK **0.31.0+**):
|
|
461
|
+
|
|
462
|
+
```ts
|
|
463
|
+
import { getActiveSpendGrant } from '@genex-ai/embed-sdk';
|
|
464
|
+
|
|
465
|
+
// On boot, or after `grant_stopped`: the player's live budget in THIS game.
|
|
466
|
+
const running = await getActiveSpendGrant(); // RuntimeGrantView | null
|
|
467
|
+
if (running) grantId = running.id;
|
|
468
|
+
else grantId = (await requestSpendGrant(budgetRequest)).grantId; // from a click
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
`getActiveSpendGrant()` (SDK **0.31.0+**) returns the same view as
|
|
472
|
+
`getSpendGrant(id)`, or `null` when the player has no live budget in this game.
|
|
473
|
+
"Live" means it can run calls now or once its reason clears (`active`,
|
|
474
|
+
`suspended_insufficient_funds`, `waiting_for_plan`); a stopped, expired or
|
|
475
|
+
used-up budget is `null`, like one that never existed. It is scoped by the
|
|
476
|
+
player's token to this player and this game, so it never finds another game's
|
|
477
|
+
budget or another player's. A guest rejects with `no_player_session`, and any
|
|
478
|
+
other refusal rejects with the server's code, like `getSpendGrant()`. It is a
|
|
479
|
+
read: it never asks the player anything, so a game may call it on boot with no
|
|
480
|
+
click behind it — and, since only `requestSpendGrant()` needs a click, the one
|
|
481
|
+
prompt a returning player sees is the one their running budget does not cover. The development lane (`@genex-ai/embed-sdk/development`) has
|
|
482
|
+
no budgets, so there is no counterpart there.
|
|
483
|
+
|
|
238
484
|
`generate({ grantId })` runs one call under that budget. It opens **no window,
|
|
239
485
|
posts no parent message and needs no user gesture**, so it works from a game
|
|
240
486
|
loop or a timer. Every other guard is unchanged: the published game (or its
|
|
@@ -257,8 +503,8 @@ those at 0). Poll it on the
|
|
|
257
503
|
cadence your HUD needs — never derive the remaining budget from your own count
|
|
258
504
|
of calls, and never show a figure the server did not send. Store `grantId` the
|
|
259
505
|
way you store a `generationId`; `getSpendGrant()` recovers the budget after a
|
|
260
|
-
reload,
|
|
261
|
-
approval. `stopSpendGrant(id)` releases it when your feature ends. Stopping is
|
|
506
|
+
reload, `getActiveSpendGrant()` finds it when the id is lost, and a budget
|
|
507
|
+
whose status is no longer live simply needs a new approval. `stopSpendGrant(id)` releases it when your feature ends. Stopping is
|
|
262
508
|
prospective: calls already started finish and are charged. The player has the
|
|
263
509
|
same lever on Genex, on every page, and theirs always outranks the game's.
|
|
264
510
|
|
|
@@ -285,7 +531,7 @@ the game should have believable copy for each:
|
|
|
285
531
|
`credits_unverified` (verify the email on Genex), `generation_paused` (Genex
|
|
286
532
|
paused paid generation; retry later),
|
|
287
533
|
`waiting_for_plan` (a personal plan's own rate limit; it resumes by itself),
|
|
288
|
-
`grant_price_unreasonable`, `
|
|
534
|
+
`grant_price_unreasonable`, `external_grant_active` and
|
|
289
535
|
`invalid_grant_limit`. `generationErrorMessage(code)` returns a player-facing
|
|
290
536
|
sentence for every one of these and for every one-time code as well; show it, or
|
|
291
537
|
write your own in-fiction line keyed off the same code. Never show the raw code,
|