glitch-javascript-sdk 3.15.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.
@@ -1,22 +1,91 @@
1
1
  # Game microtransactions
2
2
 
3
- **Minimum SDK for this guide: `3.15.0`.** Use a confirmed published `3.15.0+`
4
- release or an approved local package. Registry verification on September 15, 2026
5
- showed public latest `3.10.8`, which lacks commerce; a plain public npm install at
6
- that point cannot run this callback/history example. Until `3.15.0` is actually
7
- published, use only the reviewed local `glitch-javascript-sdk-3.15.0.tgz` for testing.
8
- Do not change a production dependency to an unpublished version or assume that
9
- local build success means public publication has happened.
3
+ **Player checkout/history minimum: SDK `3.15.0`, which is published.** The new
4
+ administrative direct-management API below is a **major SDK `4.0.0` migration**.
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
11
+ setup does not require installing or publishing the game SDK, so do not block
12
+ authorized server configuration while runtime package work is pending.
10
13
 
11
14
  The SDK entry point is `Glitch.api.Microtransactions`. All HTTP methods return an
12
15
  Axios response whose `response.data.data` contains the typed commerce result.
13
16
  Configure the ordinary API base once using the existing Glitch configuration.
14
- 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.
15
83
 
16
84
  ## Developer setup
17
85
 
18
86
  1. Read `settings`, `readiness`, `providers` and `listProducts` with a signed-in
19
- title administrator. Start disabled/sandbox. Approvals are server-controlled.
87
+ title administrator or scoped MCP caller. Use sandbox for development. Authorized
88
+ commerce operations execute directly; no custom confirmation/human-review gate.
20
89
  The **Enable in-game purchases** and **Show ads** switches live only on the
21
90
  game's Pricing/monetization page. Microtransactions is for products, media,
22
91
  prices, orders and integration—not a second location for those switches.
@@ -38,9 +107,128 @@ Never put a developer/MCP/install token into a shipped browser game.
38
107
  (12%) of discounted pre-tax subtotal. Actual provider costs are separate.
39
108
  Taxes are separate; pending earnings are not a verified available payout.
40
109
  6. Run a real approved provider sandbox purchase, verify game delivery/claim,
41
- then call `verifyIntegration(titleId, {order_id, confirm:true})`. This records
42
- real evidence, not a self-certified integration checkbox. Launch still needs
43
- independent seller/tax/provider approvals. MCP confirm alone cannot supply them.
110
+ then call `verifyIntegration(titleId, {order_id})`. This records
111
+ real evidence, not a self-certified integration checkbox. Actual external
112
+ provider/account/tax capability and global sales emergency controls still apply.
113
+
114
+ ## SDK4.0 administrative migration
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
+
155
+ Player checkout, restore, inventory and self-history routes remain compatible with
156
+ SDK3.15. The administrative changes are deliberately major:
157
+
158
+ - `refundOrder(titleId,orderId,{reason,amount_minor?,idempotency_key},options?)`
159
+ now requires a stable caller key. The SDK never generates it. Legacy `confirm`
160
+ is optional/ignored, not authorization. Keep one refund intent outside retries;
161
+ same key + changed payload conflicts, and unknown outcomes stay pinned.
162
+ - `providers(titleId,{environment}?,options?)` returns factual `configured` and
163
+ `available` values instead of an `approved` badge. `account` is the platform
164
+ processor; `payout_account` is the game's target and must be evaluated separately.
165
+ The older second-argument request-options overload remains compatible.
166
+ - `listProducts(titleId,{page,per_page,status,sku}?,options?)` now discovers the
167
+ complete catalog. `sku` matches exactly; status is draft/active/archived. Product
168
+ pages default to 200 records (1–200), unlike financial/history lists below.
169
+ Follow `pagination.has_more_pages`; absence on page one is not proof a SKU is
170
+ unused. Query the exact SKU after an uncertain create before retrying it.
171
+ The no-filter call and older request-options overload remain compatible.
172
+ - `updateProvider`, `refreshProvider` and `createProviderOnboarding` manage routes
173
+ and owned Stripe onboarding. Onboarding also requires a stable key and returns
174
+ `onboarding_url` for the same owned account on retry, not an arbitrary payee ID.
175
+ - `getDeliverySettings`/`updateDeliverySettings` expose enabled/URL and only public
176
+ verification material. Private signing keys remain server-side. Actual DNS/IP,
177
+ HTTPS and provider requirements are validated without an approval workflow.
178
+ Legacy `updateSettings.webhook_url` additionally requires commerce:fulfill as
179
+ well as commerce:write; prefer the dedicated delivery-settings methods.
180
+ - `listOrders`, `listRefunds`, `listDeliveries` and `listPayouts` use page1–10000,
181
+ per_page1–100(default25) and return arrays plus pagination. Get IDs from discovery.
182
+ `getOrder` retains the player receipt path; management relationships are optional
183
+ and can be finance-redacted. Omitted fields do not prove no records exist.
184
+ - `reconcileOrder`, `getRefund` and `reconcileRefund` inspect/recover the original
185
+ provider operations. A linked refund request or pending/unknown execution is not
186
+ a completed refund. Keep `execution_refund_id`, `execution_status` and actual
187
+ `order_refunded_minor` distinct. Transfers are not automatically bank-paid payouts.
188
+ - All commerce calls omit unrelated global community context without mutating the
189
+ stored community/auth state. Other SDK features retain their own context behavior.
190
+
191
+ Example stable refund intent (authorized commerce:finance only):
192
+
193
+ ```ts
194
+ const refundIntent = {
195
+ reason: 'Customer refund', amount_minor: 199,
196
+ idempotency_key: crypto.randomUUID(), // ONCE for this intent, outside retries.
197
+ };
198
+ async function submitOrRetryRefund() {
199
+ return Glitch.api.Microtransactions.refundOrder(titleId, orderId, refundIntent);
200
+ }
201
+ // If response is unknown/lost, keep refundIntent. Inspect/reconcile its original
202
+ // operation instead of making another key or blindly starting another refund.
203
+ ```
204
+
205
+ Provider configuration reuses existing platform credentials; never send platform
206
+ Stripe/Xsolla API keys or MCP credentials as settings. A new owned title/environment
207
+ Xsolla `webhook_secret` is write-only(16–512 chars) under finance scope, encrypted
208
+ server-side and never returned/audited. Existing platform/historical bindings cannot
209
+ be overwritten. Keep this out of runtime game code, logs and raw JSON editors.
210
+ Missing external setup returns factual reasons; saving configuration is not proof
211
+ that a provider can accept payments. Global sales-off may block new purchases while
212
+ authorized configuration and historical refunds remain available.
213
+
214
+ ### Signed server-delivery receiver
215
+
216
+ [The complete Node24+ receiver example](commerce-delivery-receiver.mjs) verifies
217
+ the exact raw body before parsing and durably queues event IDs without applying
218
+ embedded inventory. Pin `title_id`, environment, `key_id` and the base64 raw32-byte
219
+ `verification_public_key` from authenticated delivery settings, never from a message.
220
+ Require algorithm `ed25519`, `X-Glitch-Key-Id`, UNIX-second `X-Glitch-Timestamp`
221
+ within300 seconds, and `X-Glitch-Event-Id === body.id`. `X-Glitch-Signature` is base64
222
+ raw64 bytes over timestamp + `.` + exact raw JSON bytes. ACK2xx `{event_id}` only
223
+ after durable handling/commit. Duplicate IDs stay deduped across restarts.
224
+
225
+ Do not increment inventory or replace aggregate balances from webhook snapshots:
226
+ cross-order notifications can arrive out of order. An authorized game/player
227
+ refreshes current `listEntitlements`, or a real server adapter uses monotonic
228
+ inventory revisions. Legacy HMAC delivery is a separate configured algorithm;
229
+ leave its original secrets unchanged and reject message-selected algorithm/key
230
+ downgrades. The example needs Node24 only; it does not change the core SDK/MCP
231
+ runtime requirement or replace actual payment/browser3DS verification.
44
232
 
45
233
  Product limits: SKU/grant key 1–100 alphanumeric/underscore/dot/hyphen characters;
46
234
  name 255 characters; description 4000; 10 distinct Media UUIDs; 50 prices; 30
@@ -51,14 +239,25 @@ Server capability schemas remain authoritative.
51
239
  Required product fields are **SKU\***, **Name\***, **Type\***, **Prices\*** and
52
240
  **Grants\***; each price needs currency, country and integer minor-unit amount,
53
241
  and each grant needs key, quantity and kind. A pass also needs duration in seconds.
54
- For a pack of **100 Timber** spent building things, choose product type `currency`
55
- (or `consumable`) and grant `{key:'timber',quantity:100,kind:'consumable'}`. A durable
56
- 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.
57
256
 
58
257
  ## Hosted checkout and account creation
59
258
 
60
259
  `createCheckoutSession(titleId, {product_id,quantity,country,currency,environment,
61
- 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
62
261
  flow. Use `createMicrotransactionNonce()` to generate the nonce and retain it in
63
262
  the game. `hosted_url` points to Glitch's game-branded checkout with the session
64
263
  secret in a `#token` fragment, never a query parameter.
@@ -82,6 +281,15 @@ only after its valid-session account/checkout UI is usable. Exact origin/source/
82
281
  session/nonce checks protect this signal, and it never grants inventory. Retry
83
282
  resets timers; verified readiness and close clear them.
84
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
+
85
293
  The read-only `getCheckoutFramePolicy(titleId,sessionId)` returns only approved
86
294
  `frame_ancestors` and expiry; the hosted document uses that server-owned policy.
87
295
  It does not expose a checkout token or player data.
@@ -124,9 +332,10 @@ event. Closing checkout without a successful claim does not call this a purchase
124
332
  ### Minimal working Timber shop
125
333
 
126
334
  Copy this JavaScript module into your game's browser bundle. Call
127
- `installTimberShop` with the title/product IDs and API/checkout origins shown by
128
- your game integration settings. For local testing use your approved local origins
129
- 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.
130
339
  The example creates its own small UI, so no undefined HTML elements or game helper
131
340
  functions are required. It never takes the player away from the game.
132
341
 
@@ -137,8 +346,16 @@ import Glitch, {
137
346
  openMicrotransactionRestoreOverlay,
138
347
  } from 'glitch-javascript-sdk';
139
348
 
140
- export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrigin,
349
+ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrigin, gameOrigin, timberGrantKey,
141
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.
142
359
  Glitch.util.Requests.setBaseUrl(apiBaseUrl); // Set API location, NOT global auth.
143
360
  const api = Glitch.api.Microtransactions;
144
361
  const game = { playerId: null, inventory: [], paused: false };
@@ -152,15 +369,17 @@ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrig
152
369
  const say = text => { status.textContent = text; };
153
370
 
154
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.');
155
374
  game.inventory = entitlements; // REPLACE the snapshot. Never add 100 here.
156
- timber.textContent = 'Timber: ' + (entitlements.find(x => x.key === 'timber')?.balance ?? 0);
375
+ timber.textContent = 'Timber: ' + (resource?.balance ?? 0);
157
376
  }
158
377
  function setGamePaused(paused) { game.paused = paused; }
159
378
  function onVerified(result) {
379
+ replaceInventoryInYourGame(result.entitlements); // Validate canonical kind before accepting this account.
160
380
  game.playerId = result.player_id; // Associate the game's profile with this player.
161
381
  playerToken = result.player_token; // Memory only; never a URL or global auth token.
162
382
  tokenExpiresAt = Date.parse(result.expires_at);
163
- replaceInventoryInYourGame(result.entitlements); // Already verified by Glitch.
164
383
  say('Account connected. Your current inventory is ready.');
165
384
  }
166
385
  function playerOptions() {
@@ -181,7 +400,7 @@ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrig
181
400
  if (opening || overlay) return;
182
401
  opening = true;
183
402
  try {
184
- const context = { return_origin: window.location.origin,
403
+ const context = { return_origin: gameOrigin,
185
404
  nonce: createMicrotransactionNonce(), environment };
186
405
  const response = restore
187
406
  ? await api.createRestoreSession(titleId, context)
@@ -211,12 +430,14 @@ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrig
211
430
  async function useTenTimber() {
212
431
  if (spending || game.paused) return;
213
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.');
214
435
  if (pendingUse && pendingUse.playerId !== game.playerId) {
215
436
  throw new Error('Restore the original account before retrying its pending action.');
216
437
  }
217
438
  // Create ONCE for this gameplay intent. A failed retry keeps this same object.
218
439
  pendingUse ??= { playerId: game.playerId, action_id: createMicrotransactionNonce(),
219
- key: 'timber', quantity: 10 };
440
+ key: timberGrantKey, quantity: 10 };
220
441
  spending = true;
221
442
  try {
222
443
  await api.consume(titleId, { key: pendingUse.key, quantity: pendingUse.quantity,
@@ -243,11 +464,15 @@ export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrig
243
464
  ```
244
465
 
245
466
  Call `installTimberShop({titleId: YOUR_TITLE_ID, productId: YOUR_TIMBER_PRODUCT_ID,
246
- apiBaseUrl: YOUR_API_BASE, checkoutOrigin: YOUR_CHECKOUT_ORIGIN})` from your existing
247
- 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;
248
470
  replace them with the actual values, not credentials. `environment` is optional
249
471
  and defaults to sandbox. The example assumes an eligible US/USD price; choose a
250
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.
251
476
 
252
477
  **`replaceInventoryInYourGame` and `setGamePaused` are example game functions, not
253
478
  SDK APIs.** Their working demo bodies update the displayed Timber and `game`
@@ -360,12 +585,12 @@ hosted-account flows, not the default anonymous-game recovery path.
360
585
  - Earnings `transferred_minor` means money transferred to a provider balance,
361
586
  not a confirmed bank deposit. Preserve `bank_payout_status` and reserve/reconciliation
362
587
  fields; never relabel pending or transferred balances as paid bank payouts.
363
- - `requestRefund` is an owning account's support request. `refundOrder` requires
364
- a separately approved financial administrator; pending/unknown is not completed.
588
+ - `requestRefund` is an owning account's support request. `refundOrder` executes
589
+ directly for an authorized finance caller with a stable key; pending/unknown is not completed.
365
590
  Preserve historical orders and reverse commission proportionately. Refunds
366
591
  use the original provider/account, not the currently preferred payment route.
367
592
  - Handle HTTP 401/403 for account/scope, 404 for unavailable or cross-title IDs,
368
- 409 for idempotency/state/approval conflicts, 410 for expired sessions/claims,
593
+ 409 for idempotency/state/invariant conflicts, 410 for expired sessions/claims,
369
594
  422 for invalid inputs/revenue policy, 429 for rate limits and 503 for provider
370
595
  coverage. Do not retry a hard decline/fraud block through another provider.
371
596
  - Ads-off is an actual per-title delivery policy. The backend rejects removing
@@ -374,12 +599,13 @@ hosted-account flows, not the default anonymous-game recovery path.
374
599
 
375
600
  ## MCP
376
601
 
377
- Use `mcpCapabilities` to discover exact schemas, abilities, approval flags and
602
+ Use `mcpCapabilities` to discover exact schemas, abilities, mutation metadata and
378
603
  examples. `mcpOperation` always targets the authenticated MCP facade; it never
379
604
  uses a game's runtime token. `mcpUploadMedia` uses the same authorized Media
380
605
  pipeline. The companion `glitch-mcp` package supplies explicit tools, a
381
606
  `glitch://microtransactions/setup` resource, dynamic title schema resources and
382
- the `glitch_setup_microtransactions` prompt. A model must not auto-approve live
383
- prices, provider activation, financial actions or disabling the last revenue model.
607
+ the `glitch_setup_microtransactions` prompt. Authorized title-scoped MCP management
608
+ executes directly without confirmation/proposal/approval workflows. Permissions,
609
+ actual provider facts and the last-revenue-model/financial invariants remain enforced.
384
610
  Developer MCP read tools do not impersonate players. The self-only runtime purchase
385
611
  history API is documented for game code, not exposed as an arbitrary-player MCP tool.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "glitch-javascript-sdk",
3
- "version": "3.15.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",