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
|
@@ -3,13 +3,17 @@ import MicrotransactionsRoute from '../routes/MicrotransactionsRoute';
|
|
|
3
3
|
import Requests from '../util/Requests';
|
|
4
4
|
|
|
5
5
|
export type MicrotransactionEnvironment = 'sandbox' | 'live';
|
|
6
|
+
export type MicrotransactionProviderName = 'stripe' | 'xsolla';
|
|
6
7
|
export type MicrotransactionProductType = 'durable' | 'consumable' | 'currency' | 'bundle' | 'pass';
|
|
7
8
|
export type MicrotransactionCurrency = 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD' | 'JPY' | 'BRL' | 'INR' | 'KRW';
|
|
8
9
|
export type MicrotransactionProductStatus = 'draft' | 'active' | 'archived';
|
|
9
|
-
export type MicrotransactionPaymentStatus = 'created' | 'action_required' | 'pending' | 'unknown' | 'paid' | 'failed' | 'canceled' | 'refund_pending' | 'partially_refunded' | 'refunded' | 'disputed' | 'quarantined';
|
|
10
|
+
export type MicrotransactionPaymentStatus = 'created' | 'action_required' | 'pending' | 'unknown' | 'paid' | 'failed' | 'canceled' | 'refund_pending' | 'partially_refunded' | 'refunded' | 'disputed' | 'quarantined' | 'refund_review';
|
|
11
|
+
export type MicrotransactionRefundStatus = 'requested' | 'linked' | 'unknown' | 'pending' | 'submitted' | 'succeeded' | 'failed' | 'canceled';
|
|
12
|
+
export type MicrotransactionDeliveryStatus = 'pending' | 'retrying' | 'processing' | 'acknowledged' | 'failed' | 'superseded';
|
|
13
|
+
export type MicrotransactionPayoutStatus = 'pending' | 'transferred' | 'bank_paid' | 'bank_pending' | 'bank_failed' | 'transfer_reversed';
|
|
10
14
|
export type MicrotransactionFulfillmentStatus = 'not_ready' | 'pending' | 'delivered' | 'retrying' | 'failed' | 'revoked' | 'partially_recovered';
|
|
11
15
|
export type MicrotransactionAbility = 'commerce:read' | 'commerce:write' | 'commerce:finance' | 'commerce:fulfill';
|
|
12
|
-
export type MicrotransactionErrorCode = 'authentication_required' | 'permission_denied' | '
|
|
16
|
+
export type MicrotransactionErrorCode = 'authentication_required' | 'permission_denied' | 'not_found' | 'not_eligible' | 'quote_expired' | 'already_owned' | 'idempotency_conflict' | 'payment_unknown' | 'rate_limited' | 'invalid_revenue_configuration' | 'fulfillment_pending' | 'provider_unavailable';
|
|
13
17
|
|
|
14
18
|
/** The backend's JSON envelope; Axios returns this envelope in response.data. */
|
|
15
19
|
export interface MicrotransactionResponse<T> { data: T; message?: string; success?: boolean; }
|
|
@@ -24,6 +28,27 @@ export interface MicrotransactionSessionOptions extends MicrotransactionRequestO
|
|
|
24
28
|
checkoutToken: string;
|
|
25
29
|
}
|
|
26
30
|
export interface MicrotransactionEnvironmentFilter { environment?: MicrotransactionEnvironment; }
|
|
31
|
+
/** Catalog discovery defaults to 200 records per page; absence on page one is not proof a SKU is unused. */
|
|
32
|
+
export interface MicrotransactionProductListFilters {
|
|
33
|
+
page?: number;
|
|
34
|
+
per_page?: number;
|
|
35
|
+
status?: MicrotransactionProductStatus;
|
|
36
|
+
/** Exact SKU, not a substring search. */
|
|
37
|
+
sku?: string;
|
|
38
|
+
}
|
|
39
|
+
/** Administrative lists default to page 1 / 25 records and are scoped to the authorized title. */
|
|
40
|
+
export interface MicrotransactionManagementListFilters extends MicrotransactionEnvironmentFilter {
|
|
41
|
+
page?: number;
|
|
42
|
+
per_page?: number;
|
|
43
|
+
status?: string;
|
|
44
|
+
}
|
|
45
|
+
export interface MicrotransactionOrderListFilters extends MicrotransactionManagementListFilters { product_id?: string; status?: MicrotransactionPaymentStatus; payment_status?: MicrotransactionPaymentStatus; }
|
|
46
|
+
export interface MicrotransactionRelatedListFilters extends MicrotransactionManagementListFilters { order_id?: string; }
|
|
47
|
+
export interface MicrotransactionRefundListFilters extends MicrotransactionRelatedListFilters { status?: MicrotransactionRefundStatus; }
|
|
48
|
+
export interface MicrotransactionDeliveryListFilters extends MicrotransactionRelatedListFilters { status?: MicrotransactionDeliveryStatus; }
|
|
49
|
+
export interface MicrotransactionPayoutListFilters extends MicrotransactionRelatedListFilters { status?: MicrotransactionPayoutStatus; }
|
|
50
|
+
/** @deprecated Optional compatibility field only; no confirmation or human-approval gate is enforced. */
|
|
51
|
+
export interface MicrotransactionLegacyConfirmation { confirm?: boolean; }
|
|
27
52
|
/** Self-only purchase-history filters. Identity comes from authentication, never a user_id argument. */
|
|
28
53
|
export interface MicrotransactionMyPurchasesFilters extends MicrotransactionEnvironmentFilter {
|
|
29
54
|
/** Page number, integer 1–10000. Defaults to 1; ordering is created_at DESC, id DESC. */
|
|
@@ -80,7 +105,7 @@ export interface MicrotransactionProductInput {
|
|
|
80
105
|
starts_at?: string | null;
|
|
81
106
|
ends_at?: string | null;
|
|
82
107
|
max_per_order?: number;
|
|
83
|
-
/**
|
|
108
|
+
/** @deprecated Ignored compatibility field. Title authorization and immutable-data validation remain required. */
|
|
84
109
|
confirm?: boolean;
|
|
85
110
|
}
|
|
86
111
|
export interface MicrotransactionProduct extends Omit<MicrotransactionProductInput, 'confirm' | 'status' | 'media_ids'> {
|
|
@@ -93,19 +118,157 @@ export interface MicrotransactionProduct extends Omit<MicrotransactionProductInp
|
|
|
93
118
|
created_at: string;
|
|
94
119
|
updated_at: string;
|
|
95
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
|
+
}
|
|
96
132
|
export interface MicrotransactionProvider {
|
|
97
|
-
provider:
|
|
133
|
+
provider: MicrotransactionProviderName;
|
|
98
134
|
environment: MicrotransactionEnvironment;
|
|
99
135
|
configured: boolean;
|
|
100
|
-
|
|
136
|
+
/** Actual external provider/account capability, not a manual approval flag. */
|
|
137
|
+
available: boolean;
|
|
138
|
+
enabled: boolean;
|
|
139
|
+
priority: number;
|
|
101
140
|
countries: string[];
|
|
102
141
|
currencies: string[];
|
|
142
|
+
minimum_amounts: Record<string, number>;
|
|
103
143
|
channels: string[];
|
|
104
|
-
|
|
144
|
+
payment_methods: string[];
|
|
145
|
+
configuration: MicrotransactionProviderConfiguration;
|
|
146
|
+
account: { id: string; country: string | null; charges_enabled: boolean; payouts_enabled: boolean; requirements_due: string[]; merchant_name?: string | null } | null;
|
|
147
|
+
/** The game's payout target. Do not substitute the platform processing account's payouts_enabled. */
|
|
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[] };
|
|
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[];
|
|
154
|
+
reasons: string[];
|
|
155
|
+
checked_at: string | null;
|
|
156
|
+
revision?: number;
|
|
157
|
+
}
|
|
158
|
+
export interface MicrotransactionProviderSku {
|
|
159
|
+
/** Provider SKU, 1–100 characters. */
|
|
160
|
+
sku: string;
|
|
161
|
+
currency: MicrotransactionCurrency;
|
|
162
|
+
amount_minor: number;
|
|
163
|
+
}
|
|
164
|
+
export interface MicrotransactionProviderConfiguration {
|
|
165
|
+
/** Requested configuration. Explicit disabled is sandbox-only; pending-setup fallback does not change live configuration to disabled. */
|
|
166
|
+
tax_mode: 'automatic' | 'disabled';
|
|
167
|
+
/** Stripe tax code txcd_ followed by exactly eight digits. */
|
|
168
|
+
tax_code: string | null;
|
|
169
|
+
payout_source: 'platform' | 'user' | 'community' | 'managed';
|
|
170
|
+
/** Xsolla public project ID, 1–20 decimal digits. */
|
|
171
|
+
project_id: string | null;
|
|
172
|
+
/** Maximum 200 mappings. */
|
|
173
|
+
sku_map: Record<string, MicrotransactionProviderSku>;
|
|
174
|
+
}
|
|
175
|
+
/** Developer preferences and an optional new owned Xsolla webhook secret only; never platform credentials, arbitrary payees, or availability facts. */
|
|
176
|
+
export interface MicrotransactionProviderInput extends Partial<MicrotransactionProviderConfiguration>, MicrotransactionLegacyConfirmation {
|
|
177
|
+
environment: MicrotransactionEnvironment;
|
|
178
|
+
enabled?: boolean;
|
|
179
|
+
priority?: number;
|
|
180
|
+
countries?: string[];
|
|
181
|
+
currencies?: MicrotransactionCurrency[];
|
|
182
|
+
minimum_amounts?: Record<string, number>;
|
|
183
|
+
/** Write-only NEW owned Xsolla project secret, 16–512 chars, finance scope. Never a platform API key or MCP token; never returned/logged or put in game code. Existing platform/historical bindings cannot be overwritten. */
|
|
184
|
+
webhook_secret?: string;
|
|
185
|
+
}
|
|
186
|
+
export interface MicrotransactionProviderOnboardingInput extends MicrotransactionLegacyConfirmation {
|
|
187
|
+
environment: MicrotransactionEnvironment;
|
|
188
|
+
country: string;
|
|
189
|
+
/** Stable caller-created key. Reuse with identical input after uncertain retries; never generate inside a retry. */
|
|
190
|
+
idempotency_key: string;
|
|
191
|
+
}
|
|
192
|
+
export interface MicrotransactionProviderOnboarding {
|
|
193
|
+
title_id: string;
|
|
194
|
+
provider: 'stripe';
|
|
195
|
+
environment: MicrotransactionEnvironment;
|
|
196
|
+
account_id: string;
|
|
197
|
+
/** Single-use provider onboarding URL on connect.stripe.com; do not log or persist it. */
|
|
198
|
+
onboarding_url: string;
|
|
199
|
+
expires_at: string;
|
|
200
|
+
status: 'requires_provider_onboarding';
|
|
201
|
+
reused: boolean;
|
|
202
|
+
}
|
|
203
|
+
export interface MicrotransactionDeliverySettings {
|
|
204
|
+
title_id: string;
|
|
205
|
+
environment: MicrotransactionEnvironment;
|
|
206
|
+
enabled: boolean;
|
|
207
|
+
url: string | null;
|
|
208
|
+
signature_algorithm: 'ed25519' | 'hmac-sha256';
|
|
209
|
+
/** Public verification material only. The private signing key never leaves the server. */
|
|
210
|
+
verification_public_key: string | null;
|
|
211
|
+
key_id: string | null;
|
|
212
|
+
revision: number;
|
|
213
|
+
configured: boolean;
|
|
214
|
+
}
|
|
215
|
+
export interface MicrotransactionDeliverySettingsInput extends MicrotransactionLegacyConfirmation {
|
|
216
|
+
environment: MicrotransactionEnvironment;
|
|
217
|
+
enabled?: boolean;
|
|
218
|
+
url?: string | null;
|
|
219
|
+
}
|
|
220
|
+
export interface MicrotransactionDelivery {
|
|
221
|
+
id: string;
|
|
222
|
+
order_id: string;
|
|
223
|
+
event_type: string;
|
|
224
|
+
status: MicrotransactionDeliveryStatus;
|
|
225
|
+
attempts: number;
|
|
226
|
+
next_attempt_at: string | null;
|
|
227
|
+
acknowledged_at: string | null;
|
|
228
|
+
created_at: string;
|
|
229
|
+
updated_at: string;
|
|
230
|
+
}
|
|
231
|
+
/** Replay/acknowledgement return only this safe subset, not the list's timestamps. */
|
|
232
|
+
export type MicrotransactionDeliveryResult = Pick<MicrotransactionDelivery, 'id' | 'order_id' | 'status' | 'event_type' | 'attempts' | 'acknowledged_at'>;
|
|
233
|
+
export interface MicrotransactionRefundRecord {
|
|
234
|
+
id: string;
|
|
235
|
+
order_id: string;
|
|
236
|
+
status: MicrotransactionRefundStatus;
|
|
237
|
+
amount_minor: number;
|
|
238
|
+
reason: string;
|
|
239
|
+
idempotency_key: string | null;
|
|
240
|
+
record_type: 'request' | 'execution';
|
|
241
|
+
execution_refund_id: string | null;
|
|
242
|
+
execution_status: MicrotransactionRefundStatus | null;
|
|
243
|
+
request_resolution: 'linked_to_execution' | 'not_executed' | null;
|
|
244
|
+
order_refunded_minor: number | null;
|
|
245
|
+
failure_code: string | null;
|
|
246
|
+
created_at: string;
|
|
247
|
+
updated_at: string;
|
|
248
|
+
}
|
|
249
|
+
export interface MicrotransactionPayout {
|
|
250
|
+
id: string;
|
|
251
|
+
order_id: string;
|
|
252
|
+
status: MicrotransactionPayoutStatus;
|
|
253
|
+
amount_minor: number;
|
|
254
|
+
provider_reference: string | null;
|
|
255
|
+
created_at: string;
|
|
256
|
+
updated_at: string;
|
|
257
|
+
}
|
|
258
|
+
export interface MicrotransactionRefundInput extends MicrotransactionLegacyConfirmation {
|
|
259
|
+
reason: string;
|
|
260
|
+
amount_minor?: number;
|
|
261
|
+
/** REQUIRED stable operation key, scoped to title/order. Reuse identical input on retry; changes conflict. */
|
|
262
|
+
idempotency_key: string;
|
|
105
263
|
}
|
|
106
264
|
export interface MicrotransactionReadiness {
|
|
107
265
|
status: 'disabled' | 'draft' | 'sandbox' | 'ready' | 'live' | 'degraded' | 'suspended';
|
|
266
|
+
/** Configuration readiness only; not proof of payment, delivery, claim or browser 3DS. */
|
|
108
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;
|
|
109
272
|
blockers: string[];
|
|
110
273
|
providers: MicrotransactionProvider[];
|
|
111
274
|
commission_basis_points: 1200;
|
|
@@ -122,8 +285,9 @@ export interface MicrotransactionSettingsInput {
|
|
|
122
285
|
currencies?: MicrotransactionCurrency[];
|
|
123
286
|
branding?: Omit<MicrotransactionBranding, 'logo_media'>;
|
|
124
287
|
support_email?: string | null;
|
|
288
|
+
/** @deprecated Legacy delivery alias requiring BOTH commerce:write and commerce:fulfill; prefer updateDeliverySettings/getDeliverySettings. */
|
|
125
289
|
webhook_url?: string | null;
|
|
126
|
-
/**
|
|
290
|
+
/** @deprecated Ignored compatibility field. Authorized title editors save directly; actual provider/sales restrictions remain. */
|
|
127
291
|
confirm?: boolean;
|
|
128
292
|
}
|
|
129
293
|
export interface MicrotransactionSettings extends Omit<Required<MicrotransactionSettingsInput>, 'confirm'> {
|
|
@@ -199,8 +363,17 @@ export interface MicrotransactionOrder {
|
|
|
199
363
|
paid_at: string | null;
|
|
200
364
|
refunded_minor: number;
|
|
201
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;
|
|
202
368
|
entitlements?: MicrotransactionEntitlement[];
|
|
203
369
|
}
|
|
370
|
+
export interface MicrotransactionOrderDetail extends MicrotransactionOrder {
|
|
371
|
+
/** Optional, permission-scoped management relationships. Omission is not proof no records exist. */
|
|
372
|
+
refunds?: Array<Pick<MicrotransactionRefundRecord, 'id' | 'order_id' | 'status'> & Partial<MicrotransactionRefundRecord>>;
|
|
373
|
+
deliveries?: MicrotransactionDelivery[];
|
|
374
|
+
payouts?: Array<Pick<MicrotransactionPayout, 'id' | 'order_id' | 'status'> & Partial<MicrotransactionPayout>>;
|
|
375
|
+
financial_details_included?: boolean;
|
|
376
|
+
}
|
|
204
377
|
export type MicrotransactionGrantUsageStatus = 'unused' | 'partially_used' | 'used_up' | 'owned' | 'expired' | 'revoked' | 'not_delivered' | 'unavailable';
|
|
205
378
|
|
|
206
379
|
/** One purchase's server-calculated grant lot, not the player's aggregate inventory balance. */
|
|
@@ -339,7 +512,7 @@ export interface MicrotransactionConsumeInput {
|
|
|
339
512
|
action_id: string;
|
|
340
513
|
environment: MicrotransactionEnvironment;
|
|
341
514
|
}
|
|
342
|
-
export interface MicrotransactionRefund { refund_id: string; status:
|
|
515
|
+
export interface MicrotransactionRefund { refund_id: string; status: MicrotransactionRefundStatus; order_id: string; idempotency_key: string; failure_code: string | null; refund_allocation?: 'pro_rata_all_grants'; }
|
|
343
516
|
export interface MicrotransactionRefundRequest { id: string; order_id: string; status: 'requested'; }
|
|
344
517
|
export interface MicrotransactionEarnings {
|
|
345
518
|
currency_balances: Array<{
|
|
@@ -352,14 +525,16 @@ export interface MicrotransactionEarnings {
|
|
|
352
525
|
payouts_enabled: boolean;
|
|
353
526
|
reserve_days?: number;
|
|
354
527
|
}
|
|
355
|
-
export type MicrotransactionOperation = 'settings.get' | 'settings.update' | 'products.list' | 'products.create' | 'products.update' | 'products.archive' | 'providers.list' | 'readiness.get' | 'orders.list' | 'orders.get' | 'earnings.get' | 'refunds.request' | 'deliveries.replay' | 'integration.get' | 'integration.verify';
|
|
528
|
+
export type MicrotransactionOperation = 'settings.get' | 'settings.update' | 'products.list' | 'products.create' | 'products.update' | 'products.archive' | 'providers.list' | 'providers.update' | 'providers.refresh' | 'providers.onboarding' | 'readiness.get' | 'orders.list' | 'orders.get' | 'orders.reconcile' | 'earnings.get' | 'refunds.list' | 'refunds.get' | 'refunds.create' | 'refunds.request' | 'refunds.reconcile' | 'delivery.settings.get' | 'delivery.settings.update' | 'deliveries.list' | 'deliveries.replay' | 'deliveries.acknowledge' | 'payouts.list' | 'integration.get' | 'integration.verify';
|
|
356
529
|
export interface MicrotransactionOperationCapability {
|
|
357
530
|
operation: MicrotransactionOperation;
|
|
358
531
|
description: string;
|
|
359
532
|
ability: MicrotransactionAbility;
|
|
360
533
|
input_schema: Record<string, unknown>;
|
|
361
|
-
|
|
362
|
-
|
|
534
|
+
http_method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
|
|
535
|
+
mutates: boolean;
|
|
536
|
+
requires_confirmation: false;
|
|
537
|
+
requires_human_approval: false;
|
|
363
538
|
examples: Array<Record<string, unknown>>;
|
|
364
539
|
output_description: string;
|
|
365
540
|
}
|
|
@@ -371,8 +546,9 @@ export interface MicrotransactionCapabilities {
|
|
|
371
546
|
}
|
|
372
547
|
|
|
373
548
|
/**
|
|
374
|
-
* Provider-neutral, title-scoped commerce.
|
|
375
|
-
*
|
|
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
|
|
376
552
|
* tokens cannot authorize money, ownership, refunds, or catalog changes.
|
|
377
553
|
*
|
|
378
554
|
* Each result preserves payment versus fulfillment versus settlement. Redirects
|
|
@@ -387,46 +563,83 @@ class Microtransactions {
|
|
|
387
563
|
*/
|
|
388
564
|
static uploadMedia(title_id: string, media: File | Blob, onUploadProgress?: (event: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'>): AxiosPromise<MicrotransactionResponse<MicrotransactionMedia>> {
|
|
389
565
|
if (!/^[A-Za-z0-9_:-]+$/.test(title_id)) throw new Error('Invalid commerce title identifier.');
|
|
390
|
-
return Requests.uploadFile<MicrotransactionMedia>(MicrotransactionsRoute.routes.uploadMedia.url.replace('{title_id}', encodeURIComponent(title_id)), 'media', media, {}, undefined, onUploadProgress, options);
|
|
566
|
+
return Requests.uploadFile<MicrotransactionMedia>(MicrotransactionsRoute.routes.uploadMedia.url.replace('{title_id}', encodeURIComponent(title_id)), 'media', media, {}, undefined, onUploadProgress, { ...options, excludeCommunityContext: true });
|
|
391
567
|
}
|
|
392
568
|
/** Same title-authorized Media pipeline using the caller's MCP credential and commerce:write ability. */
|
|
393
569
|
static mcpUploadMedia(title_id: string, media: File | Blob, onUploadProgress?: (event: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'>): AxiosPromise<MicrotransactionResponse<MicrotransactionMedia>> {
|
|
394
570
|
if (!/^[A-Za-z0-9_:-]+$/.test(title_id)) throw new Error('Invalid commerce title identifier.');
|
|
395
|
-
return Requests.uploadFile<MicrotransactionMedia>(MicrotransactionsRoute.routes.mcpUploadMedia.url.replace('{title_id}', encodeURIComponent(title_id)), 'media', media, {}, undefined, onUploadProgress, options);
|
|
571
|
+
return Requests.uploadFile<MicrotransactionMedia>(MicrotransactionsRoute.routes.mcpUploadMedia.url.replace('{title_id}', encodeURIComponent(title_id)), 'media', media, {}, undefined, onUploadProgress, { ...options, excludeCommunityContext: true });
|
|
396
572
|
}
|
|
397
573
|
/** Admin settings, including immutable 1200bp commission and readiness blockers. */
|
|
398
574
|
static settings(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionSettings>('settings', title_id, undefined, {}, undefined, options); }
|
|
399
575
|
/** Atomic policy update. Sandbox/off by default. Cannot disable the final working revenue model. */
|
|
400
576
|
static updateSettings(title_id: string, data: MicrotransactionSettingsInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionSettings>('updateSettings', title_id, data, {}, undefined, options); }
|
|
401
|
-
/** Read-only country/provider
|
|
577
|
+
/** Read-only current country/provider capability and revenue readiness; never fabricates availability. */
|
|
402
578
|
static readiness(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionReadiness>('readiness', title_id, undefined, {}, undefined, options); }
|
|
403
|
-
/**
|
|
404
|
-
static listProducts(title_id: string, options?: MicrotransactionRequestOptions)
|
|
579
|
+
/** Paginated admin catalog including drafts/archives. Default 200, per_page 1–200/page 1–10000. Use exact sku to resolve uncertain creates. */
|
|
580
|
+
static listProducts(title_id: string, params?: MicrotransactionProductListFilters, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{ products: MicrotransactionProduct[]; pagination: MicrotransactionPurchasePagination }>>;
|
|
581
|
+
/** @deprecated Compatibility overload for the earlier second-argument request options. */
|
|
582
|
+
static listProducts(title_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{ products: MicrotransactionProduct[]; pagination: MicrotransactionPurchasePagination }>>;
|
|
583
|
+
static listProducts(title_id: string, paramsOrOptions?: MicrotransactionProductListFilters | MicrotransactionRequestOptions, options?: MicrotransactionRequestOptions) {
|
|
584
|
+
const legacy = paramsOrOptions && ('playerToken' in paramsOrOptions || 'signal' in paramsOrOptions || 'timeout' in paramsOrOptions);
|
|
585
|
+
return this.call<{ products: MicrotransactionProduct[]; pagination: MicrotransactionPurchasePagination }>('products', title_id, undefined, {}, legacy ? undefined : paramsOrOptions, legacy ? paramsOrOptions as MicrotransactionRequestOptions : options);
|
|
586
|
+
}
|
|
405
587
|
/** Save a catalog product. Prices use integer minor units and attached media must belong to the title. */
|
|
406
588
|
static createProduct(title_id: string, data: MicrotransactionProductInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProduct>('createProduct', title_id, data, {}, undefined, options); }
|
|
407
589
|
/** Update a product version. Existing order snapshots remain unchanged. */
|
|
408
590
|
static updateProduct(title_id: string, product_id: string, data: Partial<MicrotransactionProductInput>, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProduct>('updateProduct', title_id, data, { product_id }, undefined, options); }
|
|
409
|
-
/**
|
|
410
|
-
static archiveProduct(title_id: string, product_id: string, data:
|
|
411
|
-
/**
|
|
412
|
-
static providers(title_id: string, options?: MicrotransactionRequestOptions)
|
|
591
|
+
/** Direct authorized archive. Never deletes financial history or bypasses the last-revenue-model rule. */
|
|
592
|
+
static archiveProduct(title_id: string, product_id: string, data: MicrotransactionLegacyConfirmation = {}, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProduct>('archiveProduct', title_id, data, { product_id }, undefined, options); }
|
|
593
|
+
/** Actual provider configuration/capability facts; no credentials or manual approval flag. */
|
|
594
|
+
static providers(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{ providers: MicrotransactionProvider[] }>>;
|
|
595
|
+
/** @deprecated Compatibility overload for the earlier second-argument request options. */
|
|
596
|
+
static providers(title_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{ providers: MicrotransactionProvider[] }>>;
|
|
597
|
+
static providers(title_id: string, paramsOrOptions?: MicrotransactionEnvironmentFilter | MicrotransactionRequestOptions, options?: MicrotransactionRequestOptions) {
|
|
598
|
+
const legacy = paramsOrOptions && !('environment' in paramsOrOptions) && ('playerToken' in paramsOrOptions || 'signal' in paramsOrOptions || 'timeout' in paramsOrOptions);
|
|
599
|
+
return this.call<{ providers: MicrotransactionProvider[] }>('providers', title_id, undefined, {}, legacy ? undefined : paramsOrOptions, legacy ? paramsOrOptions as MicrotransactionRequestOptions : options);
|
|
600
|
+
}
|
|
601
|
+
/** Direct commerce:finance configuration. Saving preferences does not fabricate external capability; inspect available/reasons. */
|
|
602
|
+
static updateProvider(title_id: string, provider: MicrotransactionProviderName, data: MicrotransactionProviderInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProvider>('updateProvider', title_id, data, { provider }, undefined, options); }
|
|
603
|
+
/** Refresh authenticated external provider facts. May update cached state; never creates a payment or invents eligibility. */
|
|
604
|
+
static refreshProvider(title_id: string, provider: MicrotransactionProviderName, data: { environment: MicrotransactionEnvironment }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProvider>('refreshProvider', title_id, data, { provider }, undefined, options); }
|
|
605
|
+
/** Start/reuse owned Stripe Connect onboarding with one stable key. Provider KYC is factual setup, not a Glitch approval workflow. */
|
|
606
|
+
static createProviderOnboarding(title_id: string, data: MicrotransactionProviderOnboardingInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProviderOnboarding>('createProviderOnboarding', title_id, data, {}, undefined, options); }
|
|
607
|
+
/** Read title/environment delivery settings and the Ed25519 PUBLIC verification key. */
|
|
608
|
+
static getDeliverySettings(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionDeliverySettings>('deliverySettings', title_id, undefined, {}, params, options); }
|
|
609
|
+
/** Direct commerce:fulfill setup. Private/metadata network targets and private-key inputs remain forbidden. */
|
|
610
|
+
static updateDeliverySettings(title_id: string, data: MicrotransactionDeliverySettingsInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionDeliverySettings>('updateDeliverySettings', title_id, data, {}, undefined, options); }
|
|
611
|
+
/** Discover safe event IDs/statuses before replay or acknowledge. Page 1–10000, per_page 1–100, default 25. */
|
|
612
|
+
static listDeliveries(title_id: string, params?: MicrotransactionDeliveryListFilters, options?: MicrotransactionRequestOptions) { return this.call<{ deliveries: MicrotransactionDelivery[]; pagination: MicrotransactionPurchasePagination }>('deliveries', title_id, undefined, {}, params, options); }
|
|
613
|
+
/** Financially scoped refund operation discovery; pending/unknown is not completed. */
|
|
614
|
+
static listRefunds(title_id: string, params?: MicrotransactionRefundListFilters, options?: MicrotransactionRequestOptions) { return this.call<{ refunds: MicrotransactionRefundRecord[]; pagination: MicrotransactionPurchasePagination }>('refunds', title_id, undefined, {}, params, options); }
|
|
615
|
+
/** Inspect one same-title refund operation. */
|
|
616
|
+
static getRefund(title_id: string, refund_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionRefundRecord>('refundDetail', title_id, undefined, { refund_id }, undefined, options); }
|
|
617
|
+
/** Query/retry the original persisted refund with its existing identity, never generate a new refund key. */
|
|
618
|
+
static reconcileRefund(title_id: string, refund_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionRefundRecord>('reconcileRefund', title_id, {}, { refund_id }, undefined, options); }
|
|
619
|
+
/** Discover provider transfer/payout records; transferred funds are not automatically a verified bank payout. */
|
|
620
|
+
static listPayouts(title_id: string, params?: MicrotransactionPayoutListFilters, options?: MicrotransactionRequestOptions) { return this.call<{ payouts: MicrotransactionPayout[]; pagination: MicrotransactionPurchasePagination }>('payouts', title_id, undefined, {}, params, options); }
|
|
413
621
|
/** Admin read of separate-currency balances; pending is not withdrawable revenue. */
|
|
414
622
|
static earnings(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionEarnings>('earnings', title_id, undefined, {}, params, options); }
|
|
415
|
-
/** Admin
|
|
416
|
-
static listOrders(title_id: string, params?:
|
|
623
|
+
/** Admin paginated redacted orders. Page 1–10000/per_page 1–100 (default 25); own-player history is separate. */
|
|
624
|
+
static listOrders(title_id: string, params?: MicrotransactionOrderListFilters, options?: MicrotransactionRequestOptions) { return this.call<{ orders: MicrotransactionOrder[]; pagination: MicrotransactionPurchasePagination }>('orders', title_id, undefined, {}, params, options); }
|
|
417
625
|
/** Owner JWT/scoped player token or title admin. An arbitrary order UUID grants no access. */
|
|
418
|
-
static getOrder(title_id: string, order_id: string, options?: MicrotransactionRequestOptions) { return this.call<
|
|
419
|
-
/**
|
|
420
|
-
static
|
|
626
|
+
static getOrder(title_id: string, order_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionOrderDetail>('order', title_id, undefined, { order_id }, undefined, options); }
|
|
627
|
+
/** Financially scoped original-provider reconciliation. Does not reroute or start a different purchase. */
|
|
628
|
+
static reconcileOrder(title_id: string, order_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionOrderDetail>('reconcileOrder', title_id, {}, { order_id }, undefined, options); }
|
|
629
|
+
/** Direct commerce:finance refund. REQUIRED stable idempotency_key; omission is an error, never auto-filled. Same-key changed input conflicts. */
|
|
630
|
+
static refundOrder(title_id: string, order_id: string, data: MicrotransactionRefundInput, options?: MicrotransactionRequestOptions) {
|
|
631
|
+
if (typeof data.idempotency_key !== 'string' || data.idempotency_key.length < 16 || data.idempotency_key.length > 128) throw new Error('A stable 16–128 character refund idempotency_key is required. Reuse it on retry.');
|
|
632
|
+
return this.call<MicrotransactionRefund>('refund', title_id, data, { order_id }, undefined, options);
|
|
633
|
+
}
|
|
421
634
|
/** Replay the same immutable event. Receiver must deduplicate event_id. This cannot mint goods. */
|
|
422
|
-
static replayDelivery(title_id: string, delivery_id: string, data:
|
|
423
|
-
/**
|
|
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); }
|
|
636
|
+
/** Guest catalog on the exact approved game Origin. Sandbox requires enabled sandbox settings; the backend enforces environment policy. */
|
|
424
637
|
static catalog(title_id: string, params?: MicrotransactionCatalogFilter, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionCatalog>('catalog', title_id, undefined, {}, params, options); }
|
|
425
638
|
/** User-authenticated quote. Clients select product/quantity, never monetary values or seller accounts. */
|
|
426
639
|
static createQuote(title_id: string, data: MicrotransactionPurchaseInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionQuote>('createQuote', title_id, data, {}, undefined, options); }
|
|
427
|
-
/**
|
|
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. */
|
|
428
641
|
static createCheckoutSession(title_id: string, data: MicrotransactionCheckoutSessionInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionCreatedCheckoutSession>('createCheckoutSession', title_id, data, {}, undefined, options); }
|
|
429
|
-
/**
|
|
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. */
|
|
430
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); }
|
|
431
644
|
/** Read the session using its limited capability. Cannot mutate user identity or declare payment. */
|
|
432
645
|
static getCheckoutSession(title_id: string, session_id: string, options: MicrotransactionSessionOptions) { return this.call<MicrotransactionCheckoutSession>('checkoutSession', title_id, undefined, { session_id }, undefined, options); }
|
|
@@ -452,7 +665,7 @@ class Microtransactions {
|
|
|
452
665
|
*/
|
|
453
666
|
static restoreHandoff(title_id: string, data: { order_id: string; return_origin: string; nonce: string }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionHandoff>('restoreHandoff', title_id, data, {}, undefined, options); }
|
|
454
667
|
/** Record integration proof from a genuinely paid, fulfilled sandbox order with a claimed game handoff. */
|
|
455
|
-
static verifyIntegration(title_id: string, data: { order_id: string; confirm
|
|
668
|
+
static verifyIntegration(title_id: string, data: { order_id: string; confirm?: boolean }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionReadiness>('verifyIntegration', title_id, data, {}, undefined, options); }
|
|
456
669
|
/** Restore authoritative durable ownership/current consumable balances, never mutable cloud-save balances. */
|
|
457
670
|
static listEntitlements(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions) { return this.call<{ entitlements: MicrotransactionEntitlement[] }>('entitlements', title_id, undefined, {}, params, options); }
|
|
458
671
|
/**
|
|
@@ -480,11 +693,11 @@ class Microtransactions {
|
|
|
480
693
|
/** Owning user asks support to review a refund. This does not execute payment reversal. */
|
|
481
694
|
static requestRefund(title_id: string, data: { order_id: string; reason: string }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionRefundRequest>('requestRefund', title_id, data, {}, undefined, options); }
|
|
482
695
|
/** Trusted title server with commerce:fulfill or admin JWT acknowledges the immutable event. */
|
|
483
|
-
static acknowledgeDelivery(title_id: string, delivery_id: string, data: { event_id: string }, options?: MicrotransactionRequestOptions) { return this.call<
|
|
484
|
-
/** Title MCP token, never a runtime install token. Describes
|
|
696
|
+
static acknowledgeDelivery(title_id: string, delivery_id: string, data: { event_id: string }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionDeliveryResult>('acknowledgeDelivery', title_id, data, { delivery_id }, undefined, options); }
|
|
697
|
+
/** Title MCP token, never a runtime install token. Describes arguments, abilities, mutation semantics and provider facts. */
|
|
485
698
|
static mcpCapabilities(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionCapabilities>('mcpCapabilities', title_id, undefined, {}, undefined, options); }
|
|
486
|
-
/** Execute
|
|
487
|
-
static mcpOperation<T = Record<string, unknown>>(title_id: string, operation: MicrotransactionOperation, data: { arguments: Record<string, unknown>; confirm?: boolean }, options?: MicrotransactionRequestOptions) { return this.call<{ operation: MicrotransactionOperation; result: T }>('mcpOperation', title_id, data, { operation }, undefined, options); }
|
|
699
|
+
/** Execute a discovered authorized operation directly. Legacy confirm is ignored and not forwarded. */
|
|
700
|
+
static mcpOperation<T = Record<string, unknown>>(title_id: string, operation: MicrotransactionOperation, data: { arguments: Record<string, unknown>; confirm?: boolean }, options?: MicrotransactionRequestOptions) { return this.call<{ operation: MicrotransactionOperation; result: T }>('mcpOperation', title_id, { arguments: data.arguments }, { operation }, undefined, options); }
|
|
488
701
|
|
|
489
702
|
private static call<T>(route: string, title_id: string, data?: object, ids: Record<string, string> = {}, params?: object, options?: MicrotransactionRequestOptions | MicrotransactionSessionOptions): AxiosPromise<MicrotransactionResponse<T>> {
|
|
490
703
|
const replacements: Record<string, string> = {};
|
|
@@ -500,8 +713,9 @@ class Microtransactions {
|
|
|
500
713
|
}
|
|
501
714
|
return Requests.processRoute<T>(MicrotransactionsRoute.routes[route], data, replacements, params, {
|
|
502
715
|
signal: options?.signal, timeout: options?.timeout, headers,
|
|
503
|
-
//
|
|
504
|
-
|
|
716
|
+
// Every commerce route is title/environment-scoped. Never inject unrelated
|
|
717
|
+
// global community context into strict management/player route inputs.
|
|
718
|
+
excludeCommunityContext: true,
|
|
505
719
|
});
|
|
506
720
|
}
|
|
507
721
|
}
|
|
@@ -14,9 +14,20 @@ class MicrotransactionsRoute {
|
|
|
14
14
|
updateProduct: { url: '/titles/{title_id}/microtransactions/products/{product_id}', method: HTTP_METHODS.PUT },
|
|
15
15
|
archiveProduct: { url: '/titles/{title_id}/microtransactions/products/{product_id}/archive', method: HTTP_METHODS.POST },
|
|
16
16
|
providers: { url: '/titles/{title_id}/microtransactions/providers', method: HTTP_METHODS.GET },
|
|
17
|
+
updateProvider: { url: '/titles/{title_id}/microtransactions/providers/{provider}', method: HTTP_METHODS.PUT },
|
|
18
|
+
refreshProvider: { url: '/titles/{title_id}/microtransactions/providers/{provider}/refresh', method: HTTP_METHODS.POST },
|
|
19
|
+
createProviderOnboarding: { url: '/titles/{title_id}/microtransactions/providers/stripe/onboarding', method: HTTP_METHODS.POST },
|
|
20
|
+
deliverySettings: { url: '/titles/{title_id}/microtransactions/delivery-settings', method: HTTP_METHODS.GET },
|
|
21
|
+
updateDeliverySettings: { url: '/titles/{title_id}/microtransactions/delivery-settings', method: HTTP_METHODS.PUT },
|
|
22
|
+
deliveries: { url: '/titles/{title_id}/microtransactions/deliveries', method: HTTP_METHODS.GET },
|
|
23
|
+
refunds: { url: '/titles/{title_id}/microtransactions/refunds', method: HTTP_METHODS.GET },
|
|
24
|
+
refundDetail: { url: '/titles/{title_id}/microtransactions/refunds/{refund_id}', method: HTTP_METHODS.GET },
|
|
25
|
+
reconcileRefund: { url: '/titles/{title_id}/microtransactions/refunds/{refund_id}/reconcile', method: HTTP_METHODS.POST },
|
|
26
|
+
payouts: { url: '/titles/{title_id}/microtransactions/payouts', method: HTTP_METHODS.GET },
|
|
17
27
|
earnings: { url: '/titles/{title_id}/microtransactions/earnings', method: HTTP_METHODS.GET },
|
|
18
28
|
orders: { url: '/titles/{title_id}/microtransactions/orders', method: HTTP_METHODS.GET },
|
|
19
29
|
order: { url: '/titles/{title_id}/microtransactions/orders/{order_id}', method: HTTP_METHODS.GET },
|
|
30
|
+
reconcileOrder: { url: '/titles/{title_id}/microtransactions/orders/{order_id}/reconcile', method: HTTP_METHODS.POST },
|
|
20
31
|
refund: { url: '/titles/{title_id}/microtransactions/orders/{order_id}/refund', method: HTTP_METHODS.POST },
|
|
21
32
|
replayDelivery: { url: '/titles/{title_id}/microtransactions/deliveries/{delivery_id}/replay', method: HTTP_METHODS.POST },
|
|
22
33
|
catalog: { url: '/titles/{title_id}/microtransactions/catalog', method: HTTP_METHODS.GET },
|