glitch-javascript-sdk 4.0.1 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,7 @@
1
+ import Route from './interface';
2
+ declare class PreordersRoute {
3
+ static routes: {
4
+ [key: string]: Route;
5
+ };
6
+ }
7
+ export default PreordersRoute;
package/dist/index.d.ts CHANGED
@@ -12979,6 +12979,166 @@ declare class Microtransactions {
12979
12979
  private static call;
12980
12980
  }
12981
12981
 
12982
+ type PreorderFulfillmentType = 'glitch_license' | 'platform_key';
12983
+ type PreorderOfferStatus = 'draft' | 'active' | 'paused' | 'ended' | 'archived';
12984
+ type PreorderDerivedState = 'draft' | 'available' | 'scheduled' | 'sold_out' | 'paused' | 'ended' | 'released' | 'archived';
12985
+ type PreorderPaymentStatus = 'created' | 'requires_action' | 'processing' | 'paid' | 'failed' | 'canceled' | 'refunded' | 'disputed' | 'unknown';
12986
+ type PreorderFulfillmentStatus = 'waiting_for_release' | 'ready' | 'processing' | 'fulfilled' | 'blocked_missing_build' | 'blocked_missing_key' | 'canceled' | 'failed';
12987
+ interface PreorderRequestOptions extends Pick<AxiosRequestConfig, 'signal' | 'timeout'> {
12988
+ }
12989
+ interface PreorderPrice {
12990
+ country: string;
12991
+ currency: string;
12992
+ amount_minor: number;
12993
+ }
12994
+ interface PreorderInventory {
12995
+ available: number;
12996
+ reserved: number;
12997
+ delivered: number;
12998
+ retired: number;
12999
+ total: number;
13000
+ }
13001
+ interface PreorderOfferInput {
13002
+ sku: string;
13003
+ platform_code: string;
13004
+ platform_label: string;
13005
+ fulfillment_type: PreorderFulfillmentType;
13006
+ status?: PreorderOfferStatus;
13007
+ sales_start_at?: string | null;
13008
+ sales_end_at?: string | null;
13009
+ release_at: string;
13010
+ limit_total?: number | null;
13011
+ max_per_user?: number;
13012
+ custom_message?: string | null;
13013
+ post_purchase_url?: string | null;
13014
+ redeem_url?: string | null;
13015
+ prices: PreorderPrice[];
13016
+ }
13017
+ interface PreorderOffer extends Omit<PreorderOfferInput, 'status'> {
13018
+ id: string;
13019
+ title_id: string;
13020
+ status: PreorderOfferStatus;
13021
+ state: PreorderDerivedState;
13022
+ sold: number;
13023
+ reserved_or_paid: number;
13024
+ remaining: number | null;
13025
+ revision: number;
13026
+ inventory?: PreorderInventory;
13027
+ owned_count?: number;
13028
+ }
13029
+ interface PreorderSettings {
13030
+ enabled: boolean;
13031
+ timezone: string;
13032
+ readiness?: PreorderReadiness;
13033
+ }
13034
+ interface PreorderCatalog {
13035
+ enabled: boolean;
13036
+ timezone?: string;
13037
+ offers: PreorderOffer[];
13038
+ }
13039
+ interface PreorderPurchaseInput {
13040
+ country?: string;
13041
+ currency?: string;
13042
+ idempotency_key: string;
13043
+ payment_method_id?: string;
13044
+ payment_intent_id?: string;
13045
+ }
13046
+ interface PreorderOrder {
13047
+ id: string;
13048
+ title_id: string;
13049
+ offer_id: string;
13050
+ user_id?: string;
13051
+ platform_code: string;
13052
+ platform_label: string;
13053
+ fulfillment_type: PreorderFulfillmentType;
13054
+ payment_status: PreorderPaymentStatus;
13055
+ fulfillment_status: PreorderFulfillmentStatus;
13056
+ currency: string;
13057
+ subtotal_minor: number;
13058
+ tax_minor: number;
13059
+ total_minor: number;
13060
+ promised_release_at: string;
13061
+ current_release_at: string;
13062
+ paid_at?: string;
13063
+ fulfilled_at?: string;
13064
+ custom_message?: string;
13065
+ post_purchase_url?: string;
13066
+ redeem_url?: string;
13067
+ platform_key?: string;
13068
+ key_masked_suffix?: string;
13069
+ purchase_email?: string;
13070
+ provider_reference?: string;
13071
+ commission_minor?: number;
13072
+ developer_share_minor?: number;
13073
+ requires_action?: boolean;
13074
+ client_secret?: string;
13075
+ payment_intent_id?: string;
13076
+ }
13077
+ interface PreorderReadinessIssue {
13078
+ offer_id: string;
13079
+ code: string;
13080
+ [key: string]: unknown;
13081
+ }
13082
+ interface PreorderReadiness {
13083
+ enabled: boolean;
13084
+ ready: boolean;
13085
+ blockers: PreorderReadinessIssue[];
13086
+ warnings: PreorderReadinessIssue[];
13087
+ }
13088
+ interface PreorderAdminOrderFilters {
13089
+ offer_id?: string;
13090
+ payment_status?: string;
13091
+ fulfillment_status?: string;
13092
+ per_page?: number;
13093
+ page?: number;
13094
+ }
13095
+ type PreorderAdminOrderAction = 'refund' | 'reconcile' | 'fulfill' | 'resend_receipt' | 'resend_access';
13096
+ declare class Preorders {
13097
+ static catalog(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderCatalog>>;
13098
+ static purchase(title_id: string, offer_id: string, data: PreorderPurchaseInput, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOrder>>;
13099
+ static myOrders(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<{
13100
+ orders: PreorderOrder[];
13101
+ }>>;
13102
+ static order(title_id: string, order_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOrder>>;
13103
+ static refundMine(title_id: string, order_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOrder>>;
13104
+ static resendMine(title_id: string, order_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<{
13105
+ resent: boolean;
13106
+ }>>;
13107
+ static settings(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderSettings>>;
13108
+ static updateSettings(title_id: string, data: Partial<Pick<PreorderSettings, 'enabled' | 'timezone'>>, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderSettings>>;
13109
+ static offers(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<{
13110
+ offers: PreorderOffer[];
13111
+ }>>;
13112
+ static offer(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>>;
13113
+ static createOffer(title_id: string, data: PreorderOfferInput, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>>;
13114
+ static updateOffer(title_id: string, offer_id: string, data: PreorderOfferInput, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>>;
13115
+ static activateOffer(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>>;
13116
+ static pauseOffer(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>>;
13117
+ static archiveOffer(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>>;
13118
+ static inventory(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderInventory>>;
13119
+ static importKeys(title_id: string, offer_id: string, keys: string[], options?: PreorderRequestOptions): AxiosPromise<Response<{
13120
+ inserted: number;
13121
+ duplicate_in_upload: number;
13122
+ duplicate_existing: number;
13123
+ invalid: number;
13124
+ inventory: PreorderInventory;
13125
+ }>>;
13126
+ static importKeyFile<T>(title_id: string, offer_id: string, file: File | Blob): AxiosPromise<Response<T>>;
13127
+ static retireKey(title_id: string, offer_id: string, key_id: string, reason: string, options?: PreorderRequestOptions): AxiosPromise<Response<{
13128
+ id: string;
13129
+ status: string;
13130
+ masked_suffix: string;
13131
+ }>>;
13132
+ static adminOrders(title_id: string, filters?: PreorderAdminOrderFilters, options?: PreorderRequestOptions): AxiosPromise<Response<{
13133
+ orders: PreorderOrder[];
13134
+ pagination: Record<string, number>;
13135
+ }>>;
13136
+ static readiness(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderReadiness>>;
13137
+ static adminOrderAction(title_id: string, order_id: string, action: PreorderAdminOrderAction, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOrder>>;
13138
+ static mcpCapabilities<T = unknown>(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<T>>;
13139
+ static mcpOperation<T = unknown>(title_id: string, operation: string, argumentsData?: Record<string, unknown>, options?: PreorderRequestOptions): AxiosPromise<Response<T>>;
13140
+ }
13141
+
12982
13142
  /** A one-time notification, never a receipt or authorization to grant goods. */
12983
13143
  interface MicrotransactionPurchaseMessage {
12984
13144
  type: 'glitch.microtransaction.updated';
@@ -13510,6 +13670,7 @@ declare class Glitch {
13510
13670
  Hosting: typeof Hosting;
13511
13671
  GameDesign: typeof GameDesign;
13512
13672
  Microtransactions: typeof Microtransactions;
13673
+ Preorders: typeof Preorders;
13513
13674
  };
13514
13675
  static util: {
13515
13676
  Requests: typeof Requests;
@@ -13599,4 +13760,4 @@ declare class Glitch {
13599
13760
  };
13600
13761
  }
13601
13762
 
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 };
13763
+ 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, type PreorderAdminOrderAction, type PreorderAdminOrderFilters, type PreorderCatalog, type PreorderDerivedState, type PreorderFulfillmentStatus, type PreorderFulfillmentType, type PreorderInventory, type PreorderOffer, type PreorderOfferInput, type PreorderOfferStatus, type PreorderOrder, type PreorderPaymentStatus, type PreorderPrice, type PreorderPurchaseInput, type PreorderReadiness, type PreorderReadinessIssue, type PreorderRequestOptions, type PreorderSettings, createMicrotransactionBridge, createMicrotransactionNonce, createMicrotransactionRestoreBridge, Glitch as default, openMicrotransactionOverlay, openMicrotransactionRestoreOverlay };
@@ -1,6 +1,94 @@
1
1
  # Game microtransactions
2
2
 
3
- **Player checkout/history minimum: SDK `3.15.0`, which is published.** The new
3
+ ## Start with direct REST (recommended for AI/LLM setup)
4
+
5
+ Prefer native fetch/HTTP for a new game integration. **No npm install, SDK import
6
+ or SDK version is a prerequisite.** MCP configures the server directly and the
7
+ runtime REST contract below works without a JavaScript library. The SDK remains
8
+ an optional convenience; preserve existing working SDK-based frontend code.
9
+
10
+ The complete dependency-free modal/verified-callback starter is published in the
11
+ MCP `glitch://microtransactions/setup` resource and the
12
+ `glitch_setup_microtransactions` prompt, also used by the game's AI setup export.
13
+ Use the starter rather than granting inventory in an unchecked message listener.
14
+ The following browser fetch example demonstrates guest transport only:
15
+
16
+ ```js
17
+ // apiBaseUrl ends in /api; titleId is the configured title, not message input.
18
+ const base = apiBaseUrl.replace(/\/$/, '') + '/titles/'
19
+ + encodeURIComponent(titleId) + '/microtransactions';
20
+ async function guest(path, body) {
21
+ const response = await fetch(base + path, {
22
+ method: body === undefined ? 'GET' : 'POST', credentials: 'omit', redirect: 'error',
23
+ headers: { Accept: 'application/json', ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
24
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
25
+ }); // Browser supplies Origin automatically; no Authorization or manual Origin.
26
+ const payload = await response.json();
27
+ if (!response.ok || !payload.data) throw new Error('Commerce unavailable: ' + response.status);
28
+ return payload.data; // ONE JSON envelope, unlike an Axios response.data.data wrapper.
29
+ }
30
+ const catalog = await guest('/catalog?environment=sandbox&country=US&currency=USD');
31
+ // Call once for this purchase intent, not on every retry/callback.
32
+ const nonce = crypto.randomUUID();
33
+ const session = await guest('/checkout-sessions', {
34
+ product_id: productId, quantity: 1, country: 'US', currency: 'USD', environment: 'sandbox',
35
+ channel: 'web', return_origin: window.location.origin, nonce,
36
+ });
37
+ // Validate the configured checkout origin/path/session/#token, then mount the starter's
38
+ // modal iframe with session.hosted_url. Never assign window.location or grant here.
39
+ ```
40
+
41
+ For shell diagnostics only, curl can send `Origin`; browser fetch cannot set it:
42
+
43
+ ```sh
44
+ curl --fail-with-body \
45
+ "$API_BASE_URL/titles/$TITLE_ID/microtransactions/catalog?environment=sandbox&country=US&currency=USD" \
46
+ -H 'Accept: application/json' -H "Origin: $APPROVED_GAME_ORIGIN"
47
+ ```
48
+
49
+ The variables above are nonsecret integration configuration. Sandbox catalog
50
+ requires enabled sandbox settings and an exact approved Origin. Checkout session
51
+ creation requires enabled matching environment and `return_origin` equal to the
52
+ browser Origin. Live catalog is public but does not authorize payment. Restore
53
+ entry uses `POST /restore-sessions` with environment/return_origin/fresh nonce and
54
+ can remain available after sales stop. Hosted HTTPS policy is not relaxed by
55
+ `environment:sandbox`; HTTP development origins require a local/testing backend.
56
+
57
+ Keep checkout inside the game's accessible modal iframe with pause/resume and
58
+ focus restoration, no top navigation, and bounded Retry/Close for the same
59
+ session. Pin exact checkout origin, actual iframe `contentWindow`, title/session
60
+ and nonce on ready/close/updated messages. `glitch.microtransaction.updated`
61
+ version1 supplies a one-use `claim_code`, not a paid entitlement. Exchange it at
62
+ `POST /handoffs/claim` with `{claim_code,nonce,return_origin,checkout_session_id}`
63
+ using guest headers; deduplicate repeated/in-flight messages. Validate returned
64
+ title/session/order/player and future token expiry, then use the scoped token in
65
+ per-request Authorization to read own `GET /orders/{order_id}` and
66
+ `GET /entitlements?environment=...`. Recheck receipt ownership/status and replace
67
+ inventory. Never increment by product quantity. Defer close until claim and
68
+ inventory work finishes; an uncertain/lost exchange needs restore, not blind replay.
69
+
70
+ Glitch's hosted page handles account creation/login and embedded Stripe/3DS.
71
+ The account JWT never enters the game. `X-Checkout-Token` permits limited session
72
+ status only. Keep the claimed player token in memory, not global auth/storage.
73
+ Own history is `GET /me/purchases?environment=...&page=1&per_page=20`; it does not
74
+ grant items. Explicit spending is `POST /consume` with key/quantity/environment
75
+ and one stable action_id retained across retry, followed by fresh inventory.
76
+ Restore may return `no_purchases_to_restore` for fully refunded-only accounts;
77
+ do not promise a token or repurchase as a history workaround. UI-ready/client
78
+ completion/authorization never proves capture, fulfillment or browser3DS success.
79
+
80
+ Media uploaded with `POST /titles/{title_id}/microtransactions/media` (multipart
81
+ `media`, commerce:write) is **commerce-only**, even though it reuses processing.
82
+ It must not populate title/game previews, galleries, cover or social imagery.
83
+ Attach only same-title commerce Media IDs to products/branding; generic/gallery/
84
+ social assets require separate commerce upload, not relinking. MCP management
85
+ still executes authorized writes without a custom human-confirmation workflow.
86
+
87
+ ## Optional JavaScript SDK reference
88
+
89
+ The remainder documents the optional SDK. These versions and imports are not
90
+ requirements for the REST flow above. **Optional player checkout/history minimum:
91
+ SDK `3.15.0`, which is published.** The new
4
92
  administrative direct-management API below is a **major SDK `4.0.0` migration**.
5
93
  Registry verification on September 16, 2026 confirmed SDK `3.15.0`, SDK `4.0.0`
6
94
  and MCP `0.5.0` published. SDK4 is not required just for the guest player flow.
@@ -67,10 +155,17 @@ or silently substitute a path to make testing pass.
67
155
 
68
156
  ## Configuration readiness versus verified integration
69
157
 
158
+ Sandbox proof is **optional QA, not required to enable purchases or activate live
159
+ sales**. Authorized developers can enable purchases through normal settings
160
+ without a sandbox order or `integration.verify` call. Actual provider/account,
161
+ market/tax, revenue, payment and fulfillment rules remain enforced.
162
+
70
163
  `ready` and optional `configuration_ready` describe configuration only. Optional
71
164
  `readiness.integration_verified` means stored sandbox **paid + fulfilled + claimed**
72
165
  evidence. Older responses may omit the new field: absence means unknown, not true
73
- and not false. `settings.integration_verified` already exists separately. Neither
166
+ and not false. `settings.integration_verified` already exists separately. A false
167
+ or absent proof flag is not an activation prerequisite and enabling purchases must
168
+ not manufacture a true flag. Neither
74
169
  a configuration save, a ready flag, nor an iframe-ready event proves a new payment,
75
170
  current inventory delivery or successful claim. Integration evidence is not browser
76
171
  3DS certification; record challenge success/cancel/failure separately. Do not call
@@ -89,9 +184,11 @@ global connector credentials or broaden permissions as a runtime workaround.
89
184
  The **Enable in-game purchases** and **Show ads** switches live only on the
90
185
  game's Pricing/monetization page. Microtransactions is for products, media,
91
186
  prices, orders and integration—not a second location for those switches.
92
- 2. `uploadMedia(titleId, file, onProgress?)` reuses existing Glitch Media with
93
- trusted title/actor ownership. Attach returned `id` to `media_ids` or
94
- `branding.logo_media_id`. No scheduler or social-library post is created.
187
+ 2. Optional SDK `uploadMedia(titleId, file, onProgress?)` uses the same commerce-only
188
+ Media route and trusted title/actor ownership. Attach returned `id` to
189
+ `media_ids` or `branding.logo_media_id`. It does not populate title/game preview,
190
+ gallery, cover or social imagery. Generic/gallery/social media cannot be
191
+ relinked; upload separately via commerce. No scheduler post is created.
95
192
  3. Create a product draft using `createProduct`. Prices use integer minor units,
96
193
  not floating-point money: USD 499 means $4.99; JPY 499 means ¥499. Supported
97
194
  currencies are USD/EUR/GBP/CAD/AUD/JPY/BRL/INR/KRW; provider coverage can be
@@ -106,13 +203,44 @@ global connector credentials or broaden permissions as a runtime workaround.
106
203
  game name/accent/logo with `updateSettings`. The fixed commission is 1200bp
107
204
  (12%) of discounted pre-tax subtotal. Actual provider costs are separate.
108
205
  Taxes are separate; pending earnings are not a verified available payout.
109
- 6. Run a real approved provider sandbox purchase, verify game delivery/claim,
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.
206
+ 6. **Optional QA:** if you choose to test, use a real authorized sandbox purchase
207
+ and verified delivery/claim, then optionally call
208
+ `verifyIntegration(titleId, {order_id})`. This still requires real evidence,
209
+ not a self-certified checkbox. It is not required to enable purchases or
210
+ activate live sales. Actual provider/account/tax capability and global sales
211
+ emergency controls still apply; no live test charge is implied by setup.
113
212
 
114
213
  ## SDK4.0 administrative migration
115
214
 
215
+ ### Stripe Tax setup is a platform-account workflow
216
+
217
+ Use the [official setup instructions](https://docs.stripe.com/tax/set-up).
218
+ Glitch Checkout and `tax.settings` use the platform processing account, not the
219
+ connected account that receives game proceeds. A personal Stripe account link
220
+ or a `payout_source` change does not fix platform Tax configuration.
221
+
222
+ An unavailable payout recipient does not block otherwise-eligible customer payment
223
+ collection. Proceeds remain held under existing ledger/payout rules after the 12%
224
+ commission and actual fees. Payout onboarding is not tax setup and does not
225
+ reassign historical recipients or release old held funds automatically.
226
+
227
+ Saving `tax_mode:automatic` is a Glitch-managed preference, not self-service Tax
228
+ activation. Read `tax.status`/`missing_fields`; pending `head_office` or
229
+ `platform_tax_settings` needs Glitch platform operations/support. The operator
230
+ must configure the actual processing account with legitimate head-office details,
231
+ preset product classification/default tax behavior, applicable registrations and
232
+ separate filing/remittance setup. Supply support with title/environment and safe
233
+ status information, never invented credentials, addresses or registrations.
234
+
235
+ After that external setup, use the existing provider refresh operation and reread
236
+ the facts. MCP/REST/SDK management can read facts, save preferences and refresh;
237
+ it cannot write platform Tax settings. Optional `tax_code` is route-wide product
238
+ classification, not a registration ID; omitted/null uses the platform default
239
+ when available. Preserve requested/effective `tax_collection` modes and fallback
240
+ reasons. Active tax status does not certify registrations, filing or liability;
241
+ zero collected tax is not necessarily failure or zero tax owed. Payout onboarding
242
+ stays separate. Xsolla is distinct; do not apply Stripe-specific tax assumptions.
243
+
116
244
  ### SDK 4.0.1 additive follow-up
117
245
 
118
246
  This follow-up adds optional `configuration_ready` and `integration_verified`
@@ -314,6 +442,26 @@ and client completion are not paid/delivered proof. Call
314
442
  `reconcileCheckoutSession(titleId, sessionId, options)` to query the original
315
443
  attempt; never charge another provider after an uncertain submission.
316
444
 
445
+ ### Optional saved cards: hosted form only, rollout gated
446
+
447
+ After the `commerce_customer_bindings` migration and matching backend rollout,
448
+ new marked Stripe orders may show native optional save/remove controls inside
449
+ Glitch-hosted payment. [Provider reference](https://docs.stripe.com/payments/checkout/save-during-payment?payment-ui=embedded-page).
450
+ This adds no SDK route or game payment-method API and is not required for enabling
451
+ purchases. Do not promise availability on older deployments or legacy orders.
452
+
453
+ The server binds a customer to the Glitch user/provider/actual processing account/
454
+ environment. Same-user cross-game reuse stays within that scope. Preparing the
455
+ binding may call the provider Customer API but is not a charge; the customer and
456
+ payment payload are frozen before submission. Existing orders/retries remain
457
+ unchanged, and a deleted customer may be replaced only for a new purchase.
458
+
459
+ Saving requires the player's explicit opt-in in the hosted form. It is not
460
+ permission for off-session/autopay; later purchases require user confirmation and
461
+ may require 3DS. Cards cannot cross providers/environments. No Xsolla support is
462
+ implied, and raw card data, customer IDs or payment methods never belong in game,
463
+ admin or MCP APIs. Do not implement card storage in this SDK/game example.
464
+
317
465
  ## Verified game/account handoff
318
466
 
319
467
  After verified payment and fulfillment, `createHandoff` returns an event with
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "glitch-javascript-sdk",
3
- "version": "4.0.1",
3
+ "version": "4.1.0",
4
4
  "description": "Javascript SDK for Glitch",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -14,7 +14,7 @@
14
14
  ],
15
15
  "types": "dist/index.d.ts",
16
16
  "scripts": {
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",
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-preorder-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
20
  "test:package": "node scripts/test-package-exports.cjs && npm run test:commerce-compat",
@@ -0,0 +1,234 @@
1
+ import { AxiosPromise, AxiosRequestConfig } from 'axios';
2
+ import PreordersRoute from '../routes/PreordersRoute';
3
+ import Requests from '../util/Requests';
4
+ import Response from '../util/Response';
5
+
6
+ export type PreorderFulfillmentType = 'glitch_license' | 'platform_key';
7
+ export type PreorderOfferStatus = 'draft' | 'active' | 'paused' | 'ended' | 'archived';
8
+ export type PreorderDerivedState = 'draft' | 'available' | 'scheduled' | 'sold_out' | 'paused' | 'ended' | 'released' | 'archived';
9
+ export type PreorderPaymentStatus = 'created' | 'requires_action' | 'processing' | 'paid' | 'failed' | 'canceled' | 'refunded' | 'disputed' | 'unknown';
10
+ export type PreorderFulfillmentStatus = 'waiting_for_release' | 'ready' | 'processing' | 'fulfilled' | 'blocked_missing_build' | 'blocked_missing_key' | 'canceled' | 'failed';
11
+
12
+ export interface PreorderRequestOptions extends Pick<AxiosRequestConfig, 'signal' | 'timeout'> {}
13
+
14
+ export interface PreorderPrice {
15
+ country: string;
16
+ currency: string;
17
+ amount_minor: number;
18
+ }
19
+
20
+ export interface PreorderInventory {
21
+ available: number;
22
+ reserved: number;
23
+ delivered: number;
24
+ retired: number;
25
+ total: number;
26
+ }
27
+
28
+ export interface PreorderOfferInput {
29
+ sku: string;
30
+ platform_code: string;
31
+ platform_label: string;
32
+ fulfillment_type: PreorderFulfillmentType;
33
+ status?: PreorderOfferStatus;
34
+ sales_start_at?: string | null;
35
+ sales_end_at?: string | null;
36
+ release_at: string;
37
+ limit_total?: number | null;
38
+ max_per_user?: number;
39
+ custom_message?: string | null;
40
+ post_purchase_url?: string | null;
41
+ redeem_url?: string | null;
42
+ prices: PreorderPrice[];
43
+ }
44
+
45
+ export interface PreorderOffer extends Omit<PreorderOfferInput, 'status'> {
46
+ id: string;
47
+ title_id: string;
48
+ status: PreorderOfferStatus;
49
+ state: PreorderDerivedState;
50
+ sold: number;
51
+ reserved_or_paid: number;
52
+ remaining: number | null;
53
+ revision: number;
54
+ inventory?: PreorderInventory;
55
+ owned_count?: number;
56
+ }
57
+
58
+ export interface PreorderSettings {
59
+ enabled: boolean;
60
+ timezone: string;
61
+ readiness?: PreorderReadiness;
62
+ }
63
+
64
+ export interface PreorderCatalog {
65
+ enabled: boolean;
66
+ timezone?: string;
67
+ offers: PreorderOffer[];
68
+ }
69
+
70
+ export interface PreorderPurchaseInput {
71
+ country?: string;
72
+ currency?: string;
73
+ idempotency_key: string;
74
+ payment_method_id?: string;
75
+ payment_intent_id?: string;
76
+ }
77
+
78
+ export interface PreorderOrder {
79
+ id: string;
80
+ title_id: string;
81
+ offer_id: string;
82
+ user_id?: string;
83
+ platform_code: string;
84
+ platform_label: string;
85
+ fulfillment_type: PreorderFulfillmentType;
86
+ payment_status: PreorderPaymentStatus;
87
+ fulfillment_status: PreorderFulfillmentStatus;
88
+ currency: string;
89
+ subtotal_minor: number;
90
+ tax_minor: number;
91
+ total_minor: number;
92
+ promised_release_at: string;
93
+ current_release_at: string;
94
+ paid_at?: string;
95
+ fulfilled_at?: string;
96
+ custom_message?: string;
97
+ post_purchase_url?: string;
98
+ redeem_url?: string;
99
+ platform_key?: string;
100
+ key_masked_suffix?: string;
101
+ purchase_email?: string;
102
+ provider_reference?: string;
103
+ commission_minor?: number;
104
+ developer_share_minor?: number;
105
+ requires_action?: boolean;
106
+ client_secret?: string;
107
+ payment_intent_id?: string;
108
+ }
109
+
110
+ export interface PreorderReadinessIssue {
111
+ offer_id: string;
112
+ code: string;
113
+ [key: string]: unknown;
114
+ }
115
+
116
+ export interface PreorderReadiness {
117
+ enabled: boolean;
118
+ ready: boolean;
119
+ blockers: PreorderReadinessIssue[];
120
+ warnings: PreorderReadinessIssue[];
121
+ }
122
+
123
+ export interface PreorderAdminOrderFilters {
124
+ offer_id?: string;
125
+ payment_status?: string;
126
+ fulfillment_status?: string;
127
+ per_page?: number;
128
+ page?: number;
129
+ }
130
+
131
+ export type PreorderAdminOrderAction = 'refund' | 'reconcile' | 'fulfill' | 'resend_receipt' | 'resend_access';
132
+
133
+ class Preorders {
134
+ public static catalog(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderCatalog>> {
135
+ return Requests.processRoute(PreordersRoute.routes.catalog, undefined, { title_id }, undefined, options);
136
+ }
137
+
138
+ public static purchase(title_id: string, offer_id: string, data: PreorderPurchaseInput, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOrder>> {
139
+ return Requests.processRoute(PreordersRoute.routes.purchase, data, { title_id, offer_id }, undefined, options);
140
+ }
141
+
142
+ public static myOrders(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<{ orders: PreorderOrder[] }>> {
143
+ return Requests.processRoute(PreordersRoute.routes.myOrders, undefined, { title_id }, undefined, options);
144
+ }
145
+
146
+ public static order(title_id: string, order_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOrder>> {
147
+ return Requests.processRoute(PreordersRoute.routes.order, undefined, { title_id, order_id }, undefined, options);
148
+ }
149
+
150
+ public static refundMine(title_id: string, order_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOrder>> {
151
+ return Requests.processRoute(PreordersRoute.routes.refundMine, {}, { title_id, order_id }, undefined, options);
152
+ }
153
+
154
+ public static resendMine(title_id: string, order_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<{ resent: boolean }>> {
155
+ return Requests.processRoute(PreordersRoute.routes.resendMine, {}, { title_id, order_id }, undefined, options);
156
+ }
157
+
158
+ public static settings(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderSettings>> {
159
+ return Requests.processRoute(PreordersRoute.routes.settings, undefined, { title_id }, undefined, options);
160
+ }
161
+
162
+ public static updateSettings(title_id: string, data: Partial<Pick<PreorderSettings, 'enabled' | 'timezone'>>, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderSettings>> {
163
+ return Requests.processRoute(PreordersRoute.routes.updateSettings, data, { title_id }, undefined, options);
164
+ }
165
+
166
+ public static offers(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<{ offers: PreorderOffer[] }>> {
167
+ return Requests.processRoute(PreordersRoute.routes.offers, undefined, { title_id }, undefined, options);
168
+ }
169
+
170
+ public static offer(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>> {
171
+ return Requests.processRoute(PreordersRoute.routes.offer, undefined, { title_id, offer_id }, undefined, options);
172
+ }
173
+
174
+ public static createOffer(title_id: string, data: PreorderOfferInput, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>> {
175
+ return Requests.processRoute(PreordersRoute.routes.createOffer, data, { title_id }, undefined, options);
176
+ }
177
+
178
+ public static updateOffer(title_id: string, offer_id: string, data: PreorderOfferInput, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>> {
179
+ return Requests.processRoute(PreordersRoute.routes.updateOffer, data, { title_id, offer_id }, undefined, options);
180
+ }
181
+
182
+ public static activateOffer(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>> {
183
+ return Requests.processRoute(PreordersRoute.routes.activateOffer, {}, { title_id, offer_id }, undefined, options);
184
+ }
185
+
186
+ public static pauseOffer(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>> {
187
+ return Requests.processRoute(PreordersRoute.routes.pauseOffer, {}, { title_id, offer_id }, undefined, options);
188
+ }
189
+
190
+ public static archiveOffer(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOffer>> {
191
+ return Requests.processRoute(PreordersRoute.routes.archiveOffer, {}, { title_id, offer_id }, undefined, options);
192
+ }
193
+
194
+ public static inventory(title_id: string, offer_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderInventory>> {
195
+ return Requests.processRoute(PreordersRoute.routes.inventory, undefined, { title_id, offer_id }, undefined, options);
196
+ }
197
+
198
+ public static importKeys(title_id: string, offer_id: string, keys: string[], options?: PreorderRequestOptions): AxiosPromise<Response<{ inserted: number; duplicate_in_upload: number; duplicate_existing: number; invalid: number; inventory: PreorderInventory }>> {
199
+ return Requests.processRoute(PreordersRoute.routes.importKeys, { keys }, { title_id, offer_id }, undefined, options);
200
+ }
201
+
202
+ public static importKeyFile<T>(title_id: string, offer_id: string, file: File | Blob): AxiosPromise<Response<T>> {
203
+ const url = PreordersRoute.routes.importKeys.url
204
+ .replace('{title_id}', title_id)
205
+ .replace('{offer_id}', offer_id);
206
+ return Requests.uploadFile<T>(url, 'key_file', file, {}, undefined, undefined, { excludeCommunityContext: true });
207
+ }
208
+
209
+ public static retireKey(title_id: string, offer_id: string, key_id: string, reason: string, options?: PreorderRequestOptions): AxiosPromise<Response<{ id: string; status: string; masked_suffix: string }>> {
210
+ return Requests.processRoute(PreordersRoute.routes.retireKey, { reason }, { title_id, offer_id, key_id }, undefined, options);
211
+ }
212
+
213
+ public static adminOrders(title_id: string, filters?: PreorderAdminOrderFilters, options?: PreorderRequestOptions): AxiosPromise<Response<{ orders: PreorderOrder[]; pagination: Record<string, number> }>> {
214
+ return Requests.processRoute(PreordersRoute.routes.adminOrders, undefined, { title_id }, filters, options);
215
+ }
216
+
217
+ public static readiness(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderReadiness>> {
218
+ return Requests.processRoute(PreordersRoute.routes.readiness, undefined, { title_id }, undefined, options);
219
+ }
220
+
221
+ public static adminOrderAction(title_id: string, order_id: string, action: PreorderAdminOrderAction, options?: PreorderRequestOptions): AxiosPromise<Response<PreorderOrder>> {
222
+ return Requests.processRoute(PreordersRoute.routes.adminOrderAction, {}, { title_id, order_id, action }, undefined, options);
223
+ }
224
+
225
+ public static mcpCapabilities<T = unknown>(title_id: string, options?: PreorderRequestOptions): AxiosPromise<Response<T>> {
226
+ return Requests.processRoute(PreordersRoute.routes.mcpCapabilities, undefined, { title_id }, undefined, options);
227
+ }
228
+
229
+ public static mcpOperation<T = unknown>(title_id: string, operation: string, argumentsData: Record<string, unknown> = {}, options?: PreorderRequestOptions): AxiosPromise<Response<T>> {
230
+ return Requests.processRoute(PreordersRoute.routes.mcpOperation, { arguments: argumentsData }, { title_id, operation }, undefined, options);
231
+ }
232
+ }
233
+
234
+ export default Preorders;