@genex-ai/embed-sdk 0.31.0 → 0.33.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 +294 -0
- package/dist/{chunk-QNZZIJGP.js → chunk-NI554TIV.js} +955 -66
- package/dist/chunk-QBCWKMVQ.js +534 -0
- package/dist/development.js +1 -1
- package/dist/index.d.ts +316 -8
- package/dist/index.js +30 -2
- 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,300 @@ 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
|
+
|
|
257
|
+
## Request a Coin payment
|
|
258
|
+
|
|
259
|
+
SDK **0.33.0+**. Use `requestPayment()` when an action needs payment: an extra turn, access to a
|
|
260
|
+
room, a custom upgrade. No product registration or shop card is required. Pass
|
|
261
|
+
the title, optional description and Coin amount; Genex freezes those terms,
|
|
262
|
+
shows its own confirmation with the real-money equivalent, and charges only
|
|
263
|
+
after the player agrees. The game never confirms a charge itself.
|
|
264
|
+
|
|
265
|
+
```ts
|
|
266
|
+
import { requestPayment, getPayment, getPayments } from '@genex-ai/embed-sdk';
|
|
267
|
+
|
|
268
|
+
// Your game saves the order ID AND its terms before enabling the button.
|
|
269
|
+
// Keep this order after a reload or timeout; don't generate a new ID on retry.
|
|
270
|
+
const order = await loadOrCreateOrderForCurrentAction();
|
|
271
|
+
|
|
272
|
+
payButton.addEventListener('click', async () => {
|
|
273
|
+
// Call before any await in the click handler, so the popup can open.
|
|
274
|
+
const result = await requestPayment({
|
|
275
|
+
orderId: order.id,
|
|
276
|
+
title: 'Open the secret room',
|
|
277
|
+
description: 'Access for this run',
|
|
278
|
+
amountCoins: order.amountCoins,
|
|
279
|
+
});
|
|
280
|
+
if (result.status === 'succeeded' && result.payment) {
|
|
281
|
+
await deliverOrderOnce(result.payment.orderId); // Your game's saved state.
|
|
282
|
+
}
|
|
283
|
+
if (result.status === 'pending') showPaymentPending(order.id);
|
|
284
|
+
});
|
|
285
|
+
|
|
286
|
+
// Recover an uncertain payment without asking for another charge.
|
|
287
|
+
const payment = await getPayment(order.id);
|
|
288
|
+
if (payment?.status === 'succeeded') await deliverOrderOnce(payment.orderId);
|
|
289
|
+
|
|
290
|
+
// Or reconcile all successful payments, following every nextCursor.
|
|
291
|
+
let cursor: string | undefined;
|
|
292
|
+
do {
|
|
293
|
+
const page = await getPayments({ cursor, limit: 50 });
|
|
294
|
+
for (const paid of page.payments) await deliverOrderOnce(paid.orderId);
|
|
295
|
+
cursor = page.nextCursor ?? undefined;
|
|
296
|
+
} while (cursor);
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
`loadOrCreateOrderForCurrentAction`, `deliverOrderOnce` and the UI helpers above
|
|
300
|
+
are your game code. Delivery must be idempotent by `orderId` and recorded with
|
|
301
|
+
the saved effect. A payment receipt does not create an inventory item or apply
|
|
302
|
+
an effect for you. Delivering from a success message alone loses the action if
|
|
303
|
+
the game closes after payment; reconcile from receipts on boot too.
|
|
304
|
+
|
|
305
|
+
`orderId` is 1–128 characters, cannot be exactly `.` or `..`, and belongs to
|
|
306
|
+
this player and game. Repeating
|
|
307
|
+
the same ID with the same terms returns the same payment, including a canceled
|
|
308
|
+
or expired one. Changing its terms returns `payment_conflict`. A new purchase
|
|
309
|
+
gets a new ID. `title` must be 1–80 characters after trimming; `description` is optional
|
|
310
|
+
and at most 1000 characters after trimming, and `amountCoins` is a whole number
|
|
311
|
+
from 1 to 100000, further limited by the platform's payment settings. Text is
|
|
312
|
+
plain text. The recipient and revenue split are chosen by Genex, not the game.
|
|
313
|
+
|
|
314
|
+
`requestPayment()` returns `{ status, payment?, message? }`. `succeeded` means
|
|
315
|
+
the server recorded the charge; `canceled` and `expired` are terminal server
|
|
316
|
+
outcomes. `insufficient_balance` or `failed` explain a refusal. **`pending`
|
|
317
|
+
means the result is uncertain**, including a timeout or lost response: read
|
|
318
|
+
`getPayment(orderId)` and reuse that order when retrying. A closed popup is not
|
|
319
|
+
proof of cancellation. `timeoutMs` defaults to three minutes and only limits
|
|
320
|
+
how long this call waits; it does not cancel a payment.
|
|
321
|
+
|
|
322
|
+
`getPayment()` returns a `PaymentReceipt` or `null` for a missing order; a read
|
|
323
|
+
failure throws, so never interpret it as an unpaid order. `getPayments()` lists
|
|
324
|
+
only successful payments with `{ payments, nextCursor }`. Each receipt has
|
|
325
|
+
`id`, `orderId`, `title`, `description`, `amountCoins`,
|
|
326
|
+
`priceDisplayUsdCents`, `status`, `failureCode`, `createdAt`, `paidAt` and
|
|
327
|
+
`expiresAt`. All timestamps are ISO strings; `paidAt` is null until paid.
|
|
328
|
+
|
|
329
|
+
Payments require a signed-in player in a published game. On the Genex game page
|
|
330
|
+
the platform opens a sheet outside the game frame and releases the game's
|
|
331
|
+
pointer lock. On the game's own address the SDK opens a separate platform
|
|
332
|
+
window; call directly from a click or tap. Local test mode and the native app
|
|
333
|
+
do not support payments. Older platforms without this endpoint return a
|
|
334
|
+
failure; the SDK does not silently create a catalog item instead. Existing
|
|
335
|
+
`getShop()` / `buy()` / entitlement APIs remain available for catalog games.
|
|
336
|
+
|
|
43
337
|
## Generate during play
|
|
44
338
|
|
|
45
339
|
Runtime generation requires a signed-in player in a published game and an
|