glitch-javascript-sdk 4.0.0 → 4.0.1

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/dist/index.d.ts CHANGED
@@ -12320,6 +12320,17 @@ interface MicrotransactionProduct extends Omit<MicrotransactionProductInput, 'co
12320
12320
  created_at: string;
12321
12321
  updated_at: string;
12322
12322
  }
12323
+ /** Read-only collection facts, not tax exemption or a determination of tax owed. */
12324
+ interface MicrotransactionTaxCollection {
12325
+ /** Configured intent stays automatic during a known pending-setup fallback. */
12326
+ requested_mode: 'automatic' | 'disabled';
12327
+ /** Pending setup may disable collection for a NEW order; unknown facts are null and block new automatic checkout. */
12328
+ effective_mode: 'automatic' | 'disabled' | null;
12329
+ status: string;
12330
+ missing_fields: string[];
12331
+ fallback_reason: 'stripe_tax_setup_incomplete' | null;
12332
+ warnings: string[];
12333
+ }
12323
12334
  interface MicrotransactionProvider {
12324
12335
  provider: MicrotransactionProviderName;
12325
12336
  environment: MicrotransactionEnvironment;
@@ -12340,6 +12351,7 @@ interface MicrotransactionProvider {
12340
12351
  charges_enabled: boolean;
12341
12352
  payouts_enabled: boolean;
12342
12353
  requirements_due: string[];
12354
+ merchant_name?: string | null;
12343
12355
  } | null;
12344
12356
  /** The game's payout target. Do not substitute the platform processing account's payouts_enabled. */
12345
12357
  payout_account: {
@@ -12356,6 +12368,10 @@ interface MicrotransactionProvider {
12356
12368
  status: string;
12357
12369
  missing_fields: string[];
12358
12370
  };
12371
+ /** Current route facts only. Never use these to reinterpret an existing order's frozen decision. */
12372
+ tax_collection?: MicrotransactionTaxCollection | null;
12373
+ /** Non-blocking collection warnings, separate from reasons and payout_account availability. */
12374
+ warnings?: string[];
12359
12375
  reasons: string[];
12360
12376
  checked_at: string | null;
12361
12377
  revision?: number;
@@ -12367,6 +12383,7 @@ interface MicrotransactionProviderSku {
12367
12383
  amount_minor: number;
12368
12384
  }
12369
12385
  interface MicrotransactionProviderConfiguration {
12386
+ /** Requested configuration. Explicit disabled is sandbox-only; pending-setup fallback does not change live configuration to disabled. */
12370
12387
  tax_mode: 'automatic' | 'disabled';
12371
12388
  /** Stripe tax code txcd_ followed by exactly eight digits. */
12372
12389
  tax_code: string | null;
@@ -12467,7 +12484,12 @@ interface MicrotransactionRefundInput extends MicrotransactionLegacyConfirmation
12467
12484
  }
12468
12485
  interface MicrotransactionReadiness {
12469
12486
  status: 'disabled' | 'draft' | 'sandbox' | 'ready' | 'live' | 'degraded' | 'suspended';
12487
+ /** Configuration readiness only; not proof of payment, delivery, claim or browser 3DS. */
12470
12488
  ready: boolean;
12489
+ /** Optional on older backends; retains the same configuration meaning as ready. */
12490
+ configuration_ready?: boolean;
12491
+ /** Stored sandbox paid + fulfilled + claimed evidence. Absent means unknown; not browser/3DS certification. */
12492
+ integration_verified?: boolean;
12471
12493
  blockers: string[];
12472
12494
  providers: MicrotransactionProvider[];
12473
12495
  commission_basis_points: 1200;
@@ -12568,6 +12590,8 @@ interface MicrotransactionOrder {
12568
12590
  paid_at: string | null;
12569
12591
  refunded_minor: number;
12570
12592
  items: MicrotransactionGrant[];
12593
+ /** Frozen decision, also returned inside checkout/session.order. Null/absent for legacy orders; never infer from current provider facts. Warnings do not imply zero tax owed. */
12594
+ tax_collection?: MicrotransactionTaxCollection | null;
12571
12595
  entitlements?: MicrotransactionEntitlement[];
12572
12596
  }
12573
12597
  interface MicrotransactionOrderDetail extends MicrotransactionOrder {
@@ -12773,8 +12797,9 @@ interface MicrotransactionCapabilities {
12773
12797
  [key: string]: unknown;
12774
12798
  }
12775
12799
  /**
12776
- * Provider-neutral, title-scoped commerce. Configure with user JWT; purchases
12777
- * use a recoverable user account and limited checkout capability. Install/title
12800
+ * Provider-neutral, title-scoped commerce. Guest games configure only the API
12801
+ * base URL, never global account/admin auth. Hosted account pages use their own
12802
+ * user JWT and limited checkout capability; playerToken overrides auth per request. Install/title
12778
12803
  * tokens cannot authorize money, ownership, refunds, or catalog changes.
12779
12804
  *
12780
12805
  * Each result preserves payment versus fulfillment versus settlement. Redirects
@@ -12866,13 +12891,13 @@ declare class Microtransactions {
12866
12891
  static refundOrder(title_id: string, order_id: string, data: MicrotransactionRefundInput, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionRefund>>;
12867
12892
  /** Replay the same immutable event. Receiver must deduplicate event_id. This cannot mint goods. */
12868
12893
  static replayDelivery(title_id: string, delivery_id: string, data?: MicrotransactionLegacyConfirmation, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionDeliveryResult>>;
12869
- /** Public eligible catalog. Sandbox is restricted by backend environment/admin policy. */
12894
+ /** Guest catalog on the exact approved game Origin. Sandbox requires enabled sandbox settings; the backend enforces environment policy. */
12870
12895
  static catalog(title_id: string, params?: MicrotransactionCatalogFilter, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionCatalog>>;
12871
12896
  /** User-authenticated quote. Clients select product/quantity, never monetary values or seller accounts. */
12872
12897
  static createQuote(title_id: string, data: MicrotransactionPurchaseInput, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionQuote>>;
12873
- /** Anonymous-safe opening step only. The hosted UI creates/logs into an account before payment. */
12898
+ /** Guest opening only: browser Origin must equal approved return_origin. Inherits configured global auth; use an isolated credential-free game context. Hosted UI authenticates before payment. */
12874
12899
  static createCheckoutSession(title_id: string, data: MicrotransactionCheckoutSessionInput, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionCreatedCheckoutSession>>;
12875
- /** Anonymous-safe inventory recovery. Opens an in-game hosted sign-in overlay, never creates a charge or requires the game's account JWT. */
12900
+ /** Guest entry to hosted recovery, not inventory access. Exact approved Origin/return_origin required. Owning-account bind remains mandatory, including when commerce is off. Never install an account JWT in the game. */
12876
12901
  static createRestoreSession(title_id: string, data: {
12877
12902
  return_origin: string;
12878
12903
  nonce: string;
@@ -13574,4 +13599,4 @@ declare class Glitch {
13574
13599
  };
13575
13600
  }
13576
13601
 
13577
- export { type FestivalApplicationInput, type FestivalApplicationState, type FestivalConversation, type FestivalMediaUpload, type FestivalNetworkingFilters, type FestivalNetworkingProfile, type FestivalNetworkingResponse, type FestivalNetworkingSettings, type FestivalPost, type FestivalPostInput, type FestivalPostKind, type FestivalPostState, type FestivalPreferences, type FestivalReportInput, type FestivalRequestOptions, type FestivalWorkType, type MicrotransactionAbility, type MicrotransactionBranding, type MicrotransactionBridge, type MicrotransactionBridgeOptions, type MicrotransactionCapabilities, type MicrotransactionCatalog, type MicrotransactionCatalogFilter, type MicrotransactionCheckoutInput, type MicrotransactionCheckoutResult, type MicrotransactionCheckoutSession, type MicrotransactionCheckoutSessionInput, type MicrotransactionConsumeInput, type MicrotransactionCreatedCheckoutSession, type MicrotransactionCurrency, type MicrotransactionDelivery, type MicrotransactionDeliveryListFilters, type MicrotransactionDeliveryResult, type MicrotransactionDeliverySettings, type MicrotransactionDeliverySettingsInput, type MicrotransactionDeliveryStatus, type MicrotransactionEarnings, type MicrotransactionEntitlement, type MicrotransactionEnvironment, type MicrotransactionEnvironmentFilter, type MicrotransactionError, type MicrotransactionErrorCode, type MicrotransactionFramePolicy, type MicrotransactionFulfillmentStatus, type MicrotransactionGrant, type MicrotransactionGrantUsage, type MicrotransactionGrantUsageStatus, type MicrotransactionHandoff, type MicrotransactionHandoffClaim, type MicrotransactionHandoffClaimInput, type MicrotransactionLegacyConfirmation, type MicrotransactionManagementListFilters, type MicrotransactionMedia, type MicrotransactionMyPurchases, type MicrotransactionMyPurchasesFilters, type MicrotransactionOperation, type MicrotransactionOperationCapability, type MicrotransactionOrder, type MicrotransactionOrderDetail, type MicrotransactionOrderListFilters, type MicrotransactionOverlay, type MicrotransactionOverlayOptions, type MicrotransactionPaymentStatus, type MicrotransactionPayout, type MicrotransactionPayoutListFilters, type MicrotransactionPayoutStatus, type MicrotransactionPlayerPurchase, type MicrotransactionPrice, type MicrotransactionProduct, type MicrotransactionProductInput, type MicrotransactionProductListFilters, type MicrotransactionProductStatus, type MicrotransactionProductType, type MicrotransactionProvider, type MicrotransactionProviderConfiguration, type MicrotransactionProviderInput, type MicrotransactionProviderName, type MicrotransactionProviderOnboarding, type MicrotransactionProviderOnboardingInput, type MicrotransactionProviderSku, type MicrotransactionPurchaseInput, type MicrotransactionPurchaseMessage, type MicrotransactionPurchasePagination, type MicrotransactionQuote, type MicrotransactionReadiness, type MicrotransactionReadyMessage, type MicrotransactionRefund, type MicrotransactionRefundInput, type MicrotransactionRefundListFilters, type MicrotransactionRefundRecord, type MicrotransactionRefundRequest, type MicrotransactionRefundStatus, type MicrotransactionRelatedListFilters, type MicrotransactionRequestOptions, type MicrotransactionResponse, type MicrotransactionRestoreBridgeOptions, type MicrotransactionSessionOptions, type MicrotransactionSettings, type MicrotransactionSettingsInput, type MicrotransactionVerifiedSession, createMicrotransactionBridge, createMicrotransactionNonce, createMicrotransactionRestoreBridge, Glitch as default, openMicrotransactionOverlay, openMicrotransactionRestoreOverlay };
13602
+ export { type FestivalApplicationInput, type FestivalApplicationState, type FestivalConversation, type FestivalMediaUpload, type FestivalNetworkingFilters, type FestivalNetworkingProfile, type FestivalNetworkingResponse, type FestivalNetworkingSettings, type FestivalPost, type FestivalPostInput, type FestivalPostKind, type FestivalPostState, type FestivalPreferences, type FestivalReportInput, type FestivalRequestOptions, type FestivalWorkType, type MicrotransactionAbility, type MicrotransactionBranding, type MicrotransactionBridge, type MicrotransactionBridgeOptions, type MicrotransactionCapabilities, type MicrotransactionCatalog, type MicrotransactionCatalogFilter, type MicrotransactionCheckoutInput, type MicrotransactionCheckoutResult, type MicrotransactionCheckoutSession, type MicrotransactionCheckoutSessionInput, type MicrotransactionConsumeInput, type MicrotransactionCreatedCheckoutSession, type MicrotransactionCurrency, type MicrotransactionDelivery, type MicrotransactionDeliveryListFilters, type MicrotransactionDeliveryResult, type MicrotransactionDeliverySettings, type MicrotransactionDeliverySettingsInput, type MicrotransactionDeliveryStatus, type MicrotransactionEarnings, type MicrotransactionEntitlement, type MicrotransactionEnvironment, type MicrotransactionEnvironmentFilter, type MicrotransactionError, type MicrotransactionErrorCode, type MicrotransactionFramePolicy, type MicrotransactionFulfillmentStatus, type MicrotransactionGrant, type MicrotransactionGrantUsage, type MicrotransactionGrantUsageStatus, type MicrotransactionHandoff, type MicrotransactionHandoffClaim, type MicrotransactionHandoffClaimInput, type MicrotransactionLegacyConfirmation, type MicrotransactionManagementListFilters, type MicrotransactionMedia, type MicrotransactionMyPurchases, type MicrotransactionMyPurchasesFilters, type MicrotransactionOperation, type MicrotransactionOperationCapability, type MicrotransactionOrder, type MicrotransactionOrderDetail, type MicrotransactionOrderListFilters, type MicrotransactionOverlay, type MicrotransactionOverlayOptions, type MicrotransactionPaymentStatus, type MicrotransactionPayout, type MicrotransactionPayoutListFilters, type MicrotransactionPayoutStatus, type MicrotransactionPlayerPurchase, type MicrotransactionPrice, type MicrotransactionProduct, type MicrotransactionProductInput, type MicrotransactionProductListFilters, type MicrotransactionProductStatus, type MicrotransactionProductType, type MicrotransactionProvider, type MicrotransactionProviderConfiguration, type MicrotransactionProviderInput, type MicrotransactionProviderName, type MicrotransactionProviderOnboarding, type MicrotransactionProviderOnboardingInput, type MicrotransactionProviderSku, type MicrotransactionPurchaseInput, type MicrotransactionPurchaseMessage, type MicrotransactionPurchasePagination, type MicrotransactionQuote, type MicrotransactionReadiness, type MicrotransactionReadyMessage, type MicrotransactionRefund, type MicrotransactionRefundInput, type MicrotransactionRefundListFilters, type MicrotransactionRefundRecord, type MicrotransactionRefundRequest, type MicrotransactionRefundStatus, type MicrotransactionRelatedListFilters, type MicrotransactionRequestOptions, type MicrotransactionResponse, type MicrotransactionRestoreBridgeOptions, type MicrotransactionSessionOptions, type MicrotransactionSettings, type MicrotransactionSettingsInput, type MicrotransactionTaxCollection, type MicrotransactionVerifiedSession, createMicrotransactionBridge, createMicrotransactionNonce, createMicrotransactionRestoreBridge, Glitch as default, openMicrotransactionOverlay, openMicrotransactionRestoreOverlay };
@@ -2,15 +2,84 @@
2
2
 
3
3
  **Player checkout/history minimum: SDK `3.15.0`, which is published.** The new
4
4
  administrative direct-management API below is a **major SDK `4.0.0` migration**.
5
- Verify usable published versions independently before installing; a reviewed
6
- local4.0 candidate is not proof of publication. Server-side MCP catalog/provider
5
+ Registry verification on September 16, 2026 confirmed SDK `3.15.0`, SDK `4.0.0`
6
+ and MCP `0.5.0` published. SDK4 is not required just for the guest player flow.
7
+ SDK `4.0.1` includes the additive readiness and tax-collection types, checkout
8
+ overlay retry/layout fixes, and tutorial corrections below. Release validation
9
+ is local; no hosted backend deployment was performed for this update.
10
+ Server-side MCP catalog/provider
7
11
  setup does not require installing or publishing the game SDK, so do not block
8
12
  authorized server configuration while runtime package work is pending.
9
13
 
10
14
  The SDK entry point is `Glitch.api.Microtransactions`. All HTTP methods return an
11
15
  Axios response whose `response.data.data` contains the typed commerce result.
12
16
  Configure the ordinary API base once using the existing Glitch configuration.
13
- Never put a developer/MCP/install token into a shipped browser game.
17
+ Never put administrative/developer credentials, MCP tokens or provider secrets
18
+ into a shipped browser game. Existing supported **install-purpose runtime tokens**
19
+ are a separate capability: use them only for their documented install, validation,
20
+ heartbeat and telemetry endpoints. They do not authenticate commerce or prove paid
21
+ ownership, and must not be injected into the guest commerce context.
22
+
23
+ ## Guest authentication and supported test origins
24
+
25
+ A fresh SDK context has no default auth token. Setting only the API base URL does
26
+ not log in, read credentials from storage, or add a Bearer token. However,
27
+ `Config.setAuthToken` and `Requests.setAuthToken` configure shared global auth:
28
+ `Requests.processRoute` automatically includes that Authorization header, including
29
+ on `catalog`, `createCheckoutSession` and `createRestoreSession`. A per-request
30
+ `{playerToken}` overrides it; `{checkoutToken}` adds only `X-Checkout-Token` and
31
+ does NOT suppress global auth. The published 3.15.0 also appends a selected global
32
+ `community_id` query on these routes (not a body field); 4.0.0 excludes community
33
+ context for commerce. Neither commerce implementation mutates global auth/context.
34
+
35
+ Keep guest commerce in its own credential-free SDK context. Do not initialize it
36
+ with an admin JWT, MCP credential or shared Axios Authorization default/interceptor.
37
+ This does not require removing an unrelated allowed install-purpose token from
38
+ the game's existing install/validation/heartbeat flow or changing global SDK auth.
39
+ Preserve that supported integration; do not reuse its token as commerce auth or
40
+ temporarily clear/replace another context's global auth to make a guest request.
41
+ Keep the owning account JWT inside Glitch's hosted account page, and use
42
+ the verified short-lived player token only in per-request player options. Adding
43
+ an admin JWT to a guest request is not a fix for a hosted sandbox 401.
44
+
45
+ The local backend guest-entry change applies only to `catalog`, `checkout-sessions`
46
+ and `restore-sessions`: use the exact configured browser **gameOrigin**, and for
47
+ session creation set `return_origin` equal to it. Hosted testing requires approved
48
+ **HTTPS** game/API/checkout endpoints. Sandbox catalog/checkout require enabled
49
+ sandbox title settings; sandbox is a payment environment, not a relaxed Origin
50
+ policy. Historical restore entry may remain available with commerce off, but
51
+ the hosted owning-account bind still controls access. Quote/pay/inventory/finance
52
+ do not become anonymous. This contract must be verified on the target backend;
53
+ an SDK transport test alone does not establish that the server fix is deployed.
54
+
55
+ HTTP loopback is only for an explicitly configured **local/testing backend** and
56
+ its approved local game/checkout origins. `allowLocalDevelopment:true` relaxes a
57
+ client helper check only; it cannot authorize localhost against hosted services.
58
+ Published helpers also recognize some development hostnames; that does not make
59
+ those hostnames supported by a hosted backend. Browsers supply `Origin`; never
60
+ spoof it in game code. Use `window.location.origin`, not the full page URL.
61
+
62
+ An origin is scheme + host + port. Paths are NOT an origin boundary: games at
63
+ `https://shared.example/games/a` and `/games/b` have the same origin. Shared S3 or
64
+ CDN hostnames with per-game paths cannot isolate tenants via an origin allowlist.
65
+ Use an independently approved per-game hostname/origin; do not expand an allowlist
66
+ or silently substitute a path to make testing pass.
67
+
68
+ ## Configuration readiness versus verified integration
69
+
70
+ `ready` and optional `configuration_ready` describe configuration only. Optional
71
+ `readiness.integration_verified` means stored sandbox **paid + fulfilled + claimed**
72
+ evidence. Older responses may omit the new field: absence means unknown, not true
73
+ and not false. `settings.integration_verified` already exists separately. Neither
74
+ a configuration save, a ready flag, nor an iframe-ready event proves a new payment,
75
+ current inventory delivery or successful claim. Integration evidence is not browser
76
+ 3DS certification; record challenge success/cancel/failure separately. Do not call
77
+ `verifyIntegration` or perform a test purchase without authorization.
78
+
79
+ MCP tool discovery is not credential scope. A visible tool can still return 403
80
+ for a missing title ability; that is separate from a guest-entry 401. Preserve the
81
+ status/code and check the effective connection's credential abilities. Do not change
82
+ global connector credentials or broaden permissions as a runtime workaround.
14
83
 
15
84
  ## Developer setup
16
85
 
@@ -44,6 +113,45 @@ Never put a developer/MCP/install token into a shipped browser game.
44
113
 
45
114
  ## SDK4.0 administrative migration
46
115
 
116
+ ### SDK 4.0.1 additive follow-up
117
+
118
+ This follow-up adds optional `configuration_ready` and `integration_verified`
119
+ readiness fields; it does not change routes, auth precedence or required player
120
+ request fields. Existing typed DTO literals and older servers remain valid.
121
+ Callers must handle an absent integration flag as unknown. The copyable starter
122
+ now additionally requires `gameOrigin` and `timberGrantKey` (example function
123
+ parameters, not new SDK/API parameters). These additions follow the SDK `4.0.0`
124
+ baseline; local tests do not establish hosted backend deployment.
125
+
126
+ Published SDK3.15.0 CJS and its explicit CommonJS/bundler-interoperable ESM path
127
+ support the guest/account payloads. Its raw native ESM entry contains a legacy
128
+ `require('crypto-js')` during initialization, so it is not a standalone browser
129
+ script-module guarantee. SDK4 CJS and native ESM pass the runtime tests. This
130
+ packaging distinction is separate from backend 401 and does not require an
131
+ already-working SDK3.15 game to upgrade just for player checkout.
132
+
133
+ Local verification (no backend/provider calls):
134
+
135
+ ```sh
136
+ npm test
137
+ npx tsc --noEmit
138
+ npm run build
139
+ npm run build-docs
140
+ npm run test:package
141
+ npm run test:commerce-compat -- --published
142
+ ```
143
+
144
+ The last command fetches only public npm registry tarballs into memory, verifies
145
+ the pinned SHA-512 values in `scripts/fixtures/published-commerce.json`, and runs
146
+ their unmodified CJS/ESM bundles with an in-memory browser HTTP transport. It also
147
+ records the SDK3.15 raw-ESM caveat separately rather than hiding it with a shim.
148
+ It asserts exact guest bodies/query, no default auth, legacy community injection,
149
+ hosted account-bind and scoped credentials, and old/new readiness response
150
+ pass-through. It does not prove deployed backend authorization, catalog availability,
151
+ payment, fulfillment, claim execution or browser 3DS. Ordinary package tests run
152
+ the local-build part offline. The normal build/build-docs pipeline generates
153
+ artifacts; never hand-edit `dist` or generated API docs.
154
+
47
155
  Player checkout, restore, inventory and self-history routes remain compatible with
48
156
  SDK3.15. The administrative changes are deliberately major:
49
157
 
@@ -131,14 +239,25 @@ Server capability schemas remain authoritative.
131
239
  Required product fields are **SKU\***, **Name\***, **Type\***, **Prices\*** and
132
240
  **Grants\***; each price needs currency, country and integer minor-unit amount,
133
241
  and each grant needs key, quantity and kind. A pass also needs duration in seconds.
134
- For a pack of **100 Timber** spent building things, choose product type `currency`
135
- (or `consumable`) and grant `{key:'timber',quantity:100,kind:'consumable'}`. A durable
136
- grant means lasting ownership and cannot be spent; it is wrong for building Timber.
242
+ For a pack of **100 Timber** spent building things, use that title's actual
243
+ consumable grant key. Keys are title-scoped, not globally reserved: another game
244
+ may already use `timber` as consumable and should pass that exact key. The starter
245
+ requires an explicit key using the existing 1–100 character grammar above;
246
+ namespacing is optional. Validate its canonical grant kind from the title's catalog
247
+ and server-verified inventory, never from the display name. Preserve the per-title
248
+ key/kind invariant and all old grants/orders; never convert durable ownership.
249
+
250
+ **WOTW-specific migration proposal:** WOTW (title ID prefix `ad467`, abbreviated)
251
+ already has durable `timber`. That title needs a coordinated new consumable key
252
+ and game-resource mapping; a new SKU alone cannot retype its existing key.
253
+ `wotw.resource.timber` is one possible new key, not an existing catalog fact or a
254
+ global naming rule. This proposal does not create/publish products or prices or
255
+ authorize a catalog mutation. It does not restrict other titles' consumable keys.
137
256
 
138
257
  ## Hosted checkout and account creation
139
258
 
140
259
  `createCheckoutSession(titleId, {product_id,quantity,country,currency,environment,
141
- channel:'web',return_origin,nonce})` is anonymous-safe and only opens the purchase
260
+ channel:'web',return_origin,nonce})` supports guest entry and only opens the purchase
142
261
  flow. Use `createMicrotransactionNonce()` to generate the nonce and retain it in
143
262
  the game. `hosted_url` points to Glitch's game-branded checkout with the session
144
263
  secret in a `#token` fragment, never a query parameter.
@@ -162,6 +281,15 @@ only after its valid-session account/checkout UI is usable. Exact origin/source/
162
281
  session/nonce checks protect this signal, and it never grants inventory. Retry
163
282
  resets timers; verified readiness and close clear them.
164
283
 
284
+ Retry first commits `about:blank` inside the existing iframe, then restores the
285
+ exact original hosted URL after that blank document loads. This avoids a
286
+ fragment-only navigation after checkout removes `#token` from its visible URL.
287
+ The iframe and its WindowProxy stay the same, so the existing exact
288
+ origin/source/title/session/nonce bridge remains pinned. No query parameter,
289
+ new checkout session or payment is created. Repeated Retry clicks during this
290
+ navigation are coalesced; each phase has a bounded watchdog, and Close still
291
+ cleans up while navigation or a verified claim is pending.
292
+
165
293
  The read-only `getCheckoutFramePolicy(titleId,sessionId)` returns only approved
166
294
  `frame_ancestors` and expiry; the hosted document uses that server-owned policy.
167
295
  It does not expose a checkout token or player data.
@@ -204,9 +332,10 @@ event. Closing checkout without a successful claim does not call this a purchase
204
332
  ### Minimal working Timber shop
205
333
 
206
334
  Copy this JavaScript module into your game's browser bundle. Call
207
- `installTimberShop` with the title/product IDs and API/checkout origins shown by
208
- your game integration settings. For local testing use your approved local origins
209
- and `allowLocalDevelopment:true`; for production use approved HTTPS endpoints.
335
+ `installTimberShop` with the title/product IDs, exact approved `gameOrigin`,
336
+ API/checkout origins and actual consumable `timberGrantKey` from that title's catalog.
337
+ Use approved HTTPS origins for hosted sandbox testing. HTTP loopback with
338
+ `allowLocalDevelopment:true` additionally requires a local/testing backend.
210
339
  The example creates its own small UI, so no undefined HTML elements or game helper
211
340
  functions are required. It never takes the player away from the game.
212
341
 
@@ -217,8 +346,16 @@ import Glitch, {
217
346
  openMicrotransactionRestoreOverlay,
218
347
  } from 'glitch-javascript-sdk';
219
348
 
220
- export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrigin,
349
+ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrigin, gameOrigin, timberGrantKey,
221
350
  environment = 'sandbox', allowLocalDevelopment = false }) {
351
+ if (new URL(gameOrigin).origin !== gameOrigin || window.location.origin !== gameOrigin) {
352
+ throw new Error('Open the game on its exact approved gameOrigin; a path is not an origin.');
353
+ }
354
+ if (typeof timberGrantKey !== 'string' || timberGrantKey.length < 1 || timberGrantKey.length > 100
355
+ || /[^A-Za-z0-9_.-]/.test(timberGrantKey)) {
356
+ throw new Error('Supply an explicit grant key: 1–100 letters, numbers, underscores, dots or hyphens.');
357
+ }
358
+ // This game bundle must not configure global account/admin/MCP auth.
222
359
  Glitch.util.Requests.setBaseUrl(apiBaseUrl); // Set API location, NOT global auth.
223
360
  const api = Glitch.api.Microtransactions;
224
361
  const game = { playerId: null, inventory: [], paused: false };
@@ -232,15 +369,17 @@ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrig
232
369
  const say = text => { status.textContent = text; };
233
370
 
234
371
  function replaceInventoryInYourGame(entitlements) {
372
+ const resource = entitlements.find(x => x.key === timberGrantKey);
373
+ if (resource && resource.kind !== 'consumable') throw new Error('Timber grant kind mismatch.');
235
374
  game.inventory = entitlements; // REPLACE the snapshot. Never add 100 here.
236
- timber.textContent = 'Timber: ' + (entitlements.find(x => x.key === 'timber')?.balance ?? 0);
375
+ timber.textContent = 'Timber: ' + (resource?.balance ?? 0);
237
376
  }
238
377
  function setGamePaused(paused) { game.paused = paused; }
239
378
  function onVerified(result) {
379
+ replaceInventoryInYourGame(result.entitlements); // Validate canonical kind before accepting this account.
240
380
  game.playerId = result.player_id; // Associate the game's profile with this player.
241
381
  playerToken = result.player_token; // Memory only; never a URL or global auth token.
242
382
  tokenExpiresAt = Date.parse(result.expires_at);
243
- replaceInventoryInYourGame(result.entitlements); // Already verified by Glitch.
244
383
  say('Account connected. Your current inventory is ready.');
245
384
  }
246
385
  function playerOptions() {
@@ -261,7 +400,7 @@ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrig
261
400
  if (opening || overlay) return;
262
401
  opening = true;
263
402
  try {
264
- const context = { return_origin: window.location.origin,
403
+ const context = { return_origin: gameOrigin,
265
404
  nonce: createMicrotransactionNonce(), environment };
266
405
  const response = restore
267
406
  ? await api.createRestoreSession(titleId, context)
@@ -291,12 +430,14 @@ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrig
291
430
  async function useTenTimber() {
292
431
  if (spending || game.paused) return;
293
432
  const options = playerOptions();
433
+ const resource = game.inventory.find(x => x.key === timberGrantKey);
434
+ if (!resource || resource.kind !== 'consumable') throw new Error('A verified consumable grant is required.');
294
435
  if (pendingUse && pendingUse.playerId !== game.playerId) {
295
436
  throw new Error('Restore the original account before retrying its pending action.');
296
437
  }
297
438
  // Create ONCE for this gameplay intent. A failed retry keeps this same object.
298
439
  pendingUse ??= { playerId: game.playerId, action_id: createMicrotransactionNonce(),
299
- key: 'timber', quantity: 10 };
440
+ key: timberGrantKey, quantity: 10 };
300
441
  spending = true;
301
442
  try {
302
443
  await api.consume(titleId, { key: pendingUse.key, quantity: pendingUse.quantity,
@@ -323,11 +464,15 @@ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrig
323
464
  ```
324
465
 
325
466
  Call `installTimberShop({titleId: YOUR_TITLE_ID, productId: YOUR_TIMBER_PRODUCT_ID,
326
- apiBaseUrl: YOUR_API_BASE, checkoutOrigin: YOUR_CHECKOUT_ORIGIN})` from your existing
327
- game initialization. These four capitalized names describe your configuration;
467
+ apiBaseUrl: YOUR_API_BASE, checkoutOrigin: YOUR_CHECKOUT_ORIGIN,
468
+ gameOrigin: YOUR_APPROVED_GAME_ORIGIN, timberGrantKey: YOUR_CONSUMABLE_GRANT_KEY})`
469
+ from your existing game initialization. These names describe your configuration;
328
470
  replace them with the actual values, not credentials. `environment` is optional
329
471
  and defaults to sandbox. The example assumes an eligible US/USD price; choose a
330
472
  server-supported country/currency for your real player instead of guessing from IP.
473
+ Pass `timberGrantKey:'timber'` when that title's canonical `timber` is consumable.
474
+ The starter checks the returned entitlement kind before accepting an account or
475
+ spending; backend validation remains authoritative. It never changes a grant kind.
331
476
 
332
477
  **`replaceInventoryInYourGame` and `setGamePaused` are example game functions, not
333
478
  SDK APIs.** Their working demo bodies update the displayed Timber and `game`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "glitch-javascript-sdk",
3
- "version": "4.0.0",
3
+ "version": "4.0.1",
4
4
  "description": "Javascript SDK for Glitch",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -17,7 +17,8 @@
17
17
  "test": "node scripts/test-hosting-routes.cjs && node scripts/test-game-advertising-routes.cjs && node scripts/test-game-design-routes.cjs && node scripts/test-discord-media-routes.cjs && node scripts/test-user-email-delivery-routes.cjs && node scripts/test-game-show-ticket-routes.cjs && node scripts/test-festival-networking-routes.cjs && node scripts/test-microtransaction-routes.cjs && node scripts/test-microtransaction-overlay.cjs && node scripts/test-microtransaction-tutorial.cjs",
18
18
  "build": "rm -Rf dist && rollup -c --bundleConfigAsCjs",
19
19
  "build-docs": "rm -rf docs && typedoc --tsconfig tsconfig.json src/",
20
- "test:package": "node scripts/test-package-exports.cjs"
20
+ "test:package": "node scripts/test-package-exports.cjs && npm run test:commerce-compat",
21
+ "test:commerce-compat": "node --experimental-vm-modules scripts/test-commerce-compat.cjs"
21
22
  },
22
23
  "author": "",
23
24
  "license": "ISC",
@@ -118,6 +118,17 @@ export interface MicrotransactionProduct extends Omit<MicrotransactionProductInp
118
118
  created_at: string;
119
119
  updated_at: string;
120
120
  }
121
+ /** Read-only collection facts, not tax exemption or a determination of tax owed. */
122
+ export interface MicrotransactionTaxCollection {
123
+ /** Configured intent stays automatic during a known pending-setup fallback. */
124
+ requested_mode: 'automatic' | 'disabled';
125
+ /** Pending setup may disable collection for a NEW order; unknown facts are null and block new automatic checkout. */
126
+ effective_mode: 'automatic' | 'disabled' | null;
127
+ status: string;
128
+ missing_fields: string[];
129
+ fallback_reason: 'stripe_tax_setup_incomplete' | null;
130
+ warnings: string[];
131
+ }
121
132
  export interface MicrotransactionProvider {
122
133
  provider: MicrotransactionProviderName;
123
134
  environment: MicrotransactionEnvironment;
@@ -132,10 +143,14 @@ export interface MicrotransactionProvider {
132
143
  channels: string[];
133
144
  payment_methods: string[];
134
145
  configuration: MicrotransactionProviderConfiguration;
135
- account: { id: string; country: string | null; charges_enabled: boolean; payouts_enabled: boolean; requirements_due: string[] } | null;
146
+ account: { id: string; country: string | null; charges_enabled: boolean; payouts_enabled: boolean; requirements_due: string[]; merchant_name?: string | null } | null;
136
147
  /** The game's payout target. Do not substitute the platform processing account's payouts_enabled. */
137
148
  payout_account: { source: 'platform' | 'user' | 'community' | 'managed'; id: string | null; available: boolean; country: string | null; transfers_active: boolean; payouts_enabled: boolean; requirements_due: string[]; reasons: string[] };
138
149
  tax: { status: string; missing_fields: string[] };
150
+ /** Current route facts only. Never use these to reinterpret an existing order's frozen decision. */
151
+ tax_collection?: MicrotransactionTaxCollection | null;
152
+ /** Non-blocking collection warnings, separate from reasons and payout_account availability. */
153
+ warnings?: string[];
139
154
  reasons: string[];
140
155
  checked_at: string | null;
141
156
  revision?: number;
@@ -147,6 +162,7 @@ export interface MicrotransactionProviderSku {
147
162
  amount_minor: number;
148
163
  }
149
164
  export interface MicrotransactionProviderConfiguration {
165
+ /** Requested configuration. Explicit disabled is sandbox-only; pending-setup fallback does not change live configuration to disabled. */
150
166
  tax_mode: 'automatic' | 'disabled';
151
167
  /** Stripe tax code txcd_ followed by exactly eight digits. */
152
168
  tax_code: string | null;
@@ -247,7 +263,12 @@ export interface MicrotransactionRefundInput extends MicrotransactionLegacyConfi
247
263
  }
248
264
  export interface MicrotransactionReadiness {
249
265
  status: 'disabled' | 'draft' | 'sandbox' | 'ready' | 'live' | 'degraded' | 'suspended';
266
+ /** Configuration readiness only; not proof of payment, delivery, claim or browser 3DS. */
250
267
  ready: boolean;
268
+ /** Optional on older backends; retains the same configuration meaning as ready. */
269
+ configuration_ready?: boolean;
270
+ /** Stored sandbox paid + fulfilled + claimed evidence. Absent means unknown; not browser/3DS certification. */
271
+ integration_verified?: boolean;
251
272
  blockers: string[];
252
273
  providers: MicrotransactionProvider[];
253
274
  commission_basis_points: 1200;
@@ -342,6 +363,8 @@ export interface MicrotransactionOrder {
342
363
  paid_at: string | null;
343
364
  refunded_minor: number;
344
365
  items: MicrotransactionGrant[];
366
+ /** Frozen decision, also returned inside checkout/session.order. Null/absent for legacy orders; never infer from current provider facts. Warnings do not imply zero tax owed. */
367
+ tax_collection?: MicrotransactionTaxCollection | null;
345
368
  entitlements?: MicrotransactionEntitlement[];
346
369
  }
347
370
  export interface MicrotransactionOrderDetail extends MicrotransactionOrder {
@@ -523,8 +546,9 @@ export interface MicrotransactionCapabilities {
523
546
  }
524
547
 
525
548
  /**
526
- * Provider-neutral, title-scoped commerce. Configure with user JWT; purchases
527
- * use a recoverable user account and limited checkout capability. Install/title
549
+ * Provider-neutral, title-scoped commerce. Guest games configure only the API
550
+ * base URL, never global account/admin auth. Hosted account pages use their own
551
+ * user JWT and limited checkout capability; playerToken overrides auth per request. Install/title
528
552
  * tokens cannot authorize money, ownership, refunds, or catalog changes.
529
553
  *
530
554
  * Each result preserves payment versus fulfillment versus settlement. Redirects
@@ -609,13 +633,13 @@ class Microtransactions {
609
633
  }
610
634
  /** Replay the same immutable event. Receiver must deduplicate event_id. This cannot mint goods. */
611
635
  static replayDelivery(title_id: string, delivery_id: string, data: MicrotransactionLegacyConfirmation = {}, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionDeliveryResult>('replayDelivery', title_id, data, { delivery_id }, undefined, options); }
612
- /** Public eligible catalog. Sandbox is restricted by backend environment/admin policy. */
636
+ /** Guest catalog on the exact approved game Origin. Sandbox requires enabled sandbox settings; the backend enforces environment policy. */
613
637
  static catalog(title_id: string, params?: MicrotransactionCatalogFilter, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionCatalog>('catalog', title_id, undefined, {}, params, options); }
614
638
  /** User-authenticated quote. Clients select product/quantity, never monetary values or seller accounts. */
615
639
  static createQuote(title_id: string, data: MicrotransactionPurchaseInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionQuote>('createQuote', title_id, data, {}, undefined, options); }
616
- /** Anonymous-safe opening step only. The hosted UI creates/logs into an account before payment. */
640
+ /** Guest opening only: browser Origin must equal approved return_origin. Inherits configured global auth; use an isolated credential-free game context. Hosted UI authenticates before payment. */
617
641
  static createCheckoutSession(title_id: string, data: MicrotransactionCheckoutSessionInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionCreatedCheckoutSession>('createCheckoutSession', title_id, data, {}, undefined, options); }
618
- /** Anonymous-safe inventory recovery. Opens an in-game hosted sign-in overlay, never creates a charge or requires the game's account JWT. */
642
+ /** Guest entry to hosted recovery, not inventory access. Exact approved Origin/return_origin required. Owning-account bind remains mandatory, including when commerce is off. Never install an account JWT in the game. */
619
643
  static createRestoreSession(title_id: string, data: { return_origin: string; nonce: string; environment: MicrotransactionEnvironment }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionCreatedCheckoutSession>('createRestoreSession', title_id, data, {}, undefined, options); }
620
644
  /** Read the session using its limited capability. Cannot mutate user identity or declare payment. */
621
645
  static getCheckoutSession(title_id: string, session_id: string, options: MicrotransactionSessionOptions) { return this.call<MicrotransactionCheckoutSession>('checkoutSession', title_id, undefined, { session_id }, undefined, options); }