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.
- package/README.md +10 -0
- package/dist/browser/hosting-runtime.js +1 -1
- package/dist/browser/hosting-runtime.js.map +1 -1
- package/dist/cjs/index.js +7602 -52
- package/dist/cjs/index.js.map +1 -1
- package/dist/esm/api/Microtransactions.d.ts +286 -39
- package/dist/esm/index.js +7643 -52
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/util/Requests.d.ts +3 -1
- package/dist/index.d.ts +290 -41
- package/guides/commerce-delivery-receiver.mjs +117 -0
- package/guides/microtransactions.md +258 -32
- package/package.json +3 -2
- package/src/api/Microtransactions.ts +252 -38
- package/src/routes/MicrotransactionsRoute.ts +11 -0
- package/src/util/MicrotransactionOverlay.ts +92 -27
- package/src/util/Requests.ts +2 -2
- package/src/util/Session.ts +3 -2
|
@@ -1,22 +1,91 @@
|
|
|
1
1
|
# Game microtransactions
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
local
|
|
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
|
|
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.
|
|
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
|
|
42
|
-
real evidence, not a self-certified integration checkbox.
|
|
43
|
-
|
|
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,
|
|
55
|
-
|
|
56
|
-
|
|
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})`
|
|
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
|
|
128
|
-
|
|
129
|
-
|
|
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: ' + (
|
|
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:
|
|
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:
|
|
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
|
|
247
|
-
|
|
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`
|
|
364
|
-
|
|
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/
|
|
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,
|
|
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.
|
|
383
|
-
|
|
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
|
+
"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",
|