@genex-ai/embed-sdk 0.32.0 → 0.34.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
@@ -254,6 +254,139 @@ and save from `onShellClosing()`. Reading the clipboard is not available: listen
254
254
  for the `paste` event. Sign-in popups for other services, notifications and
255
255
  the tab's title are not available to a framed game.
256
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
+
337
+ ## Sell catalog items
338
+
339
+ `getShop()`, `buy()` and the entitlement calls predate 0.34.0; the store fields
340
+ below are SDK **0.34.0+**. Items come from `genex shop add` (or, made by another
341
+ creator, from `genex items add`). The game reads the catalog and never writes it
342
+ or sets a price.
343
+
344
+ ```ts
345
+ import { getShop, buy, getEntitlements, consumeEntitlement, ItemState } from '@genex-ai/embed-sdk';
346
+
347
+ // Every boot: deliver what the player owns. Skip a skuId this game does not know.
348
+ const applyOwned = async () => {
349
+ for (const owned of await getEntitlements({ excludeConsumed: true })) {
350
+ if (!knowsItem(owned.skuId)) continue;
351
+ if (owned.skuType === 'durable') {
352
+ applyItem(owned.skuId); // owned forever: apply on every boot, never consume
353
+ continue;
354
+ }
355
+ // A consumable: consume FIRST, then apply, and only if this call consumed it.
356
+ const { alreadyConsumed } = await consumeEntitlement(owned.id);
357
+ if (!alreadyConsumed) applyItem(owned.skuId);
358
+ }
359
+ };
360
+ await applyOwned();
361
+
362
+ for (const item of await getShop()) {
363
+ const card = drawCard(item.name, item.iconUrl, item.priceCoins, item.priceDisplayUsdCents);
364
+ if (item.state === ItemState.Draft) card.badge('New'); // the owner's staging build only
365
+ card.onclick = async () => {
366
+ const result = await buy({ skuId: item.id }); // first await in the click
367
+ if (result.status === 'succeeded' || result.status === 'already_owned') await applyOwned();
368
+ if (result.status === 'insufficient_balance') showNotEnoughCoin(); // nothing was charged
369
+ };
370
+ }
371
+ ```
372
+
373
+ `knowsItem`, `applyItem`, `drawCard` and `showNotEnoughCoin` are your game
374
+ code. `ShopItem` gains optional `description`, `modelUrl`, `tags`, `shared`,
375
+ `homeGame` and `state`; `Entitlement` gains optional `shared`, `iconUrl`,
376
+ `description` and `tags`. An older platform sends none of them, so read each as
377
+ possibly absent. `shared` means the author lets other games use the item, or
378
+ it reached this game through an allowance, so this game's own shareable items
379
+ are `shared` too. `homeGame` is sent for every item, this game's own included:
380
+ to tell another game's item, compare `homeGame.slug` with your game's slug (the
381
+ one you passed to `initEmbed`). The player may have bought such an item in
382
+ another game, and this game decides how it looks and what it does. Tags are
383
+ search words, never a type. Show `priceDisplayUsdCents` beside every coin
384
+ price. `buy()` resolves `already_owned` when the player already owns the item,
385
+ and `insufficient_balance` when they were short of coin at Confirm; nothing is
386
+ charged either way. An SDK before 0.34.0 reports both as `failed`. A durable is
387
+ applied on every boot and never consumed; a consumable is consumed with
388
+ `consumeEntitlement(id)` before its effect is applied, once.
389
+
257
390
  ## Generate during play
258
391
 
259
392
  Runtime generation requires a signed-in player in a published game and an
@@ -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;
@@ -638,14 +647,14 @@ async function awaitOutcome(intentId, timeoutMs) {
638
647
  }
639
648
  return { status: "expired" };
640
649
  }
641
- function openConfirmSurface(view) {
650
+ function openConfirmSurface(view, parentOrigin2) {
642
651
  const c = must();
643
652
  const w = typeof window === "undefined" ? null : window;
644
653
  if (!w) return { ok: false, reason: "no_window" };
645
654
  if (c.isNative()) return { ok: false, reason: "native_unsupported" };
646
655
  if (c.isEmbedded() && w.parent) {
647
656
  _releasePointer();
648
- for (const origin of c.dashboardOrigins) {
657
+ for (const origin of parentOrigin2 ? [parentOrigin2] : c.dashboardOrigins) {
649
658
  try {
650
659
  w.parent.postMessage({ type: "genex:commerce:confirm", v: 1, intentId: view.id }, origin);
651
660
  } catch {
@@ -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();
@@ -678,6 +688,167 @@ async function buy(opts) {
678
688
  }
679
689
  return awaitOutcome(view.id, opts.timeoutMs ?? 18e4);
680
690
  }
691
+ async function getPayment(orderId) {
692
+ const c = must();
693
+ if (c.isLocalTest()) return null;
694
+ if (!validOrderId(orderId)) throw new Error("invalid_order_id");
695
+ return readPayment(orderId, 15e3);
696
+ }
697
+ async function getPayments(opts) {
698
+ const c = must();
699
+ if (c.isLocalTest()) return { payments: [], nextCursor: null };
700
+ const qs = new URLSearchParams();
701
+ if (opts?.cursor !== void 0) qs.set("cursor", opts.cursor);
702
+ if (opts?.limit !== void 0) qs.set("limit", String(opts.limit));
703
+ const query = qs.size ? `?${qs}` : "";
704
+ const res = await fetch(`${c.apiUrl}/api/coin/payments${query}`, {
705
+ headers: authHeaders(),
706
+ signal: AbortSignal.timeout(15e3)
707
+ });
708
+ if (!res.ok) throw new Error(`genex payments failed (${res.status})`);
709
+ return await res.json();
710
+ }
711
+ function validOrderId(orderId) {
712
+ return typeof orderId === "string" && orderId.length > 0 && orderId.length <= 128 && orderId !== "." && orderId !== "..";
713
+ }
714
+ async function readPayment(orderId, timeoutMs) {
715
+ const res = await fetch(`${must().apiUrl}/api/coin/payments/orders/${encodeURIComponent(orderId)}`, {
716
+ headers: authHeaders(),
717
+ signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutMs)))
718
+ });
719
+ if (res.status === 404) {
720
+ const body = await res.json().catch(() => null);
721
+ if (body?.error === "payment_not_found") return null;
722
+ }
723
+ if (!res.ok) throw new Error(`genex payment failed (${res.status})`);
724
+ const payment = await res.json();
725
+ if (payment.orderId !== orderId) throw new Error("invalid_payment_response");
726
+ return payment;
727
+ }
728
+ function paymentOutcome(payment) {
729
+ switch (payment.status) {
730
+ case "succeeded":
731
+ case "canceled":
732
+ case "expired":
733
+ return { status: payment.status, payment };
734
+ case "failed":
735
+ return {
736
+ status: payment.failureCode === "insufficient_balance" ? "insufficient_balance" : "failed",
737
+ payment,
738
+ message: payment.failureCode ?? "payment_failed"
739
+ };
740
+ default:
741
+ return null;
742
+ }
743
+ }
744
+ async function awaitPaymentOutcome(payment, deadline) {
745
+ let delay = 400;
746
+ while (Date.now() < deadline) {
747
+ await new Promise((resolve) => setTimeout(resolve, Math.min(delay, deadline - Date.now())));
748
+ if (Date.now() >= deadline) break;
749
+ delay = Math.min(delay * 1.4, 2e3);
750
+ try {
751
+ const latest = await readPayment(payment.orderId, Math.min(15e3, deadline - Date.now()));
752
+ if (!latest || latest.id !== payment.id) continue;
753
+ payment = latest;
754
+ const result = paymentOutcome(payment);
755
+ if (result) return result;
756
+ } catch {
757
+ }
758
+ }
759
+ return { status: "pending", payment, message: "payment_timeout" };
760
+ }
761
+ async function requestPayment(opts) {
762
+ const c = must();
763
+ if (c.isLocalTest()) return { status: "failed", message: "payments are unavailable in local test mode" };
764
+ if (c.isNative()) return { status: "failed", message: "payments are not available in the app yet" };
765
+ if (typeof window === "undefined") return { status: "failed", message: "no_window" };
766
+ if (!c.getToken()) return { status: "failed", message: "no_player_session" };
767
+ const parentOrigin2 = c.getParentOrigin();
768
+ if (c.isEmbedded() && (!parentOrigin2 || !c.dashboardOrigins.includes(parentOrigin2))) {
769
+ return { status: "failed", message: "untrusted_parent" };
770
+ }
771
+ if (!validOrderId(opts.orderId)) return { status: "failed", message: "invalid_order_id" };
772
+ const title = typeof opts.title === "string" ? opts.title.trim() : "";
773
+ if (!title || title.length > 80) return { status: "failed", message: "invalid_title" };
774
+ if (opts.description !== void 0 && typeof opts.description !== "string") {
775
+ return { status: "failed", message: "invalid_description" };
776
+ }
777
+ const description = opts.description?.trim();
778
+ if (description && description.length > 1e3) return { status: "failed", message: "invalid_description" };
779
+ if (!Number.isSafeInteger(opts.amountCoins) || opts.amountCoins < 1 || opts.amountCoins > 1e5) {
780
+ return { status: "failed", message: "invalid_amount_coins" };
781
+ }
782
+ const timeoutMs = opts.timeoutMs ?? 18e4;
783
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) {
784
+ return { status: "failed", message: "invalid_timeout" };
785
+ }
786
+ const deadline = Date.now() + timeoutMs;
787
+ let popup = null;
788
+ if (!c.isEmbedded()) {
789
+ try {
790
+ popup = window.open("about:blank", "_blank", "popup,width=420,height=640");
791
+ if (popup) popup.opener = null;
792
+ } catch {
793
+ popup?.close();
794
+ return { status: "failed", message: "popup_blocked" };
795
+ }
796
+ if (!popup) return { status: "failed", message: "popup_blocked" };
797
+ }
798
+ let payment;
799
+ try {
800
+ const created = await fetch(`${c.apiUrl}/api/coin/payments`, {
801
+ method: "POST",
802
+ headers: { ...authHeaders(), "Content-Type": "application/json" },
803
+ body: JSON.stringify({
804
+ orderId: opts.orderId,
805
+ title,
806
+ amountCoins: opts.amountCoins,
807
+ ...description ? { description } : {}
808
+ }),
809
+ signal: AbortSignal.timeout(Math.max(1, Math.ceil(Math.min(15e3, deadline - Date.now()))))
810
+ });
811
+ if (!created.ok) {
812
+ popup?.close();
813
+ const body = await created.json().catch(() => ({}));
814
+ return {
815
+ status: created.status >= 500 ? "pending" : "failed",
816
+ message: body.error ?? `payment_failed_${created.status}`
817
+ };
818
+ }
819
+ const view = await created.json();
820
+ if (view.orderId !== opts.orderId || view.title !== title || view.amountCoins !== opts.amountCoins || view.description !== (description || null) || typeof view.id !== "string") {
821
+ throw new Error("invalid_payment_response");
822
+ }
823
+ const { confirmUrl, ...receipt } = view;
824
+ payment = receipt;
825
+ const result = paymentOutcome(payment);
826
+ if (result) {
827
+ popup?.close();
828
+ return result;
829
+ }
830
+ if (payment.status === "requires_confirmation") {
831
+ const url = new URL(confirmUrl);
832
+ const trustedProtocol = url.protocol === "https:" || url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
833
+ if (!trustedProtocol || !c.dashboardOrigins.includes(url.origin) || url.username || url.password || url.pathname !== `/confirm/${encodeURIComponent(payment.id)}` || url.search || url.hash) {
834
+ popup?.close();
835
+ return { status: "pending", payment, message: "invalid_confirm_url" };
836
+ }
837
+ if (popup) {
838
+ if (!popup.closed) popup.location.href = url.href;
839
+ } else {
840
+ const opened = openConfirmSurface({ id: payment.id, confirmUrl: url.href }, parentOrigin2);
841
+ if (!opened.ok) return { status: "pending", payment, message: opened.reason };
842
+ }
843
+ } else {
844
+ popup?.close();
845
+ }
846
+ } catch (error) {
847
+ popup?.close();
848
+ return { status: "pending", ...payment ? { payment } : {}, message: error instanceof Error ? error.message : "payment_unavailable" };
849
+ }
850
+ return awaitPaymentOutcome(payment, deadline);
851
+ }
681
852
 
682
853
  // src/stream.ts
683
854
  function createSseParser(onEvent) {
@@ -1497,7 +1668,7 @@ var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
1497
1668
  var ENTRY_REFERRER_MEMO = "genex:embed:entry-referrer";
1498
1669
  var ENTRY_REFERRER_NONE = "none";
1499
1670
  var PLAYER_ID_KEY = "genex:player";
1500
- var SDK_VERSION = "0.32.0";
1671
+ var SDK_VERSION = "0.34.0";
1501
1672
  var config2 = null;
1502
1673
  var state = "pending";
1503
1674
  var user = null;
@@ -1651,6 +1822,7 @@ function initEmbed(cfg2) {
1651
1822
  apiUrl: config2.apiUrl,
1652
1823
  dashboardOrigins: config2.dashboardOrigins,
1653
1824
  getToken: () => embedToken,
1825
+ getParentOrigin: () => parentOrigin,
1654
1826
  isEmbedded,
1655
1827
  isNative: inNativeMode,
1656
1828
  isLocalTest: () => localTestMode
@@ -3015,10 +3187,14 @@ export {
3015
3187
  saveFile,
3016
3188
  setFullscreen,
3017
3189
  supports,
3190
+ ItemState,
3018
3191
  getShop,
3019
3192
  getEntitlements,
3020
3193
  consumeEntitlement,
3021
3194
  buy,
3195
+ getPayment,
3196
+ getPayments,
3197
+ requestPayment,
3022
3198
  getGenerationModels,
3023
3199
  getWorkflowOfferings,
3024
3200
  getGeneration,
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. */
@@ -35,6 +51,29 @@ interface ShopItem {
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 coin; nothing was charged. Offer a way to
120
+ * get coin. 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 {
@@ -75,6 +135,44 @@ interface PurchaseResult {
75
135
  entitlementId?: string;
76
136
  message?: string;
77
137
  }
138
+ /** A server-recorded payment request, scoped to this player and game. */
139
+ interface PaymentReceipt {
140
+ id: string;
141
+ /** The game's stable order key. Reusing it never creates another charge. */
142
+ orderId: string;
143
+ title: string;
144
+ description: string | null;
145
+ amountCoins: number;
146
+ /** Frozen real-money equivalent from the server, in USD cents. */
147
+ priceDisplayUsdCents: number;
148
+ status: 'requires_confirmation' | 'processing' | 'succeeded' | 'canceled' | 'expired' | 'failed';
149
+ failureCode: string | null;
150
+ createdAt: string;
151
+ paidAt: string | null;
152
+ expiresAt: string;
153
+ }
154
+ interface PaymentOptions {
155
+ /** Persist before asking. Reuse the same order and terms when retrying. */
156
+ orderId: string;
157
+ title: string;
158
+ description?: string;
159
+ amountCoins: number;
160
+ /** How long to wait, including creating the request. Default 3 minutes. */
161
+ timeoutMs?: number;
162
+ }
163
+ /** A dynamic payment never answers `already_owned`: there is no catalog item to own. */
164
+ type PaymentStatus = Exclude<PurchaseStatus, 'already_owned'> | 'pending';
165
+ interface PaymentResult {
166
+ /** `pending` is uncertain: recover with getPayment(orderId), never charge anew. */
167
+ status: PaymentStatus;
168
+ /** Latest authoritative server receipt, when one was received. */
169
+ payment?: PaymentReceipt;
170
+ message?: string;
171
+ }
172
+ interface PaymentPage {
173
+ payments: PaymentReceipt[];
174
+ nextCursor: string | null;
175
+ }
78
176
  /**
79
177
  * The items this game sells.
80
178
  *
@@ -137,6 +235,32 @@ declare function buy(opts: {
137
235
  /** How long to wait for the player to decide. Default 3 minutes. */
138
236
  timeoutMs?: number;
139
237
  }): Promise<PurchaseResult>;
238
+ /**
239
+ * Recover a saved order after a timeout, reload or lost response.
240
+ * Returns null when this player has no such order in this game. A failed read
241
+ * throws: a network failure is not evidence that the order was never paid.
242
+ */
243
+ declare function getPayment(orderId: string): Promise<PaymentReceipt | null>;
244
+ /**
245
+ * This player's successful payments in this game, newest first.
246
+ * On boot, follow nextCursor until null and reconcile against saved delivered
247
+ * order IDs. A receipt is proof of payment, not automatic delivery of an item.
248
+ */
249
+ declare function getPayments(opts?: {
250
+ cursor?: string;
251
+ limit?: number;
252
+ }): Promise<PaymentPage>;
253
+ /**
254
+ * Ask the player to approve a dynamic Coin payment. No catalog item required.
255
+ * Call directly from a click or tap, before any await: standalone games reserve
256
+ * the platform popup synchronously. Only Genex can confirm the charge.
257
+ *
258
+ * Save orderId before calling. Repeating the same order and terms returns its
259
+ * existing receipt; changing its terms fails with payment_conflict. Deliver
260
+ * once by orderId only after succeeded. `pending` means getPayment(orderId)
261
+ * must recover the outcome; it never means a fresh order is safe to charge.
262
+ */
263
+ declare function requestPayment(opts: PaymentOptions): Promise<PaymentResult>;
140
264
 
141
265
  interface GenerateOptions {
142
266
  /**
@@ -1052,4 +1176,4 @@ declare function __resetForTests(overrides?: {
1052
1176
  platformConfirmTimeoutMs?: number;
1053
1177
  }): void;
1054
1178
 
1055
- 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 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, getShared, getShell, getShop, getSpendGrant, getUser, getWorkflowOfferings, haptic, initEmbed, isEmbedded, judge, keepAwake, listEvents, listShared, loadPlayerState, loadWorldState, on, onShellClosing, openExternal, putShared, requestSpendGrant, requestWorkflow, resumeWorkflow, saveFile, savePlayerState, saveWorldState, setFullscreen, share, stopSpendGrant, submitScore, supports, waitForAuth, waitForGeneration, waitForPlayer };
1179
+ 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, 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, 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,
@@ -19,6 +20,8 @@ import {
19
20
  getGeneration,
20
21
  getGenerationModels,
21
22
  getLeaderboard,
23
+ getPayment,
24
+ getPayments,
22
25
  getShared,
23
26
  getShell,
24
27
  getShop,
@@ -38,6 +41,7 @@ import {
38
41
  onShellClosing,
39
42
  openExternal,
40
43
  putShared,
44
+ requestPayment,
41
45
  requestSpendGrant,
42
46
  requestWorkflow,
43
47
  resumeWorkflow,
@@ -52,9 +56,10 @@ import {
52
56
  waitForAuth,
53
57
  waitForGeneration,
54
58
  waitForPlayer
55
- } from "./chunk-NBCL5P5V.js";
59
+ } from "./chunk-276FF56N.js";
56
60
  import "./chunk-QBCWKMVQ.js";
57
61
  export {
62
+ ItemState,
58
63
  __resetForTests,
59
64
  _stashTicketFromUrl,
60
65
  appendEvent,
@@ -75,6 +80,8 @@ export {
75
80
  getGeneration,
76
81
  getGenerationModels,
77
82
  getLeaderboard,
83
+ getPayment,
84
+ getPayments,
78
85
  getShared,
79
86
  getShell,
80
87
  getShop,
@@ -94,6 +101,7 @@ export {
94
101
  onShellClosing,
95
102
  openExternal,
96
103
  putShared,
104
+ requestPayment,
97
105
  requestSpendGrant,
98
106
  requestWorkflow,
99
107
  resumeWorkflow,
package/dist/sentry.js CHANGED
@@ -2,7 +2,7 @@ import {
2
2
  _stashTicketFromUrl,
3
3
  getUser,
4
4
  on
5
- } from "./chunk-NBCL5P5V.js";
5
+ } from "./chunk-276FF56N.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.32.0",
3
+ "version": "0.34.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",