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/README.md +10 -0
- package/dist/cjs/index.js +107 -32
- package/dist/cjs/index.js.map +1 -1
- package/dist/esm/api/Microtransactions.d.ts +30 -5
- package/dist/esm/index.js +114 -32
- package/dist/esm/index.js.map +1 -1
- package/dist/index.d.ts +31 -6
- package/guides/microtransactions.md +162 -17
- package/package.json +3 -2
- package/src/api/Microtransactions.ts +30 -6
- package/src/util/MicrotransactionOverlay.ts +92 -27
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.
|
|
12777
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
|
|
6
|
-
|
|
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
|
|
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,
|
|
135
|
-
|
|
136
|
-
|
|
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})`
|
|
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
|
|
208
|
-
|
|
209
|
-
|
|
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: ' + (
|
|
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:
|
|
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:
|
|
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
|
|
327
|
-
|
|
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.
|
|
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.
|
|
527
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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); }
|