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.
@@ -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' | 'human_approval_required' | 'not_found' | 'not_eligible' | 'quote_expired' | 'already_owned' | 'idempotency_conflict' | 'payment_unknown' | 'rate_limited' | 'invalid_revenue_configuration' | 'fulfillment_pending' | 'provider_unavailable';
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
- /** Required for publishing/changing published goods; live approvals also enforced server-side. */
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: 'stripe' | 'xsolla';
133
+ provider: MicrotransactionProviderName;
98
134
  environment: MicrotransactionEnvironment;
99
135
  configured: boolean;
100
- approved: boolean;
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
- reason?: string;
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
- /** Required for policy/live changes; cannot replace recorded platform approval. */
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: string; order_id: string; refund_allocation?: 'pro_rata_all_grants'; }
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
- requires_confirmation: boolean;
362
- requires_human_approval: boolean;
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. Configure with user JWT; purchases
375
- * use a recoverable user account and limited checkout capability. Install/title
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/approval readiness; never enables a 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
- /** Admin list includes drafts and archives. Player clients should use catalog(). */
404
- static listProducts(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<{ products: MicrotransactionProduct[] }>('products', title_id, undefined, {}, undefined, options); }
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
- /** Archive, never delete financial history. Requires explicit confirmation. */
410
- static archiveProduct(title_id: string, product_id: string, data: { confirm: true }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProduct>('archiveProduct', title_id, data, { product_id }, undefined, options); }
411
- /** Public provider metadata only. Credentials and commercial approvals are platform-managed. */
412
- static providers(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<{ providers: MicrotransactionProvider[] }>('providers', title_id, undefined, {}, undefined, options); }
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 list, bounded to the server's most recent 100 redacted orders. */
416
- static listOrders(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions) { return this.call<{ orders: MicrotransactionOrder[] }>('orders', title_id, undefined, {}, params, options); }
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<MicrotransactionOrder>('order', title_id, undefined, { order_id }, undefined, options); }
419
- /** Financial admin only; original provider and human approval. Omit amount_minor for remaining full refund; partial amounts are bounded and allocated pro rata. */
420
- static refundOrder(title_id: string, order_id: string, data: { reason: string; confirm: true; amount_minor?: number }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionRefund>('refund', title_id, data, { order_id }, undefined, options); }
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: { confirm: true }, options?: MicrotransactionRequestOptions) { return this.call<Record<string, unknown>>('replayDelivery', title_id, data, { delivery_id }, undefined, options); }
423
- /** Public eligible catalog. Sandbox is restricted by backend environment/admin policy. */
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
- /** Anonymous-safe opening step only. The hosted UI creates/logs into an account before payment. */
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
- /** Anonymous-safe inventory recovery. Opens an in-game hosted sign-in overlay, never creates a charge or requires the game's account JWT. */
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: true }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionReadiness>('verifyIntegration', title_id, data, {}, undefined, options); }
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<Record<string, unknown>>('acknowledgeDelivery', title_id, data, { delivery_id }, undefined, options); }
484
- /** Title MCP token, never a runtime install token. Describes every argument/schema/ability/approval gate. */
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 only an operation discovered in mcpCapabilities. confirm is not financial approval. */
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
- // Self-history accepts only its explicit filters, not global community scope.
504
- excludeCommunityContext: route === 'myPurchases',
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 },