@genex-ai/embed-sdk 0.33.0 → 0.35.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
@@ -127,6 +127,24 @@ one, and a phone can also drop a backgrounded tab without telling the page:
127
127
  save as the game goes. A game cannot block the close or ask the player to
128
128
  confirm it.
129
129
 
130
+ ## Multiplayer servers
131
+
132
+ After `await waitForPlayer()`, pass these to `@genex-ai/multiplayer`. Read the credential
133
+ fresh at each join (`auth: () => getColyseusAuth()`; tokens rotate) and never log it.
134
+
135
+ - `getColyseusUrls()`: the relay servers, for `connect()` and `matchmake()`.
136
+ - `getAuthorityUrls()` (SDK **0.35.0+**): the server-authoritative room servers, for
137
+ `connectAuthority()`. Empty when the stand serves none.
138
+ - `getAuthorityRegions()`: the same servers by region (`{ region, urls }`), for `connectAuthority()`'s
139
+ `regions`: the nearest region is joined, and each region is its own matchmaking pool. Empty when the
140
+ stand names no regions, and in local test mode.
141
+
142
+ In local test mode both lists are empty and `getColyseusAuth()` is `undefined`, except for a
143
+ local authority server: a loopback page opened with `?genex_authority_url=ws://127.0.0.1:<port>`
144
+ (a plain `ws://` url on `localhost`, `127.0.0.1` or `[::1]`, nothing after the port) gets that
145
+ one url from `getAuthorityUrls()`, and `getColyseusAuth()` answers a fixed local placeholder that
146
+ no real server accepts. Any other value is ignored.
147
+
130
148
  ## Platform capabilities
131
149
 
132
150
  SDK **0.32.0+**. The browser gives a page different powers in each shell. The
@@ -254,11 +272,15 @@ and save from `onShellClosing()`. Reading the clipboard is not available: listen
254
272
  for the `paste` event. Sign-in popups for other services, notifications and
255
273
  the tab's title are not available to a framed game.
256
274
 
257
- ## Request a Coin payment
275
+ ## Request a Nex payment
258
276
 
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,
277
+ Nex is Genex's own currency: players buy it with real money and spend it in the
278
+ Genex store (the API and the SDK's fields keep its internal name, coin:
279
+ `amountCoins`, `priceCoins`). SDK **0.33.0+**. Use `requestPayment()` when an
280
+ action needs payment of an amount decided while playing: an extra turn, access
281
+ to a room, a custom upgrade. A fixed-price item is a store item instead (below).
282
+ No product registration or shop card is required. Pass
283
+ the title, optional description and Nex amount; Genex freezes those terms,
262
284
  shows its own confirmation with the real-money equivalent, and charges only
263
285
  after the player agrees. The game never confirms a charge itself.
264
286
 
@@ -334,6 +356,59 @@ do not support payments. Older platforms without this endpoint return a
334
356
  failure; the SDK does not silently create a catalog item instead. Existing
335
357
  `getShop()` / `buy()` / entitlement APIs remain available for catalog games.
336
358
 
359
+ ## Sell catalog items
360
+
361
+ `getShop()`, `buy()` and the entitlement calls predate 0.34.0; the store fields
362
+ below are SDK **0.34.0+**. Items come from `genex shop add` (or, made by another
363
+ creator, from `genex items add`). The game reads the catalog and never writes it
364
+ or sets a price.
365
+
366
+ ```ts
367
+ import { getShop, buy, getEntitlements, consumeEntitlement, ItemState } from '@genex-ai/embed-sdk';
368
+
369
+ // Every boot: deliver what the player owns. Skip a skuId this game does not know.
370
+ const applyOwned = async () => {
371
+ for (const owned of await getEntitlements({ excludeConsumed: true })) {
372
+ if (!knowsItem(owned.skuId)) continue;
373
+ if (owned.skuType === 'durable') {
374
+ applyItem(owned.skuId); // owned forever: apply on every boot, never consume
375
+ continue;
376
+ }
377
+ // A consumable: consume FIRST, then apply, and only if this call consumed it.
378
+ const { alreadyConsumed } = await consumeEntitlement(owned.id);
379
+ if (!alreadyConsumed) applyItem(owned.skuId);
380
+ }
381
+ };
382
+ await applyOwned();
383
+
384
+ for (const item of await getShop()) {
385
+ const card = drawCard(item.name, item.iconUrl, item.priceCoins, item.priceDisplayUsdCents);
386
+ if (item.state === ItemState.Draft) card.badge('New'); // the owner's staging build only
387
+ card.onclick = async () => {
388
+ const result = await buy({ skuId: item.id }); // first await in the click
389
+ if (result.status === 'succeeded' || result.status === 'already_owned') await applyOwned();
390
+ if (result.status === 'insufficient_balance') showNotEnoughNex(); // nothing was charged
391
+ };
392
+ }
393
+ ```
394
+
395
+ `knowsItem`, `applyItem`, `drawCard` and `showNotEnoughNex` are your game
396
+ code. `ShopItem` gains optional `description`, `modelUrl`, `tags`, `shared`,
397
+ `homeGame` and `state`; `Entitlement` gains optional `shared`, `iconUrl`,
398
+ `description` and `tags`. An older platform sends none of them, so read each as
399
+ possibly absent. `shared` means the author lets other games use the item, or
400
+ it reached this game through an allowance, so this game's own shareable items
401
+ are `shared` too. `homeGame` is sent for every item, this game's own included:
402
+ to tell another game's item, compare `homeGame.slug` with your game's slug (the
403
+ one you passed to `initEmbed`). The player may have bought such an item in
404
+ another game, and this game decides how it looks and what it does. Tags are
405
+ search words, never a type. Show `priceDisplayUsdCents` beside every Nex
406
+ price. `buy()` resolves `already_owned` when the player already owns the item,
407
+ and `insufficient_balance` when they were short of Nex at Confirm; nothing is
408
+ charged either way. An SDK before 0.34.0 reports both as `failed`. A durable is
409
+ applied on every boot and never consumed; a consumable is consumed with
410
+ `consumeEntitlement(id)` before its effect is applied, once.
411
+
337
412
  ## Generate during play
338
413
 
339
414
  Runtime generation requires a signed-in player in a published game and an
@@ -460,7 +535,7 @@ email is refused (`credits_unverified`), one short of credits sees
460
535
  `insufficient_credits`, and Genex may pause paid generation platform-wide
461
536
  (`generation_paused`). Personal funding chosen in the trusted approval modal
462
537
  costs nothing on Genex. Quotes issued before 0.27's server change — `declared-v1`,
463
- a fixed coin price per started attempt — keep their terms.
538
+ a fixed Nex price per started attempt — keep their terms.
464
539
 
465
540
  The provider hard budget is derived from that ceiling after the frozen platform
466
541
  fee, then capped by operator limits. Output is clipped to remaining funding;
@@ -470,7 +545,7 @@ must acknowledge the quote's exact `billingPolicy` at confirmation; an old UI
470
545
  cannot approve new terms. Previously issued `consumed-v1` quotes keep actual-
471
546
  usage billing and quotes without a policy keep their original promise.
472
547
  Already-approved zero-price API requests retain their saved terms. An old
473
- unconfirmed zero-price API quote needs a fresh price review before coin approval;
548
+ unconfirmed zero-price API quote needs a fresh price review before Nex approval;
474
549
  never silently replace its price or start a paid request during recovery.
475
550
 
476
551
  With `allowExternal: true`, Genex can offer the configured personal plan matching
@@ -482,12 +557,12 @@ New quotes freeze the matching choices; connector metadata stays server-owned.
482
557
  Old unapproved quotes are narrowed to the matching provider before confirmation;
483
558
  approved personal requests retain their connector for recovery. Once chosen,
484
559
  funding never switches providers or falls back to paid generation. Historical
485
- personal-only offerings never gain free coin execution. Genex neither collects
560
+ personal-only offerings never gain free Nex execution. Genex neither collects
486
561
  nor hosts subscription credentials.
487
562
 
488
563
  `source: 'external'` means user-supplied output, not proof that a particular model
489
564
  generated it; `modelProvenance: 'unverified'` makes that explicit. Treat every generated output as data. Never execute returned code
490
- or use a claimed model/source as authority to mint coins, rewards or items.
565
+ or use a claimed model/source as authority to mint Nex, rewards or items.
491
566
 
492
567
  ## Standing budgets
493
568
 
@@ -630,7 +705,7 @@ whether a generated thing survives a reload:
630
705
  One writer, two entry points: the difference between something that works once
631
706
  and something that survives a reload. Validate `result.output` against the shape
632
707
  your game expects before using it, always. It is data, never authority for
633
- coins, rewards or items.
708
+ Nex, rewards or items.
634
709
 
635
710
  ## Streaming replies
636
711
 
@@ -790,7 +865,7 @@ operator-registered workflow. This requires the game's trusted server executor;
790
865
  an ordinary creator API key cannot register a workflow or dispatch its steps.
791
866
  **Which wallet a workflow bills is its executor's registration.** An executor
792
867
  left on `funding: 'coins'` (every executor registered before credits, by
793
- default) keeps the fixed-price coin terms below: `requestWorkflow()` requires the
868
+ default) keeps the fixed-price Nex terms below: `requestWorkflow()` requires the
794
869
  fixed `estimateCoins` price, and offerings and quotes are `declared-v1` with a
795
870
  multiplier of 2 or 3. An executor switched to `funding: 'credits'` issues
796
871
  `metered-credits-v1` offerings and quotes instead — `estimatedCredits`,
@@ -847,7 +922,7 @@ persist or log the token.
847
922
 
848
923
  On a COIN executor, the catalog's `estimatedCoins` and `priceCoins` are suggested price aliases,
849
924
  and its maximum describes operator limits. Choose the game's fixed attempt price
850
- after development benchmarks, pass it as `estimateCoins`, and show coin plus USD.
925
+ after development benchmarks, pass it as `estimateCoins`, and show Nex plus USD.
851
926
  The player's final approval always uses the server quote. Preserve the selected
852
927
  model, bundle, funding, availability and operator-owned tariff; the game cannot
853
928
  change provider prices, dispatch costs or settlement.
@@ -873,7 +948,7 @@ All API-backed Genex offerings are paid, including `google/gemini-3.8-flash` and
873
948
  `z-ai/glm-5.3-flash`. Airena's free access to those models is game-funded through
874
949
  its own direct OpenRouter path, outside the Genex runtime API.
875
950
  Personal Claude/ChatGPT funding choices in the Genex approval modal cost
876
- **0 coins** and use the player's own account through Genex-owned
951
+ **0 Nex** and use the player's own account through Genex-owned
877
952
  MCP connectors. Claude uses `/player/mcp`; ChatGPT uses `/player/chatgpt/mcp`.
878
953
  ChatGPT connector availability depends on account and workspace policy. One
879
954
  external request may be active per player across both providers. Follow the
@@ -908,7 +983,7 @@ the subpath is disabled for browser resolution and rejects browser execution.
908
983
  an explicit positive maximum from your own credits. Development uses
909
984
  `metered-credits-v1`: actual model usage plus the Genex fee, rounded up to a
910
985
  whole credit per call, including failed usage, up to that maximum (a workflow
911
- whose executor still bills coin uses `consumed-v1` on your coin wallet).
986
+ whose executor still bills Nex uses `consumed-v1` on your Nex wallet).
912
987
  Gemini/GLM models are paid too. Actual zero cost is free; unknown expense
913
988
  remains held. No personal or paid fallback occurs.
914
989
 
@@ -961,7 +1036,7 @@ replaces it — check it before a benchmark, not after.
961
1036
 
962
1037
  For a registered workflow, call `developmentRequestWorkflow({ apiUrl,
963
1038
  creatorToken, projectId, workflowId, maxCredits, request: { offeringId, input,
964
- idempotencyKey? } })` (on a coin executor the same number is its coin cap). It returns the accepted, claimed workflow immediately so
1039
+ idempotencyKey? } })` (on a coin executor the same number is its Nex cap). It returns the accepted, claimed workflow immediately so
965
1040
  your trusted executor can enqueue it. After enqueueing, call
966
1041
  `waitForDevelopmentGeneration(config, id, timeoutMs?)`. Both generic and workflow
967
1042
  benchmarks are recoverable with `getDevelopmentGeneration(config, id)` and
@@ -572,6 +572,12 @@ function _resetPlatform(overrides) {
572
572
  }
573
573
 
574
574
  // src/commerce.ts
575
+ var ItemState = {
576
+ Draft: "draft",
577
+ OnSale: "on_sale",
578
+ OffSale: "off_sale",
579
+ TakenDown: "taken_down"
580
+ };
575
581
  var cfg = null;
576
582
  function _initCommerce(c) {
577
583
  cfg = c;
@@ -631,6 +637,9 @@ async function awaitOutcome(intentId, timeoutMs) {
631
637
  case "expired":
632
638
  return { status: "expired" };
633
639
  case "failed":
640
+ if (view.failureCode === "already_owned" || view.failureCode === "insufficient_balance") {
641
+ return { status: view.failureCode, message: view.failureCode };
642
+ }
634
643
  return { status: "failed", message: "the purchase could not be completed" };
635
644
  default:
636
645
  break;
@@ -668,6 +677,7 @@ async function buy(opts) {
668
677
  });
669
678
  if (!created.ok) {
670
679
  const body = await created.json().catch(() => ({}));
680
+ if (body.error === "already_owned") return { status: "already_owned", message: body.error };
671
681
  return { status: "failed", message: body.error ?? `intent failed (${created.status})` };
672
682
  }
673
683
  const view = await created.json();
@@ -1658,7 +1668,7 @@ var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
1658
1668
  var ENTRY_REFERRER_MEMO = "genex:embed:entry-referrer";
1659
1669
  var ENTRY_REFERRER_NONE = "none";
1660
1670
  var PLAYER_ID_KEY = "genex:player";
1661
- var SDK_VERSION = "0.33.0";
1671
+ var SDK_VERSION = "0.35.0";
1662
1672
  var config2 = null;
1663
1673
  var state = "pending";
1664
1674
  var user = null;
@@ -1670,6 +1680,9 @@ var heartbeatTimer;
1670
1680
  var nativeBootAt = 0;
1671
1681
  var embedToken;
1672
1682
  var colyseusUrls;
1683
+ var authorityUrls;
1684
+ var authorityRegions;
1685
+ var localAuthority = false;
1673
1686
  var parentOrigin = null;
1674
1687
  var shellCaps = [];
1675
1688
  var initialized = false;
@@ -1886,11 +1899,18 @@ function getEmbedToken() {
1886
1899
  return embedToken;
1887
1900
  }
1888
1901
  function getColyseusAuth() {
1902
+ if (localAuthority) return { embedToken: LOCAL_AUTHORITY_TOKEN };
1889
1903
  return embedToken ? { embedToken } : void 0;
1890
1904
  }
1891
1905
  function getColyseusUrls() {
1892
1906
  return colyseusUrls ?? [];
1893
1907
  }
1908
+ function getAuthorityUrls() {
1909
+ return urlList(authorityUrls) ?? [];
1910
+ }
1911
+ function getAuthorityRegions() {
1912
+ return regionList(authorityRegions);
1913
+ }
1894
1914
  function waitForAuth() {
1895
1915
  if (state === "authenticated" && user) return Promise.resolve({ user });
1896
1916
  if (state === "blocked") return Promise.reject(new Error("genex embed auth: blocked"));
@@ -2570,7 +2590,7 @@ async function redeemTicket(ticket) {
2570
2590
  if (epoch !== identityEpoch) return;
2571
2591
  embedToken = body.embedToken;
2572
2592
  user = body.user;
2573
- colyseusUrls = body.colyseus?.urls;
2593
+ adoptColyseus(body.colyseus);
2574
2594
  state = "authenticated";
2575
2595
  if (handshakeTimer !== void 0) clearTimeout(handshakeTimer);
2576
2596
  handshakeTimer = void 0;
@@ -2624,7 +2644,7 @@ async function requestGuestSession() {
2624
2644
  if (epoch !== identityEpoch) return;
2625
2645
  embedToken = body.embedToken;
2626
2646
  user = body.user;
2627
- colyseusUrls = body.colyseus?.urls;
2647
+ adoptColyseus(body.colyseus);
2628
2648
  enterGuest();
2629
2649
  } catch (error) {
2630
2650
  if (epoch !== identityEpoch) return;
@@ -2660,11 +2680,47 @@ function enterGuest() {
2660
2680
  function isLoopbackLocation(w) {
2661
2681
  try {
2662
2682
  const u = new URL(w.location.origin);
2663
- return u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]");
2683
+ return u.protocol === "http:" && LOOPBACK_HOSTNAMES.has(u.hostname);
2664
2684
  } catch {
2665
2685
  return false;
2666
2686
  }
2667
2687
  }
2688
+ var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
2689
+ var AUTHORITY_URL_PARAM = "genex_authority_url";
2690
+ var LOCAL_AUTHORITY_TOKEN = "local:test";
2691
+ var MAX_AUTHORITY_URL_CHARS = 64;
2692
+ function loopbackAuthorityUrl(raw) {
2693
+ if (!raw || raw.length > MAX_AUTHORITY_URL_CHARS) return null;
2694
+ let u;
2695
+ try {
2696
+ u = new URL(raw);
2697
+ } catch {
2698
+ return null;
2699
+ }
2700
+ const bare = !u.username && !u.password && u.pathname === "/" && !u.search && !u.hash;
2701
+ if (u.protocol !== "ws:" || !LOOPBACK_HOSTNAMES.has(u.hostname) || !bare) return null;
2702
+ return `ws://${u.host}`;
2703
+ }
2704
+ function adoptColyseus(block) {
2705
+ colyseusUrls = block?.urls;
2706
+ authorityUrls = block?.authorityUrls;
2707
+ authorityRegions = block?.authorityRegions;
2708
+ }
2709
+ function urlList(value) {
2710
+ if (!Array.isArray(value)) return void 0;
2711
+ return value.filter((url) => typeof url === "string" && url.length > 0);
2712
+ }
2713
+ function regionList(value) {
2714
+ if (!Array.isArray(value)) return [];
2715
+ const out = [];
2716
+ for (const entry of value) {
2717
+ if (entry === null || typeof entry !== "object") continue;
2718
+ const { region, urls } = entry;
2719
+ const list = urlList(urls) ?? [];
2720
+ if (typeof region === "string" && region.length > 0 && list.length > 0) out.push({ region, urls: list });
2721
+ }
2722
+ return out;
2723
+ }
2668
2724
  function wantsLocalTestMode(w, latch = true) {
2669
2725
  if (isEmbedded()) return false;
2670
2726
  if (detectNativeEntry(w)) return false;
@@ -2689,6 +2745,7 @@ function hasGenexFragment(w) {
2689
2745
  function enterLocalTestMode(w) {
2690
2746
  localTestMode = true;
2691
2747
  readFragment(w);
2748
+ acceptLocalAuthorityUrl(w);
2692
2749
  const localUser = { id: "local:test", name: "Local Tester" };
2693
2750
  user = localUser;
2694
2751
  state = "guest";
@@ -2702,6 +2759,19 @@ function enterLocalTestMode(w) {
2702
2759
  for (const waiter of playerWaiters.splice(0)) waiter.resolve({ user: localUser, guest: true });
2703
2760
  emit("guest", { user: localUser });
2704
2761
  }
2762
+ function acceptLocalAuthorityUrl(w) {
2763
+ if (!isLoopbackLocation(w)) return;
2764
+ let raw = null;
2765
+ try {
2766
+ raw = new URLSearchParams(w.location.search).get(AUTHORITY_URL_PARAM);
2767
+ } catch {
2768
+ return;
2769
+ }
2770
+ const url = loopbackAuthorityUrl(raw);
2771
+ if (!url) return;
2772
+ authorityUrls = [url];
2773
+ localAuthority = true;
2774
+ }
2705
2775
  async function handleRedeemFailure() {
2706
2776
  const w = win2();
2707
2777
  if (handshakeTimer !== void 0) clearTimeout(handshakeTimer);
@@ -3117,7 +3187,8 @@ function __resetForTests(overrides) {
3117
3187
  user = null;
3118
3188
  localTestMode = false;
3119
3189
  embedToken = void 0;
3120
- colyseusUrls = void 0;
3190
+ adoptColyseus(void 0);
3191
+ localAuthority = false;
3121
3192
  parentOrigin = null;
3122
3193
  shellCaps = [];
3123
3194
  initialized = false;
@@ -3177,6 +3248,7 @@ export {
3177
3248
  saveFile,
3178
3249
  setFullscreen,
3179
3250
  supports,
3251
+ ItemState,
3180
3252
  getShop,
3181
3253
  getEntitlements,
3182
3254
  consumeEntitlement,
@@ -3208,6 +3280,8 @@ export {
3208
3280
  getEmbedToken,
3209
3281
  getColyseusAuth,
3210
3282
  getColyseusUrls,
3283
+ getAuthorityUrls,
3284
+ getAuthorityRegions,
3211
3285
  waitForAuth,
3212
3286
  waitForPlayer,
3213
3287
  on,
@@ -4,7 +4,7 @@ import { R as RuntimeJudgeQuestion, a as RuntimeWorkflowInput, b as RuntimeGener
4
4
  * Server-only benchmarks spend the authenticated creator's OWN CREDITS
5
5
  * (`metered-credits-v1` since SDK 0.27: the real model cost plus the Genex fee,
6
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`).
7
+ * still bills Nex, their own Nex wallet (`consumed-v1`).
8
8
  */
9
9
 
10
10
  interface DevelopmentGenerationConfig {
package/dist/index.d.ts CHANGED
@@ -18,7 +18,23 @@ export { j as RuntimeBillingPolicy, k as RuntimeCurrency, l as RuntimeExternalPr
18
18
  declare const PLATFORM_ERRORS: readonly ["unsupported", "needs_gesture", "dismissed", "busy", "rate_limited", "invalid_request", "too_large", "timeout"];
19
19
  type PlatformError = (typeof PLATFORM_ERRORS)[number];
20
20
 
21
- /** A thing the game sells. Resolved server-side; the game never sets a price. */
21
+ /**
22
+ * Where an item stands for sale — the wire values of {@link ShopItem.state}.
23
+ * A game sees `draft` only on its staging build, for its owner: badge it "New".
24
+ */
25
+ declare const ItemState: {
26
+ readonly Draft: "draft";
27
+ readonly OnSale: "on_sale";
28
+ readonly OffSale: "off_sale";
29
+ readonly TakenDown: "taken_down";
30
+ };
31
+ type ItemState = (typeof ItemState)[keyof typeof ItemState];
32
+ /**
33
+ * A thing the game sells. Resolved server-side; the game never sets a price.
34
+ *
35
+ * Every field after `priceDisplayUsdCents` is optional (0.34.0, the item
36
+ * store): an older platform does not send them, so read each as possibly absent.
37
+ */
22
38
  interface ShopItem {
23
39
  id: string;
24
40
  /** 'consumable' — spent on use. 'durable' — owned permanently. */
@@ -29,12 +45,35 @@ interface ShopItem {
29
45
  /**
30
46
  * The real-money equivalent, in USD cents, from the server.
31
47
  *
32
- * Show it next to the coin price. It is not decoration: a currency price
48
+ * Show it next to the Nex price (`priceCoins`). It is not decoration: a currency price
33
49
  * without its real-world value is the practice consumer regulators single
34
50
  * out first, and the platform sends this so a game never has to compute it —
35
51
  * or be tempted to omit it.
36
52
  */
37
53
  priceDisplayUsdCents: number;
54
+ description?: string | null;
55
+ /** A GLB of the item, when its author made one. */
56
+ modelUrl?: string | null;
57
+ /** Free-text search words. Never a type or a slot: the game decides what an item does. */
58
+ tags?: string[];
59
+ /**
60
+ * Its author lets other games use it, or it reached this game through an
61
+ * allowance — so it is true for this game's OWN shareable items too. It does
62
+ * not mean "from another game": compare {@link ShopItem.homeGame}'s `slug`
63
+ * with this game's slug (the one passed to initEmbed) for that. Another
64
+ * game's item looks and works however this game decides.
65
+ */
66
+ shared?: boolean;
67
+ /**
68
+ * The game the item was made for, sent for every item, this game's own
69
+ * included (null for an item with no home game). `homeGame.slug` differs
70
+ * from this game's slug exactly when the item is another game's.
71
+ */
72
+ homeGame?: {
73
+ slug: string;
74
+ title: string;
75
+ } | null;
76
+ state?: ItemState;
38
77
  }
39
78
  interface Entitlement {
40
79
  id: string;
@@ -57,6 +96,17 @@ interface Entitlement {
57
96
  quantity: number;
58
97
  consumed: boolean;
59
98
  createdAt: string;
99
+ /**
100
+ * Its author lets other games use it, or it reached this game through an
101
+ * allowance; it may have been bought in another game. True for this game's
102
+ * own shareable items too, so it does not say whose item it is: match
103
+ * `skuId` against getShop() and compare that item's `homeGame.slug` with
104
+ * this game's slug.
105
+ */
106
+ shared?: boolean;
107
+ iconUrl?: string | null;
108
+ description?: string | null;
109
+ tags?: string[];
60
110
  }
61
111
  type PurchaseStatus =
62
112
  /** Settled. The item is owned; consume it, then apply the effect. */
@@ -65,8 +115,18 @@ type PurchaseStatus =
65
115
  | 'canceled'
66
116
  /** The confirmation was never completed in time. */
67
117
  | 'expired'
68
- /** The player does not have enough coin. */
118
+ /**
119
+ * The player does not have enough Nex; nothing was charged. Offer a way to
120
+ * get Nex. An SDK before 0.34.0 reports it from buy() as `failed`.
121
+ */
69
122
  | 'insufficient_balance'
123
+ /**
124
+ * The player already owns this item — a durable, or a free item they claimed
125
+ * (0.34.0), including one they came to own while the sheet was open. Nothing
126
+ * was charged; deliver it from getEntitlements(). An older SDK reports it as
127
+ * `failed`.
128
+ */
129
+ | 'already_owned'
70
130
  /** Something went wrong. `message` says what, for a log — not for the player. */
71
131
  | 'failed';
72
132
  interface PurchaseResult {
@@ -100,7 +160,8 @@ interface PaymentOptions {
100
160
  /** How long to wait, including creating the request. Default 3 minutes. */
101
161
  timeoutMs?: number;
102
162
  }
103
- type PaymentStatus = PurchaseStatus | 'pending';
163
+ /** A dynamic payment never answers `already_owned`: there is no catalog item to own. */
164
+ type PaymentStatus = Exclude<PurchaseStatus, 'already_owned'> | 'pending';
104
165
  interface PaymentResult {
105
166
  /** `pending` is uncertain: recover with getPayment(orderId), never charge anew. */
106
167
  status: PaymentStatus;
@@ -190,7 +251,8 @@ declare function getPayments(opts?: {
190
251
  limit?: number;
191
252
  }): Promise<PaymentPage>;
192
253
  /**
193
- * Ask the player to approve a dynamic Coin payment. No catalog item required.
254
+ * Ask the player to approve a dynamic Nex payment, for an amount decided in
255
+ * play. No catalog item required.
194
256
  * Call directly from a click or tap, before any await: standalone games reserve
195
257
  * the platform popup synchronously. Only Genex can confirm the charge.
196
258
  *
@@ -257,8 +319,8 @@ interface RuntimeGenerationResult extends RuntimeGenerationBilling {
257
319
  }
258
320
  interface RequestWorkflowOptions {
259
321
  /**
260
- * The operation's ceiling. A workflow whose executor bills coin (the default
261
- * for every executor registered before credits) reads it as its fixed coin
322
+ * The operation's ceiling. A workflow whose executor bills Nex (the default
323
+ * for every executor registered before credits) reads it as its fixed Nex
262
324
  * price of a started attempt; one whose executor bills credits reads it as the
263
325
  * credit ceiling of a request billed as used. Pass this or `maxCredits`.
264
326
  */
@@ -934,6 +996,21 @@ declare function getColyseusAuth(): {
934
996
  /** The relay URLs for this session (server-owned; a regional list when configured). Pass to
935
997
  * connect()/matchmake() as `urls` so the SDK joins the lowest-latency one; single-url fallback. */
936
998
  declare function getColyseusUrls(): string[];
999
+ /** The server-authoritative room servers for this session (multiplayer PROTOCOL.md §17; separate from
1000
+ * the relay urls, server-owned). Pass to `connectAuthority()` as `urls`. Empty when the stand serves
1001
+ * none. In local test mode it is the loopback `genex_authority_url` the page was opened with (a
1002
+ * `ws://` url on `localhost`, `127.0.0.1` or `[::1]`, on a loopback page), and empty otherwise. */
1003
+ declare function getAuthorityUrls(): string[];
1004
+ /** One region of the server-authoritative cluster: its name and its servers' urls. */
1005
+ type AuthorityRegion = {
1006
+ region: string;
1007
+ urls: string[];
1008
+ };
1009
+ /** The server-authoritative room servers by region (multiplayer PROTOCOL.md §17.1 *Regions*, server-owned).
1010
+ * Pass to `connectAuthority()` as `regions` beside `urls`: the nearest region is joined, and each region
1011
+ * is its own matchmaking pool. Empty when the stand names no regions, and in local test mode; `urls`
1012
+ * alone are then used. Fresh copies: editing them changes nothing. */
1013
+ declare function getAuthorityRegions(): AuthorityRegion[];
937
1014
  /**
938
1015
  * Resolves with the signed-in ACCOUNT once authenticated; rejects if the
939
1016
  * session ends up blocked. THE gate for /state saves and any account-bound
@@ -1115,4 +1192,4 @@ declare function __resetForTests(overrides?: {
1115
1192
  platformConfirmTimeoutMs?: number;
1116
1193
  }): void;
1117
1194
 
1118
- export { type AppendEventResult, type AuthState, type DeleteSharedResult, type EmbedConfig, type EmbedEntry, type EmbedEvent, type EmbedShell, type EmbedUser, type Entitlement, type GenerateOptions, type GenerateStreamOptions, type HapticKind, type JudgeOptions, type JudgeResult, type Leaderboard, type LeaderboardEntry, type PaymentOptions, type PaymentPage, type PaymentReceipt, type PaymentResult, type PaymentStatus, type PlatformError, type PlatformFeature, type PlatformOutcome, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type PutSharedResult, type RequestWorkflowOptions, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationModels, type RuntimeGenerationResult, RuntimeGenerationView, RuntimeGrantView, RuntimeJudgeAnswer, RuntimeJudgeQuestion, RuntimeJudgmentView, type RuntimeWorkflowAuthorization, RuntimeWorkflowInput, RuntimeWorkflowOfferings, type SaveStateResult, type ShareOptions, type ShareResult, type SharedEventPage, type SharedEventRecord, type SharedObject, type SharedObjectInfo, type SharedPage, type ShopItem, type SpendGrantDisclosure, type SpendGrantOptions, type SpendGrantResult, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, appendEvent, buy, consumeEntitlement, copyText, deleteShared, generate, generateStream, generationErrorMessage, getActiveSpendGrant, getAuthState, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getEntry, getGeneration, getGenerationModels, getLeaderboard, getPayment, getPayments, getShared, getShell, getShop, getSpendGrant, getUser, getWorkflowOfferings, haptic, initEmbed, isEmbedded, judge, keepAwake, listEvents, listShared, loadPlayerState, loadWorldState, on, onShellClosing, openExternal, putShared, requestPayment, requestSpendGrant, requestWorkflow, resumeWorkflow, saveFile, savePlayerState, saveWorldState, setFullscreen, share, stopSpendGrant, submitScore, supports, waitForAuth, waitForGeneration, waitForPlayer };
1195
+ export { type AppendEventResult, type AuthState, type AuthorityRegion, type DeleteSharedResult, type EmbedConfig, type EmbedEntry, type EmbedEvent, type EmbedShell, type EmbedUser, type Entitlement, type GenerateOptions, type GenerateStreamOptions, type HapticKind, ItemState, type JudgeOptions, type JudgeResult, type Leaderboard, type LeaderboardEntry, type PaymentOptions, type PaymentPage, type PaymentReceipt, type PaymentResult, type PaymentStatus, type PlatformError, type PlatformFeature, type PlatformOutcome, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type PutSharedResult, type RequestWorkflowOptions, RuntimeGenerationBilling, RuntimeGenerationFunding, RuntimeGenerationModels, type RuntimeGenerationResult, RuntimeGenerationView, RuntimeGrantView, RuntimeJudgeAnswer, RuntimeJudgeQuestion, RuntimeJudgmentView, type RuntimeWorkflowAuthorization, RuntimeWorkflowInput, RuntimeWorkflowOfferings, type SaveStateResult, type ShareOptions, type ShareResult, type SharedEventPage, type SharedEventRecord, type SharedObject, type SharedObjectInfo, type SharedPage, type ShopItem, type SpendGrantDisclosure, type SpendGrantOptions, type SpendGrantResult, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, appendEvent, buy, consumeEntitlement, copyText, deleteShared, generate, generateStream, generationErrorMessage, getActiveSpendGrant, getAuthState, getAuthorityRegions, getAuthorityUrls, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getEntry, getGeneration, getGenerationModels, getLeaderboard, getPayment, getPayments, getShared, getShell, getShop, getSpendGrant, getUser, getWorkflowOfferings, haptic, initEmbed, isEmbedded, judge, keepAwake, listEvents, listShared, loadPlayerState, loadWorldState, on, onShellClosing, openExternal, putShared, requestPayment, requestSpendGrant, requestWorkflow, resumeWorkflow, saveFile, savePlayerState, saveWorldState, setFullscreen, share, stopSpendGrant, submitScore, supports, waitForAuth, waitForGeneration, waitForPlayer };
package/dist/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import {
2
+ ItemState,
2
3
  __resetForTests,
3
4
  _stashTicketFromUrl,
4
5
  appendEvent,
@@ -11,6 +12,8 @@ import {
11
12
  generationErrorMessage,
12
13
  getActiveSpendGrant,
13
14
  getAuthState,
15
+ getAuthorityRegions,
16
+ getAuthorityUrls,
14
17
  getColyseusAuth,
15
18
  getColyseusUrls,
16
19
  getEmbedToken,
@@ -55,9 +58,10 @@ import {
55
58
  waitForAuth,
56
59
  waitForGeneration,
57
60
  waitForPlayer
58
- } from "./chunk-NI554TIV.js";
61
+ } from "./chunk-KEW6LYT2.js";
59
62
  import "./chunk-QBCWKMVQ.js";
60
63
  export {
64
+ ItemState,
61
65
  __resetForTests,
62
66
  _stashTicketFromUrl,
63
67
  appendEvent,
@@ -70,6 +74,8 @@ export {
70
74
  generationErrorMessage,
71
75
  getActiveSpendGrant,
72
76
  getAuthState,
77
+ getAuthorityRegions,
78
+ getAuthorityUrls,
73
79
  getColyseusAuth,
74
80
  getColyseusUrls,
75
81
  getEmbedToken,
package/dist/sentry.js CHANGED
@@ -2,7 +2,7 @@ import {
2
2
  _stashTicketFromUrl,
3
3
  getUser,
4
4
  on
5
- } from "./chunk-NI554TIV.js";
5
+ } from "./chunk-KEW6LYT2.js";
6
6
  import "./chunk-QBCWKMVQ.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.33.0",
3
+ "version": "0.35.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, soft-trust leaderboards, and shared collections and event streams.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",