glitch-javascript-sdk 3.15.0 → 4.0.0

package/guides/microtransactions.md

@@ -1,12 +1,11 @@
 # Game microtransactions
 
-**Minimum SDK for this guide: `3.15.0`.** Use a confirmed published `3.15.0+`
-release or an approved local package. Registry verification on September 15, 2026
-showed public latest `3.10.8`, which lacks commerce; a plain public npm install at
-that point cannot run this callback/history example. Until `3.15.0` is actually
-published, use only the reviewed local `glitch-javascript-sdk-3.15.0.tgz` for testing.
-Do not change a production dependency to an unpublished version or assume that
-local build success means public publication has happened.
+**Player checkout/history minimum: SDK `3.15.0`, which is published.** The new
+administrative direct-management API below is a **major SDK `4.0.0` migration**.
+Verify usable published versions independently before installing; a reviewed
+local4.0 candidate is not proof of publication. Server-side MCP catalog/provider
+setup does not require installing or publishing the game SDK, so do not block
+authorized server configuration while runtime package work is pending.
 
 The SDK entry point is `Glitch.api.Microtransactions`. All HTTP methods return an
 Axios response whose `response.data.data` contains the typed commerce result.
@@ -16,7 +15,8 @@ Never put a developer/MCP/install token into a shipped browser game.
 ## Developer setup
 
 1. Read `settings`, `readiness`, `providers` and `listProducts` with a signed-in
-   title administrator. Start disabled/sandbox. Approvals are server-controlled.
+   title administrator or scoped MCP caller. Use sandbox for development. Authorized
+   commerce operations execute directly; no custom confirmation/human-review gate.
    The **Enable in-game purchases** and **Show ads** switches live only on the
    game's Pricing/monetization page. Microtransactions is for products, media,
    prices, orders and integration—not a second location for those switches.
@@ -38,9 +38,89 @@ Never put a developer/MCP/install token into a shipped browser game.
    (12%) of discounted pre-tax subtotal. Actual provider costs are separate.
    Taxes are separate; pending earnings are not a verified available payout.
 6. Run a real approved provider sandbox purchase, verify game delivery/claim,
-   then call `verifyIntegration(titleId, {order_id, confirm:true})`. This records
-   real evidence, not a self-certified integration checkbox. Launch still needs
-   independent seller/tax/provider approvals. MCP confirm alone cannot supply them.
+   then call `verifyIntegration(titleId, {order_id})`. This records
+   real evidence, not a self-certified integration checkbox. Actual external
+   provider/account/tax capability and global sales emergency controls still apply.
+
+## SDK4.0 administrative migration
+
+Player checkout, restore, inventory and self-history routes remain compatible with
+SDK3.15. The administrative changes are deliberately major:
+
+- `refundOrder(titleId,orderId,{reason,amount_minor?,idempotency_key},options?)`
+  now requires a stable caller key. The SDK never generates it. Legacy `confirm`
+  is optional/ignored, not authorization. Keep one refund intent outside retries;
+  same key + changed payload conflicts, and unknown outcomes stay pinned.
+- `providers(titleId,{environment}?,options?)` returns factual `configured` and
+  `available` values instead of an `approved` badge. `account` is the platform
+  processor; `payout_account` is the game's target and must be evaluated separately.
+  The older second-argument request-options overload remains compatible.
+- `listProducts(titleId,{page,per_page,status,sku}?,options?)` now discovers the
+  complete catalog. `sku` matches exactly; status is draft/active/archived. Product
+  pages default to 200 records (1–200), unlike financial/history lists below.
+  Follow `pagination.has_more_pages`; absence on page one is not proof a SKU is
+  unused. Query the exact SKU after an uncertain create before retrying it.
+  The no-filter call and older request-options overload remain compatible.
+- `updateProvider`, `refreshProvider` and `createProviderOnboarding` manage routes
+  and owned Stripe onboarding. Onboarding also requires a stable key and returns
+  `onboarding_url` for the same owned account on retry, not an arbitrary payee ID.
+- `getDeliverySettings`/`updateDeliverySettings` expose enabled/URL and only public
+  verification material. Private signing keys remain server-side. Actual DNS/IP,
+  HTTPS and provider requirements are validated without an approval workflow.
+  Legacy `updateSettings.webhook_url` additionally requires commerce:fulfill as
+  well as commerce:write; prefer the dedicated delivery-settings methods.
+- `listOrders`, `listRefunds`, `listDeliveries` and `listPayouts` use page1–10000,
+  per_page1–100(default25) and return arrays plus pagination. Get IDs from discovery.
+  `getOrder` retains the player receipt path; management relationships are optional
+  and can be finance-redacted. Omitted fields do not prove no records exist.
+- `reconcileOrder`, `getRefund` and `reconcileRefund` inspect/recover the original
+  provider operations. A linked refund request or pending/unknown execution is not
+  a completed refund. Keep `execution_refund_id`, `execution_status` and actual
+  `order_refunded_minor` distinct. Transfers are not automatically bank-paid payouts.
+- All commerce calls omit unrelated global community context without mutating the
+  stored community/auth state. Other SDK features retain their own context behavior.
+
+Example stable refund intent (authorized commerce:finance only):
+
+```ts
+const refundIntent = {
+  reason: 'Customer refund', amount_minor: 199,
+  idempotency_key: crypto.randomUUID(), // ONCE for this intent, outside retries.
+};
+async function submitOrRetryRefund() {
+  return Glitch.api.Microtransactions.refundOrder(titleId, orderId, refundIntent);
+}
+// If response is unknown/lost, keep refundIntent. Inspect/reconcile its original
+// operation instead of making another key or blindly starting another refund.
+```
+
+Provider configuration reuses existing platform credentials; never send platform
+Stripe/Xsolla API keys or MCP credentials as settings. A new owned title/environment
+Xsolla `webhook_secret` is write-only(16–512 chars) under finance scope, encrypted
+server-side and never returned/audited. Existing platform/historical bindings cannot
+be overwritten. Keep this out of runtime game code, logs and raw JSON editors.
+Missing external setup returns factual reasons; saving configuration is not proof
+that a provider can accept payments. Global sales-off may block new purchases while
+authorized configuration and historical refunds remain available.
+
+### Signed server-delivery receiver
+
+[The complete Node24+ receiver example](commerce-delivery-receiver.mjs) verifies
+the exact raw body before parsing and durably queues event IDs without applying
+embedded inventory. Pin `title_id`, environment, `key_id` and the base64 raw32-byte
+`verification_public_key` from authenticated delivery settings, never from a message.
+Require algorithm `ed25519`, `X-Glitch-Key-Id`, UNIX-second `X-Glitch-Timestamp`
+within300 seconds, and `X-Glitch-Event-Id === body.id`. `X-Glitch-Signature` is base64
+raw64 bytes over timestamp + `.` + exact raw JSON bytes. ACK2xx `{event_id}` only
+after durable handling/commit. Duplicate IDs stay deduped across restarts.
+
+Do not increment inventory or replace aggregate balances from webhook snapshots:
+cross-order notifications can arrive out of order. An authorized game/player
+refreshes current `listEntitlements`, or a real server adapter uses monotonic
+inventory revisions. Legacy HMAC delivery is a separate configured algorithm;
+leave its original secrets unchanged and reject message-selected algorithm/key
+downgrades. The example needs Node24 only; it does not change the core SDK/MCP
+runtime requirement or replace actual payment/browser3DS verification.
 
 Product limits: SKU/grant key 1–100 alphanumeric/underscore/dot/hyphen characters;
 name 255 characters; description 4000; 10 distinct Media UUIDs; 50 prices; 30
@@ -360,12 +440,12 @@ hosted-account flows, not the default anonymous-game recovery path.
 - Earnings `transferred_minor` means money transferred to a provider balance,
   not a confirmed bank deposit. Preserve `bank_payout_status` and reserve/reconciliation
   fields; never relabel pending or transferred balances as paid bank payouts.
-- `requestRefund` is an owning account's support request. `refundOrder` requires
-  a separately approved financial administrator; pending/unknown is not completed.
+- `requestRefund` is an owning account's support request. `refundOrder` executes
+  directly for an authorized finance caller with a stable key; pending/unknown is not completed.
   Preserve historical orders and reverse commission proportionately. Refunds
   use the original provider/account, not the currently preferred payment route.
 - Handle HTTP 401/403 for account/scope, 404 for unavailable or cross-title IDs,
-  409 for idempotency/state/approval conflicts, 410 for expired sessions/claims,
+  409 for idempotency/state/invariant conflicts, 410 for expired sessions/claims,
   422 for invalid inputs/revenue policy, 429 for rate limits and 503 for provider
   coverage. Do not retry a hard decline/fraud block through another provider.
 - Ads-off is an actual per-title delivery policy. The backend rejects removing
@@ -374,12 +454,13 @@ hosted-account flows, not the default anonymous-game recovery path.
 
 ## MCP
 
-Use `mcpCapabilities` to discover exact schemas, abilities, approval flags and
+Use `mcpCapabilities` to discover exact schemas, abilities, mutation metadata and
 examples. `mcpOperation` always targets the authenticated MCP facade; it never
 uses a game's runtime token. `mcpUploadMedia` uses the same authorized Media
 pipeline. The companion `glitch-mcp` package supplies explicit tools, a
 `glitch://microtransactions/setup` resource, dynamic title schema resources and
-the `glitch_setup_microtransactions` prompt. A model must not auto-approve live
-prices, provider activation, financial actions or disabling the last revenue model.
+the `glitch_setup_microtransactions` prompt. Authorized title-scoped MCP management
+executes directly without confirmation/proposal/approval workflows. Permissions,
+actual provider facts and the last-revenue-model/financial invariants remain enforced.
 Developer MCP read tools do not impersonate players. The self-only runtime purchase
 history API is documented for game code, not exposed as an arbitrary-player MCP tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glitch-javascript-sdk",
-  "version": "3.15.0",
+  "version": "4.0.0",
   "description": "Javascript SDK for Glitch",
   "publishConfig": {
     "access": "public"

package/src/api/Microtransactions.ts

@@ -3,13 +3,17 @@ import MicrotransactionsRoute from '../routes/MicrotransactionsRoute';
 import Requests from '../util/Requests';
 
 export type MicrotransactionEnvironment = 'sandbox' | 'live';
+export type MicrotransactionProviderName = 'stripe' | 'xsolla';
 export type MicrotransactionProductType = 'durable' | 'consumable' | 'currency' | 'bundle' | 'pass';
 export type MicrotransactionCurrency = 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD' | 'JPY' | 'BRL' | 'INR' | 'KRW';
 export type MicrotransactionProductStatus = 'draft' | 'active' | 'archived';
-export type MicrotransactionPaymentStatus = 'created' | 'action_required' | 'pending' | 'unknown' | 'paid' | 'failed' | 'canceled' | 'refund_pending' | 'partially_refunded' | 'refunded' | 'disputed' | 'quarantined';
+export type MicrotransactionPaymentStatus = 'created' | 'action_required' | 'pending' | 'unknown' | 'paid' | 'failed' | 'canceled' | 'refund_pending' | 'partially_refunded' | 'refunded' | 'disputed' | 'quarantined' | 'refund_review';
+export type MicrotransactionRefundStatus = 'requested' | 'linked' | 'unknown' | 'pending' | 'submitted' | 'succeeded' | 'failed' | 'canceled';
+export type MicrotransactionDeliveryStatus = 'pending' | 'retrying' | 'processing' | 'acknowledged' | 'failed' | 'superseded';
+export type MicrotransactionPayoutStatus = 'pending' | 'transferred' | 'bank_paid' | 'bank_pending' | 'bank_failed' | 'transfer_reversed';
 export type MicrotransactionFulfillmentStatus = 'not_ready' | 'pending' | 'delivered' | 'retrying' | 'failed' | 'revoked' | 'partially_recovered';
 export type MicrotransactionAbility = 'commerce:read' | 'commerce:write' | 'commerce:finance' | 'commerce:fulfill';
-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';
+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';
 
 /** The backend's JSON envelope; Axios returns this envelope in response.data. */
 export interface MicrotransactionResponse<T> { data: T; message?: string; success?: boolean; }
@@ -24,6 +28,27 @@ export interface MicrotransactionSessionOptions extends MicrotransactionRequestO
   checkoutToken: string;
 }
 export interface MicrotransactionEnvironmentFilter { environment?: MicrotransactionEnvironment; }
+/** Catalog discovery defaults to 200 records per page; absence on page one is not proof a SKU is unused. */
+export interface MicrotransactionProductListFilters {
+  page?: number;
+  per_page?: number;
+  status?: MicrotransactionProductStatus;
+  /** Exact SKU, not a substring search. */
+  sku?: string;
+}
+/** Administrative lists default to page 1 / 25 records and are scoped to the authorized title. */
+export interface MicrotransactionManagementListFilters extends MicrotransactionEnvironmentFilter {
+  page?: number;
+  per_page?: number;
+  status?: string;
+}
+export interface MicrotransactionOrderListFilters extends MicrotransactionManagementListFilters { product_id?: string; status?: MicrotransactionPaymentStatus; payment_status?: MicrotransactionPaymentStatus; }
+export interface MicrotransactionRelatedListFilters extends MicrotransactionManagementListFilters { order_id?: string; }
+export interface MicrotransactionRefundListFilters extends MicrotransactionRelatedListFilters { status?: MicrotransactionRefundStatus; }
+export interface MicrotransactionDeliveryListFilters extends MicrotransactionRelatedListFilters { status?: MicrotransactionDeliveryStatus; }
+export interface MicrotransactionPayoutListFilters extends MicrotransactionRelatedListFilters { status?: MicrotransactionPayoutStatus; }
+/** @deprecated Optional compatibility field only; no confirmation or human-approval gate is enforced. */
+export interface MicrotransactionLegacyConfirmation { confirm?: boolean; }
 /** Self-only purchase-history filters. Identity comes from authentication, never a user_id argument. */
 export interface MicrotransactionMyPurchasesFilters extends MicrotransactionEnvironmentFilter {
   /** Page number, integer 1–10000. Defaults to 1; ordering is created_at DESC, id DESC. */
@@ -80,7 +105,7 @@ export interface MicrotransactionProductInput {
   starts_at?: string | null;
   ends_at?: string | null;
   max_per_order?: number;
-  /** Required for publishing/changing published goods; live approvals also enforced server-side. */
+  /** @deprecated Ignored compatibility field. Title authorization and immutable-data validation remain required. */
   confirm?: boolean;
 }
 export interface MicrotransactionProduct extends Omit<MicrotransactionProductInput, 'confirm' | 'status' | 'media_ids'> {
@@ -94,14 +119,131 @@ export interface MicrotransactionProduct extends Omit<MicrotransactionProductInp
   updated_at: string;
 }
 export interface MicrotransactionProvider {
-  provider: 'stripe' | 'xsolla';
+  provider: MicrotransactionProviderName;
   environment: MicrotransactionEnvironment;
   configured: boolean;
-  approved: boolean;
+  /** Actual external provider/account capability, not a manual approval flag. */
+  available: boolean;
+  enabled: boolean;
+  priority: number;
   countries: string[];
   currencies: string[];
+  minimum_amounts: Record<string, number>;
   channels: string[];
-  reason?: string;
+  payment_methods: string[];
+  configuration: MicrotransactionProviderConfiguration;
+  account: { id: string; country: string | null; charges_enabled: boolean; payouts_enabled: boolean; requirements_due: string[] } | null;
+  /** The game's payout target. Do not substitute the platform processing account's payouts_enabled. */
+  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[] };
+  tax: { status: string; missing_fields: string[] };
+  reasons: string[];
+  checked_at: string | null;
+  revision?: number;
+}
+export interface MicrotransactionProviderSku {
+  /** Provider SKU, 1–100 characters. */
+  sku: string;
+  currency: MicrotransactionCurrency;
+  amount_minor: number;
+}
+export interface MicrotransactionProviderConfiguration {
+  tax_mode: 'automatic' | 'disabled';
+  /** Stripe tax code txcd_ followed by exactly eight digits. */
+  tax_code: string | null;
+  payout_source: 'platform' | 'user' | 'community' | 'managed';
+  /** Xsolla public project ID, 1–20 decimal digits. */
+  project_id: string | null;
+  /** Maximum 200 mappings. */
+  sku_map: Record<string, MicrotransactionProviderSku>;
+}
+/** Developer preferences and an optional new owned Xsolla webhook secret only; never platform credentials, arbitrary payees, or availability facts. */
+export interface MicrotransactionProviderInput extends Partial<MicrotransactionProviderConfiguration>, MicrotransactionLegacyConfirmation {
+  environment: MicrotransactionEnvironment;
+  enabled?: boolean;
+  priority?: number;
+  countries?: string[];
+  currencies?: MicrotransactionCurrency[];
+  minimum_amounts?: Record<string, number>;
+  /** 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. */
+  webhook_secret?: string;
+}
+export interface MicrotransactionProviderOnboardingInput extends MicrotransactionLegacyConfirmation {
+  environment: MicrotransactionEnvironment;
+  country: string;
+  /** Stable caller-created key. Reuse with identical input after uncertain retries; never generate inside a retry. */
+  idempotency_key: string;
+}
+export interface MicrotransactionProviderOnboarding {
+  title_id: string;
+  provider: 'stripe';
+  environment: MicrotransactionEnvironment;
+  account_id: string;
+  /** Single-use provider onboarding URL on connect.stripe.com; do not log or persist it. */
+  onboarding_url: string;
+  expires_at: string;
+  status: 'requires_provider_onboarding';
+  reused: boolean;
+}
+export interface MicrotransactionDeliverySettings {
+  title_id: string;
+  environment: MicrotransactionEnvironment;
+  enabled: boolean;
+  url: string | null;
+  signature_algorithm: 'ed25519' | 'hmac-sha256';
+  /** Public verification material only. The private signing key never leaves the server. */
+  verification_public_key: string | null;
+  key_id: string | null;
+  revision: number;
+  configured: boolean;
+}
+export interface MicrotransactionDeliverySettingsInput extends MicrotransactionLegacyConfirmation {
+  environment: MicrotransactionEnvironment;
+  enabled?: boolean;
+  url?: string | null;
+}
+export interface MicrotransactionDelivery {
+  id: string;
+  order_id: string;
+  event_type: string;
+  status: MicrotransactionDeliveryStatus;
+  attempts: number;
+  next_attempt_at: string | null;
+  acknowledged_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+/** Replay/acknowledgement return only this safe subset, not the list's timestamps. */
+export type MicrotransactionDeliveryResult = Pick<MicrotransactionDelivery, 'id' | 'order_id' | 'status' | 'event_type' | 'attempts' | 'acknowledged_at'>;
+export interface MicrotransactionRefundRecord {
+  id: string;
+  order_id: string;
+  status: MicrotransactionRefundStatus;
+  amount_minor: number;
+  reason: string;
+  idempotency_key: string | null;
+  record_type: 'request' | 'execution';
+  execution_refund_id: string | null;
+  execution_status: MicrotransactionRefundStatus | null;
+  request_resolution: 'linked_to_execution' | 'not_executed' | null;
+  order_refunded_minor: number | null;
+  failure_code: string | null;
+  created_at: string;
+  updated_at: string;
+}
+export interface MicrotransactionPayout {
+  id: string;
+  order_id: string;
+  status: MicrotransactionPayoutStatus;
+  amount_minor: number;
+  provider_reference: string | null;
+  created_at: string;
+  updated_at: string;
+}
+export interface MicrotransactionRefundInput extends MicrotransactionLegacyConfirmation {
+  reason: string;
+  amount_minor?: number;
+  /** REQUIRED stable operation key, scoped to title/order. Reuse identical input on retry; changes conflict. */
+  idempotency_key: string;
 }
 export interface MicrotransactionReadiness {
   status: 'disabled' | 'draft' | 'sandbox' | 'ready' | 'live' | 'degraded' | 'suspended';
@@ -122,8 +264,9 @@ export interface MicrotransactionSettingsInput {
   currencies?: MicrotransactionCurrency[];
   branding?: Omit<MicrotransactionBranding, 'logo_media'>;
   support_email?: string | null;
+  /** @deprecated Legacy delivery alias requiring BOTH commerce:write and commerce:fulfill; prefer updateDeliverySettings/getDeliverySettings. */
   webhook_url?: string | null;
-  /** Required for policy/live changes; cannot replace recorded platform approval. */
+  /** @deprecated Ignored compatibility field. Authorized title editors save directly; actual provider/sales restrictions remain. */
   confirm?: boolean;
 }
 export interface MicrotransactionSettings extends Omit<Required<MicrotransactionSettingsInput>, 'confirm'> {
@@ -201,6 +344,13 @@ export interface MicrotransactionOrder {
   items: MicrotransactionGrant[];
   entitlements?: MicrotransactionEntitlement[];
 }
+export interface MicrotransactionOrderDetail extends MicrotransactionOrder {
+  /** Optional, permission-scoped management relationships. Omission is not proof no records exist. */
+  refunds?: Array<Pick<MicrotransactionRefundRecord, 'id' | 'order_id' | 'status'> & Partial<MicrotransactionRefundRecord>>;
+  deliveries?: MicrotransactionDelivery[];
+  payouts?: Array<Pick<MicrotransactionPayout, 'id' | 'order_id' | 'status'> & Partial<MicrotransactionPayout>>;
+  financial_details_included?: boolean;
+}
 export type MicrotransactionGrantUsageStatus = 'unused' | 'partially_used' | 'used_up' | 'owned' | 'expired' | 'revoked' | 'not_delivered' | 'unavailable';
 
 /** One purchase's server-calculated grant lot, not the player's aggregate inventory balance. */
@@ -339,7 +489,7 @@ export interface MicrotransactionConsumeInput {
   action_id: string;
   environment: MicrotransactionEnvironment;
 }
-export interface MicrotransactionRefund { refund_id: string; status: string; order_id: string; refund_allocation?: 'pro_rata_all_grants'; }
+export interface MicrotransactionRefund { refund_id: string; status: MicrotransactionRefundStatus; order_id: string; idempotency_key: string; failure_code: string | null; refund_allocation?: 'pro_rata_all_grants'; }
 export interface MicrotransactionRefundRequest { id: string; order_id: string; status: 'requested'; }
 export interface MicrotransactionEarnings {
   currency_balances: Array<{
@@ -352,14 +502,16 @@ export interface MicrotransactionEarnings {
   payouts_enabled: boolean;
   reserve_days?: number;
 }
-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';
+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';
 export interface MicrotransactionOperationCapability {
   operation: MicrotransactionOperation;
   description: string;
   ability: MicrotransactionAbility;
   input_schema: Record<string, unknown>;
-  requires_confirmation: boolean;
-  requires_human_approval: boolean;
+  http_method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  mutates: boolean;
+  requires_confirmation: false;
+  requires_human_approval: false;
   examples: Array<Record<string, unknown>>;
   output_description: string;
 }
@@ -387,39 +539,76 @@ class Microtransactions {
    */
   static uploadMedia(title_id: string, media: File | Blob, onUploadProgress?: (event: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'>): AxiosPromise<MicrotransactionResponse<MicrotransactionMedia>> {
     if (!/^[A-Za-z0-9_:-]+$/.test(title_id)) throw new Error('Invalid commerce title identifier.');
-    return Requests.uploadFile<MicrotransactionMedia>(MicrotransactionsRoute.routes.uploadMedia.url.replace('{title_id}', encodeURIComponent(title_id)), 'media', media, {}, undefined, onUploadProgress, options);
+    return Requests.uploadFile<MicrotransactionMedia>(MicrotransactionsRoute.routes.uploadMedia.url.replace('{title_id}', encodeURIComponent(title_id)), 'media', media, {}, undefined, onUploadProgress, { ...options, excludeCommunityContext: true });
   }
   /** Same title-authorized Media pipeline using the caller's MCP credential and commerce:write ability. */
   static mcpUploadMedia(title_id: string, media: File | Blob, onUploadProgress?: (event: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'>): AxiosPromise<MicrotransactionResponse<MicrotransactionMedia>> {
     if (!/^[A-Za-z0-9_:-]+$/.test(title_id)) throw new Error('Invalid commerce title identifier.');
-    return Requests.uploadFile<MicrotransactionMedia>(MicrotransactionsRoute.routes.mcpUploadMedia.url.replace('{title_id}', encodeURIComponent(title_id)), 'media', media, {}, undefined, onUploadProgress, options);
+    return Requests.uploadFile<MicrotransactionMedia>(MicrotransactionsRoute.routes.mcpUploadMedia.url.replace('{title_id}', encodeURIComponent(title_id)), 'media', media, {}, undefined, onUploadProgress, { ...options, excludeCommunityContext: true });
   }
   /** Admin settings, including immutable 1200bp commission and readiness blockers. */
   static settings(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionSettings>('settings', title_id, undefined, {}, undefined, options); }
   /** Atomic policy update. Sandbox/off by default. Cannot disable the final working revenue model. */
   static updateSettings(title_id: string, data: MicrotransactionSettingsInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionSettings>('updateSettings', title_id, data, {}, undefined, options); }
-  /** Read-only country/provider/approval readiness; never enables a provider. */
+  /** Read-only current country/provider capability and revenue readiness; never fabricates availability. */
   static readiness(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionReadiness>('readiness', title_id, undefined, {}, undefined, options); }
-  /** Admin list includes drafts and archives. Player clients should use catalog(). */
-  static listProducts(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<{ products: MicrotransactionProduct[] }>('products', title_id, undefined, {}, undefined, options); }
+  /** Paginated admin catalog including drafts/archives. Default 200, per_page 1–200/page 1–10000. Use exact sku to resolve uncertain creates. */
+  static listProducts(title_id: string, params?: MicrotransactionProductListFilters, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{ products: MicrotransactionProduct[]; pagination: MicrotransactionPurchasePagination }>>;
+  /** @deprecated Compatibility overload for the earlier second-argument request options. */
+  static listProducts(title_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{ products: MicrotransactionProduct[]; pagination: MicrotransactionPurchasePagination }>>;
+  static listProducts(title_id: string, paramsOrOptions?: MicrotransactionProductListFilters | MicrotransactionRequestOptions, options?: MicrotransactionRequestOptions) {
+    const legacy = paramsOrOptions && ('playerToken' in paramsOrOptions || 'signal' in paramsOrOptions || 'timeout' in paramsOrOptions);
+    return this.call<{ products: MicrotransactionProduct[]; pagination: MicrotransactionPurchasePagination }>('products', title_id, undefined, {}, legacy ? undefined : paramsOrOptions, legacy ? paramsOrOptions as MicrotransactionRequestOptions : options);
+  }
   /** Save a catalog product. Prices use integer minor units and attached media must belong to the title. */
   static createProduct(title_id: string, data: MicrotransactionProductInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProduct>('createProduct', title_id, data, {}, undefined, options); }
   /** Update a product version. Existing order snapshots remain unchanged. */
   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); }
-  /** Archive, never delete financial history. Requires explicit confirmation. */
-  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); }
-  /** Public provider metadata only. Credentials and commercial approvals are platform-managed. */
-  static providers(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<{ providers: MicrotransactionProvider[] }>('providers', title_id, undefined, {}, undefined, options); }
+  /** Direct authorized archive. Never deletes financial history or bypasses the last-revenue-model rule. */
+  static archiveProduct(title_id: string, product_id: string, data: MicrotransactionLegacyConfirmation = {}, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProduct>('archiveProduct', title_id, data, { product_id }, undefined, options); }
+  /** Actual provider configuration/capability facts; no credentials or manual approval flag. */
+  static providers(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{ providers: MicrotransactionProvider[] }>>;
+  /** @deprecated Compatibility overload for the earlier second-argument request options. */
+  static providers(title_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{ providers: MicrotransactionProvider[] }>>;
+  static providers(title_id: string, paramsOrOptions?: MicrotransactionEnvironmentFilter | MicrotransactionRequestOptions, options?: MicrotransactionRequestOptions) {
+    const legacy = paramsOrOptions && !('environment' in paramsOrOptions) && ('playerToken' in paramsOrOptions || 'signal' in paramsOrOptions || 'timeout' in paramsOrOptions);
+    return this.call<{ providers: MicrotransactionProvider[] }>('providers', title_id, undefined, {}, legacy ? undefined : paramsOrOptions, legacy ? paramsOrOptions as MicrotransactionRequestOptions : options);
+  }
+  /** Direct commerce:finance configuration. Saving preferences does not fabricate external capability; inspect available/reasons. */
+  static updateProvider(title_id: string, provider: MicrotransactionProviderName, data: MicrotransactionProviderInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProvider>('updateProvider', title_id, data, { provider }, undefined, options); }
+  /** Refresh authenticated external provider facts. May update cached state; never creates a payment or invents eligibility. */
+  static refreshProvider(title_id: string, provider: MicrotransactionProviderName, data: { environment: MicrotransactionEnvironment }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProvider>('refreshProvider', title_id, data, { provider }, undefined, options); }
+  /** Start/reuse owned Stripe Connect onboarding with one stable key. Provider KYC is factual setup, not a Glitch approval workflow. */
+  static createProviderOnboarding(title_id: string, data: MicrotransactionProviderOnboardingInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionProviderOnboarding>('createProviderOnboarding', title_id, data, {}, undefined, options); }
+  /** Read title/environment delivery settings and the Ed25519 PUBLIC verification key. */
+  static getDeliverySettings(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionDeliverySettings>('deliverySettings', title_id, undefined, {}, params, options); }
+  /** Direct commerce:fulfill setup. Private/metadata network targets and private-key inputs remain forbidden. */
+  static updateDeliverySettings(title_id: string, data: MicrotransactionDeliverySettingsInput, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionDeliverySettings>('updateDeliverySettings', title_id, data, {}, undefined, options); }
+  /** Discover safe event IDs/statuses before replay or acknowledge. Page 1–10000, per_page 1–100, default 25. */
+  static listDeliveries(title_id: string, params?: MicrotransactionDeliveryListFilters, options?: MicrotransactionRequestOptions) { return this.call<{ deliveries: MicrotransactionDelivery[]; pagination: MicrotransactionPurchasePagination }>('deliveries', title_id, undefined, {}, params, options); }
+  /** Financially scoped refund operation discovery; pending/unknown is not completed. */
+  static listRefunds(title_id: string, params?: MicrotransactionRefundListFilters, options?: MicrotransactionRequestOptions) { return this.call<{ refunds: MicrotransactionRefundRecord[]; pagination: MicrotransactionPurchasePagination }>('refunds', title_id, undefined, {}, params, options); }
+  /** Inspect one same-title refund operation. */
+  static getRefund(title_id: string, refund_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionRefundRecord>('refundDetail', title_id, undefined, { refund_id }, undefined, options); }
+  /** Query/retry the original persisted refund with its existing identity, never generate a new refund key. */
+  static reconcileRefund(title_id: string, refund_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionRefundRecord>('reconcileRefund', title_id, {}, { refund_id }, undefined, options); }
+  /** Discover provider transfer/payout records; transferred funds are not automatically a verified bank payout. */
+  static listPayouts(title_id: string, params?: MicrotransactionPayoutListFilters, options?: MicrotransactionRequestOptions) { return this.call<{ payouts: MicrotransactionPayout[]; pagination: MicrotransactionPurchasePagination }>('payouts', title_id, undefined, {}, params, options); }
   /** Admin read of separate-currency balances; pending is not withdrawable revenue. */
   static earnings(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionEarnings>('earnings', title_id, undefined, {}, params, options); }
-  /** Admin list, bounded to the server's most recent 100 redacted orders. */
-  static listOrders(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions) { return this.call<{ orders: MicrotransactionOrder[] }>('orders', title_id, undefined, {}, params, options); }
+  /** Admin paginated redacted orders. Page 1–10000/per_page 1–100 (default 25); own-player history is separate. */
+  static listOrders(title_id: string, params?: MicrotransactionOrderListFilters, options?: MicrotransactionRequestOptions) { return this.call<{ orders: MicrotransactionOrder[]; pagination: MicrotransactionPurchasePagination }>('orders', title_id, undefined, {}, params, options); }
   /** Owner JWT/scoped player token or title admin. An arbitrary order UUID grants no access. */
-  static getOrder(title_id: string, order_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionOrder>('order', title_id, undefined, { order_id }, undefined, options); }
-  /** Financial admin only; original provider and human approval. Omit amount_minor for remaining full refund; partial amounts are bounded and allocated pro rata. */
-  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); }
+  static getOrder(title_id: string, order_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionOrderDetail>('order', title_id, undefined, { order_id }, undefined, options); }
+  /** Financially scoped original-provider reconciliation. Does not reroute or start a different purchase. */
+  static reconcileOrder(title_id: string, order_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionOrderDetail>('reconcileOrder', title_id, {}, { order_id }, undefined, options); }
+  /** Direct commerce:finance refund. REQUIRED stable idempotency_key; omission is an error, never auto-filled. Same-key changed input conflicts. */
+  static refundOrder(title_id: string, order_id: string, data: MicrotransactionRefundInput, options?: MicrotransactionRequestOptions) {
+    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.');
+    return this.call<MicrotransactionRefund>('refund', title_id, data, { order_id }, undefined, options);
+  }
   /** Replay the same immutable event. Receiver must deduplicate event_id. This cannot mint goods. */
-  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); }
+  static replayDelivery(title_id: string, delivery_id: string, data: MicrotransactionLegacyConfirmation = {}, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionDeliveryResult>('replayDelivery', title_id, data, { delivery_id }, undefined, options); }
   /** Public eligible catalog. Sandbox is restricted by backend environment/admin policy. */
   static catalog(title_id: string, params?: MicrotransactionCatalogFilter, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionCatalog>('catalog', title_id, undefined, {}, params, options); }
   /** User-authenticated quote. Clients select product/quantity, never monetary values or seller accounts. */
@@ -452,7 +641,7 @@ class Microtransactions {
    */
   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); }
   /** Record integration proof from a genuinely paid, fulfilled sandbox order with a claimed game handoff. */
-  static verifyIntegration(title_id: string, data: { order_id: string; confirm: true }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionReadiness>('verifyIntegration', title_id, data, {}, undefined, options); }
+  static verifyIntegration(title_id: string, data: { order_id: string; confirm?: boolean }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionReadiness>('verifyIntegration', title_id, data, {}, undefined, options); }
   /** Restore authoritative durable ownership/current consumable balances, never mutable cloud-save balances. */
   static listEntitlements(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions) { return this.call<{ entitlements: MicrotransactionEntitlement[] }>('entitlements', title_id, undefined, {}, params, options); }
   /**
@@ -480,11 +669,11 @@ class Microtransactions {
   /** Owning user asks support to review a refund. This does not execute payment reversal. */
   static requestRefund(title_id: string, data: { order_id: string; reason: string }, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionRefundRequest>('requestRefund', title_id, data, {}, undefined, options); }
   /** Trusted title server with commerce:fulfill or admin JWT acknowledges the immutable event. */
-  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); }
-  /** Title MCP token, never a runtime install token. Describes every argument/schema/ability/approval gate. */
+  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); }
+  /** Title MCP token, never a runtime install token. Describes arguments, abilities, mutation semantics and provider facts. */
   static mcpCapabilities(title_id: string, options?: MicrotransactionRequestOptions) { return this.call<MicrotransactionCapabilities>('mcpCapabilities', title_id, undefined, {}, undefined, options); }
-  /** Execute only an operation discovered in mcpCapabilities. confirm is not financial approval. */
-  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); }
+  /** Execute a discovered authorized operation directly. Legacy confirm is ignored and not forwarded. */
+  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); }
 
   private static call<T>(route: string, title_id: string, data?: object, ids: Record<string, string> = {}, params?: object, options?: MicrotransactionRequestOptions | MicrotransactionSessionOptions): AxiosPromise<MicrotransactionResponse<T>> {
     const replacements: Record<string, string> = {};
@@ -500,8 +689,9 @@ class Microtransactions {
     }
     return Requests.processRoute<T>(MicrotransactionsRoute.routes[route], data, replacements, params, {
       signal: options?.signal, timeout: options?.timeout, headers,
-      // Self-history accepts only its explicit filters, not global community scope.
-      excludeCommunityContext: route === 'myPurchases',
+      // Every commerce route is title/environment-scoped. Never inject unrelated
+      // global community context into strict management/player route inputs.
+      excludeCommunityContext: true,
     });
   }
 }

package/src/routes/MicrotransactionsRoute.ts

@@ -14,9 +14,20 @@ class MicrotransactionsRoute {
     updateProduct: { url: '/titles/{title_id}/microtransactions/products/{product_id}', method: HTTP_METHODS.PUT },
     archiveProduct: { url: '/titles/{title_id}/microtransactions/products/{product_id}/archive', method: HTTP_METHODS.POST },
     providers: { url: '/titles/{title_id}/microtransactions/providers', method: HTTP_METHODS.GET },
+    updateProvider: { url: '/titles/{title_id}/microtransactions/providers/{provider}', method: HTTP_METHODS.PUT },
+    refreshProvider: { url: '/titles/{title_id}/microtransactions/providers/{provider}/refresh', method: HTTP_METHODS.POST },
+    createProviderOnboarding: { url: '/titles/{title_id}/microtransactions/providers/stripe/onboarding', method: HTTP_METHODS.POST },
+    deliverySettings: { url: '/titles/{title_id}/microtransactions/delivery-settings', method: HTTP_METHODS.GET },
+    updateDeliverySettings: { url: '/titles/{title_id}/microtransactions/delivery-settings', method: HTTP_METHODS.PUT },
+    deliveries: { url: '/titles/{title_id}/microtransactions/deliveries', method: HTTP_METHODS.GET },
+    refunds: { url: '/titles/{title_id}/microtransactions/refunds', method: HTTP_METHODS.GET },
+    refundDetail: { url: '/titles/{title_id}/microtransactions/refunds/{refund_id}', method: HTTP_METHODS.GET },
+    reconcileRefund: { url: '/titles/{title_id}/microtransactions/refunds/{refund_id}/reconcile', method: HTTP_METHODS.POST },
+    payouts: { url: '/titles/{title_id}/microtransactions/payouts', method: HTTP_METHODS.GET },
     earnings: { url: '/titles/{title_id}/microtransactions/earnings', method: HTTP_METHODS.GET },
     orders: { url: '/titles/{title_id}/microtransactions/orders', method: HTTP_METHODS.GET },
     order: { url: '/titles/{title_id}/microtransactions/orders/{order_id}', method: HTTP_METHODS.GET },
+    reconcileOrder: { url: '/titles/{title_id}/microtransactions/orders/{order_id}/reconcile', method: HTTP_METHODS.POST },
     refund: { url: '/titles/{title_id}/microtransactions/orders/{order_id}/refund', method: HTTP_METHODS.POST },
     replayDelivery: { url: '/titles/{title_id}/microtransactions/deliveries/{delivery_id}/replay', method: HTTP_METHODS.POST },
     catalog: { url: '/titles/{title_id}/microtransactions/catalog', method: HTTP_METHODS.GET },

package/src/util/Requests.ts

@@ -227,7 +227,7 @@ class Requests {
     data?: any,
     params?: Record<string, any>,
     onUploadProgress?: (progressEvent: AxiosProgressEvent) => void,
-    options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'>
+    options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'> & { excludeCommunityContext?: boolean }
   ): AxiosPromise<Response<T>> {
     // Process URL and params
     if (params && Object.keys(params).length > 0) {
@@ -241,7 +241,7 @@ class Requests {
     const formData = new FormData();
     formData.append(filename, file);
 
-    if (Requests.community_id) {
+    if (Requests.community_id && !options?.excludeCommunityContext) {
       data = {
         ...data,
         communities: [Requests.community_id],

package/src/util/Session.ts

@@ -1,5 +1,6 @@
 import { Config } from "../config";
 import Storage from "./Storage";
+import CryptoJS from 'crypto-js';
 
 // Type declarations for crypto functionality
 interface HmacInterface {
@@ -16,7 +17,7 @@ class BrowserCrypto implements CryptoInterface {
   private CryptoJS: any;
 
   constructor() {
-    this.CryptoJS = require('crypto-js');
+    this.CryptoJS = CryptoJS;
   }
 
   createHmac(algorithm: string, secret: string): HmacInterface {
@@ -188,4 +189,4 @@ class Session {
   }
 }
 
-export default Session;
+export default Session;