@genex-ai/embed-sdk 0.33.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
@@ -334,6 +334,59 @@ do not support payments. Older platforms without this endpoint return a
334
334
  failure; the SDK does not silently create a catalog item instead. Existing
335
335
  `getShop()` / `buy()` / entitlement APIs remain available for catalog games.
336
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
+
337
390
  ## Generate during play
338
391
 
339
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;
@@ -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.34.0";
1662
1672
  var config2 = null;
1663
1673
  var state = "pending";
1664
1674
  var user = null;
@@ -3177,6 +3187,7 @@ export {
3177
3187
  saveFile,
3178
3188
  setFullscreen,
3179
3189
  supports,
3190
+ ItemState,
3180
3191
  getShop,
3181
3192
  getEntitlements,
3182
3193
  consumeEntitlement,
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 {
@@ -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;
@@ -1115,4 +1176,4 @@ declare function __resetForTests(overrides?: {
1115
1176
  platformConfirmTimeoutMs?: number;
1116
1177
  }): void;
1117
1178
 
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 };
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,
@@ -55,9 +56,10 @@ import {
55
56
  waitForAuth,
56
57
  waitForGeneration,
57
58
  waitForPlayer
58
- } from "./chunk-NI554TIV.js";
59
+ } from "./chunk-276FF56N.js";
59
60
  import "./chunk-QBCWKMVQ.js";
60
61
  export {
62
+ ItemState,
61
63
  __resetForTests,
62
64
  _stashTicketFromUrl,
63
65
  appendEvent,
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-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.33.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",