glitch-javascript-sdk 3.15.0 → 4.0.0

package/dist/esm/util/Requests.d.ts

@@ -25,7 +25,9 @@ declare class Requests {
     static put<T>(url: string, data: any, params?: Record<string, any>): AxiosPromise<Response<T>>;
     static patch<T>(url: string, data: any, params?: Record<string, any>): AxiosPromise<Response<T>>;
     static delete<T>(url: string, params?: Record<string, any>): AxiosPromise<Response<T>>;
-    static uploadFile<T>(url: string, filename: string, file: File | Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'>): AxiosPromise<Response<T>>;
+    static uploadFile<T>(url: string, filename: string, file: File | Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'> & {
+        excludeCommunityContext?: boolean;
+    }): AxiosPromise<Response<T>>;
     static postFormData<T>(url: string, formData: FormData, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void): AxiosPromise<Response<T>>;
     static uploadBlob<T>(url: string, filename: string, blob: Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void): AxiosPromise<Response<T>>;
     static uploadFileInChunks<T>(file: File, uploadUrl: string, onProgress?: (totalSize: number, amountUploaded: number) => void, data?: any, chunkSize?: number): Promise<void>;

package/dist/index.d.ts

@@ -12180,13 +12180,17 @@ declare class FestivalNetworking {
 }
 
 type MicrotransactionEnvironment = 'sandbox' | 'live';
+type MicrotransactionProviderName = 'stripe' | 'xsolla';
 type MicrotransactionProductType = 'durable' | 'consumable' | 'currency' | 'bundle' | 'pass';
 type MicrotransactionCurrency = 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD' | 'JPY' | 'BRL' | 'INR' | 'KRW';
 type MicrotransactionProductStatus = 'draft' | 'active' | 'archived';
-type MicrotransactionPaymentStatus = 'created' | 'action_required' | 'pending' | 'unknown' | 'paid' | 'failed' | 'canceled' | 'refund_pending' | 'partially_refunded' | 'refunded' | 'disputed' | 'quarantined';
+type MicrotransactionPaymentStatus = 'created' | 'action_required' | 'pending' | 'unknown' | 'paid' | 'failed' | 'canceled' | 'refund_pending' | 'partially_refunded' | 'refunded' | 'disputed' | 'quarantined' | 'refund_review';
+type MicrotransactionRefundStatus = 'requested' | 'linked' | 'unknown' | 'pending' | 'submitted' | 'succeeded' | 'failed' | 'canceled';
+type MicrotransactionDeliveryStatus = 'pending' | 'retrying' | 'processing' | 'acknowledged' | 'failed' | 'superseded';
+type MicrotransactionPayoutStatus = 'pending' | 'transferred' | 'bank_paid' | 'bank_pending' | 'bank_failed' | 'transfer_reversed';
 type MicrotransactionFulfillmentStatus = 'not_ready' | 'pending' | 'delivered' | 'retrying' | 'failed' | 'revoked' | 'partially_recovered';
 type MicrotransactionAbility = 'commerce:read' | 'commerce:write' | 'commerce:finance' | 'commerce:fulfill';
-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';
+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. */
 interface MicrotransactionResponse<T> {
     data: T;
@@ -12209,6 +12213,41 @@ interface MicrotransactionSessionOptions extends MicrotransactionRequestOptions
 interface MicrotransactionEnvironmentFilter {
     environment?: MicrotransactionEnvironment;
 }
+/** Catalog discovery defaults to 200 records per page; absence on page one is not proof a SKU is unused. */
+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. */
+interface MicrotransactionManagementListFilters extends MicrotransactionEnvironmentFilter {
+    page?: number;
+    per_page?: number;
+    status?: string;
+}
+interface MicrotransactionOrderListFilters extends MicrotransactionManagementListFilters {
+    product_id?: string;
+    status?: MicrotransactionPaymentStatus;
+    payment_status?: MicrotransactionPaymentStatus;
+}
+interface MicrotransactionRelatedListFilters extends MicrotransactionManagementListFilters {
+    order_id?: string;
+}
+interface MicrotransactionRefundListFilters extends MicrotransactionRelatedListFilters {
+    status?: MicrotransactionRefundStatus;
+}
+interface MicrotransactionDeliveryListFilters extends MicrotransactionRelatedListFilters {
+    status?: MicrotransactionDeliveryStatus;
+}
+interface MicrotransactionPayoutListFilters extends MicrotransactionRelatedListFilters {
+    status?: MicrotransactionPayoutStatus;
+}
+/** @deprecated Optional compatibility field only; no confirmation or human-approval gate is enforced. */
+interface MicrotransactionLegacyConfirmation {
+    confirm?: boolean;
+}
 /** Self-only purchase-history filters. Identity comes from authentication, never a user_id argument. */
 interface MicrotransactionMyPurchasesFilters extends MicrotransactionEnvironmentFilter {
     /** Page number, integer 1–10000. Defaults to 1; ordering is created_at DESC, id DESC. */
@@ -12268,7 +12307,7 @@ 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;
 }
 interface MicrotransactionProduct extends Omit<MicrotransactionProductInput, 'confirm' | 'status' | 'media_ids'> {
@@ -12282,14 +12321,149 @@ interface MicrotransactionProduct extends Omit<MicrotransactionProductInput, 'co
     updated_at: string;
 }
 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;
+}
+interface MicrotransactionProviderSku {
+    /** Provider SKU, 1–100 characters. */
+    sku: string;
+    currency: MicrotransactionCurrency;
+    amount_minor: number;
+}
+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. */
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+interface MicrotransactionDeliverySettingsInput extends MicrotransactionLegacyConfirmation {
+    environment: MicrotransactionEnvironment;
+    enabled?: boolean;
+    url?: string | null;
+}
+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. */
+type MicrotransactionDeliveryResult = Pick<MicrotransactionDelivery, 'id' | 'order_id' | 'status' | 'event_type' | 'attempts' | 'acknowledged_at'>;
+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;
+}
+interface MicrotransactionPayout {
+    id: string;
+    order_id: string;
+    status: MicrotransactionPayoutStatus;
+    amount_minor: number;
+    provider_reference: string | null;
+    created_at: string;
+    updated_at: string;
+}
+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;
 }
 interface MicrotransactionReadiness {
     status: 'disabled' | 'draft' | 'sandbox' | 'ready' | 'live' | 'degraded' | 'suspended';
@@ -12313,8 +12487,9 @@ 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;
 }
 interface MicrotransactionSettings extends Omit<Required<MicrotransactionSettingsInput>, 'confirm'> {
@@ -12395,6 +12570,13 @@ interface MicrotransactionOrder {
     items: MicrotransactionGrant[];
     entitlements?: MicrotransactionEntitlement[];
 }
+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;
+}
 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. */
 interface MicrotransactionGrantUsage {
@@ -12545,8 +12727,10 @@ interface MicrotransactionConsumeInput {
 }
 interface MicrotransactionRefund {
     refund_id: string;
-    status: string;
+    status: MicrotransactionRefundStatus;
     order_id: string;
+    idempotency_key: string;
+    failure_code: string | null;
     refund_allocation?: 'pro_rata_all_grants';
 }
 interface MicrotransactionRefundRequest {
@@ -12569,14 +12753,16 @@ interface MicrotransactionEarnings {
     payouts_enabled: boolean;
     reserve_days?: number;
 }
-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';
+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';
 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;
 }
@@ -12608,42 +12794,78 @@ declare class Microtransactions {
     static settings(title_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionSettings>>;
     /** Atomic policy update. Sandbox/off by default. Cannot disable the final working revenue model. */
     static updateSettings(title_id: string, data: MicrotransactionSettingsInput, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionSettings>>;
-    /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionReadiness>>;
-    /** Admin list includes drafts and archives. Player clients should use catalog(). */
+    /** 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;
     }>>;
     /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionProduct>>;
     /** Update a product version. Existing order snapshots remain unchanged. */
     static updateProduct(title_id: string, product_id: string, data: Partial<MicrotransactionProductInput>, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionProduct>>;
-    /** Archive, never delete financial history. Requires explicit confirmation. */
-    static archiveProduct(title_id: string, product_id: string, data: {
-        confirm: true;
-    }, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionProduct>>;
-    /** Public provider metadata only. Credentials and commercial approvals are platform-managed. */
+    /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionProduct>>;
+    /** 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[];
     }>>;
+    /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionProvider>>;
+    /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionProvider>>;
+    /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionProviderOnboarding>>;
+    /** Read title/environment delivery settings and the Ed25519 PUBLIC verification key. */
+    static getDeliverySettings(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionDeliverySettings>>;
+    /** Direct commerce:fulfill setup. Private/metadata network targets and private-key inputs remain forbidden. */
+    static updateDeliverySettings(title_id: string, data: MicrotransactionDeliverySettingsInput, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionDeliverySettings>>;
+    /** 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): AxiosPromise<MicrotransactionResponse<{
+        deliveries: MicrotransactionDelivery[];
+        pagination: MicrotransactionPurchasePagination;
+    }>>;
+    /** Financially scoped refund operation discovery; pending/unknown is not completed. */
+    static listRefunds(title_id: string, params?: MicrotransactionRefundListFilters, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{
+        refunds: MicrotransactionRefundRecord[];
+        pagination: MicrotransactionPurchasePagination;
+    }>>;
+    /** Inspect one same-title refund operation. */
+    static getRefund(title_id: string, refund_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionRefundRecord>>;
+    /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionRefundRecord>>;
+    /** Discover provider transfer/payout records; transferred funds are not automatically a verified bank payout. */
+    static listPayouts(title_id: string, params?: MicrotransactionPayoutListFilters, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{
+        payouts: MicrotransactionPayout[];
+        pagination: MicrotransactionPurchasePagination;
+    }>>;
     /** Admin read of separate-currency balances; pending is not withdrawable revenue. */
     static earnings(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionEarnings>>;
-    /** Admin list, bounded to the server's most recent 100 redacted orders. */
-    static listOrders(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{
+    /** 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): AxiosPromise<MicrotransactionResponse<{
         orders: MicrotransactionOrder[];
+        pagination: MicrotransactionPurchasePagination;
     }>>;
     /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionOrder>>;
-    /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionRefund>>;
+    static getOrder(title_id: string, order_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionOrderDetail>>;
+    /** Financially scoped original-provider reconciliation. Does not reroute or start a different purchase. */
+    static reconcileOrder(title_id: string, order_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionOrderDetail>>;
+    /** 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): AxiosPromise<MicrotransactionResponse<MicrotransactionRefund>>;
     /** 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): AxiosPromise<MicrotransactionResponse<Record<string, unknown>>>;
+    static replayDelivery(title_id: string, delivery_id: string, data?: MicrotransactionLegacyConfirmation, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionDeliveryResult>>;
     /** Public eligible catalog. Sandbox is restricted by backend environment/admin policy. */
     static catalog(title_id: string, params?: MicrotransactionCatalogFilter, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionCatalog>>;
     /** User-authenticated quote. Clients select product/quantity, never monetary values or seller accounts. */
@@ -12686,7 +12908,7 @@ declare class Microtransactions {
     /** 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;
+        confirm?: boolean;
     }, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionReadiness>>;
     /** Restore authoritative durable ownership/current consumable balances, never mutable cloud-save balances. */
     static listEntitlements(title_id: string, params?: MicrotransactionEnvironmentFilter, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<{
@@ -12718,10 +12940,10 @@ declare class Microtransactions {
     /** 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): AxiosPromise<MicrotransactionResponse<Record<string, unknown>>>;
-    /** Title MCP token, never a runtime install token. Describes every argument/schema/ability/approval gate. */
+    }, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionDeliveryResult>>;
+    /** Title MCP token, never a runtime install token. Describes arguments, abilities, mutation semantics and provider facts. */
     static mcpCapabilities(title_id: string, options?: MicrotransactionRequestOptions): AxiosPromise<MicrotransactionResponse<MicrotransactionCapabilities>>;
-    /** Execute only an operation discovered in mcpCapabilities. confirm is not financial approval. */
+    /** 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;
@@ -12912,7 +13134,9 @@ declare class Requests {
     static put<T>(url: string, data: any, params?: Record<string, any>): AxiosPromise<Response<T>>;
     static patch<T>(url: string, data: any, params?: Record<string, any>): AxiosPromise<Response<T>>;
     static delete<T>(url: string, params?: Record<string, any>): AxiosPromise<Response<T>>;
-    static uploadFile<T>(url: string, filename: string, file: File | Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'>): AxiosPromise<Response<T>>;
+    static uploadFile<T>(url: string, filename: string, file: File | Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'> & {
+        excludeCommunityContext?: boolean;
+    }): AxiosPromise<Response<T>>;
     static postFormData<T>(url: string, formData: FormData, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void): AxiosPromise<Response<T>>;
     static uploadBlob<T>(url: string, filename: string, blob: Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void): AxiosPromise<Response<T>>;
     static uploadFileInChunks<T>(file: File, uploadUrl: string, onProgress?: (totalSize: number, amountUploaded: number) => void, data?: any, chunkSize?: number): Promise<void>;
@@ -13350,4 +13574,4 @@ declare class Glitch {
     };
 }
 
-export { type FestivalApplicationInput, type FestivalApplicationState, type FestivalConversation, type FestivalMediaUpload, type FestivalNetworkingFilters, type FestivalNetworkingProfile, type FestivalNetworkingResponse, type FestivalNetworkingSettings, type FestivalPost, type FestivalPostInput, type FestivalPostKind, type FestivalPostState, type FestivalPreferences, type FestivalReportInput, type FestivalRequestOptions, type FestivalWorkType, type MicrotransactionAbility, type MicrotransactionBranding, type MicrotransactionBridge, type MicrotransactionBridgeOptions, type MicrotransactionCapabilities, type MicrotransactionCatalog, type MicrotransactionCatalogFilter, type MicrotransactionCheckoutInput, type MicrotransactionCheckoutResult, type MicrotransactionCheckoutSession, type MicrotransactionCheckoutSessionInput, type MicrotransactionConsumeInput, type MicrotransactionCreatedCheckoutSession, type MicrotransactionCurrency, type MicrotransactionEarnings, type MicrotransactionEntitlement, type MicrotransactionEnvironment, type MicrotransactionEnvironmentFilter, type MicrotransactionError, type MicrotransactionErrorCode, type MicrotransactionFramePolicy, type MicrotransactionFulfillmentStatus, type MicrotransactionGrant, type MicrotransactionGrantUsage, type MicrotransactionGrantUsageStatus, type MicrotransactionHandoff, type MicrotransactionHandoffClaim, type MicrotransactionHandoffClaimInput, type MicrotransactionMedia, type MicrotransactionMyPurchases, type MicrotransactionMyPurchasesFilters, type MicrotransactionOperation, type MicrotransactionOperationCapability, type MicrotransactionOrder, type MicrotransactionOverlay, type MicrotransactionOverlayOptions, type MicrotransactionPaymentStatus, type MicrotransactionPlayerPurchase, type MicrotransactionPrice, type MicrotransactionProduct, type MicrotransactionProductInput, type MicrotransactionProductStatus, type MicrotransactionProductType, type MicrotransactionProvider, type MicrotransactionPurchaseInput, type MicrotransactionPurchaseMessage, type MicrotransactionPurchasePagination, type MicrotransactionQuote, type MicrotransactionReadiness, type MicrotransactionReadyMessage, type MicrotransactionRefund, type MicrotransactionRefundRequest, type MicrotransactionRequestOptions, type MicrotransactionResponse, type MicrotransactionRestoreBridgeOptions, type MicrotransactionSessionOptions, type MicrotransactionSettings, type MicrotransactionSettingsInput, type MicrotransactionVerifiedSession, createMicrotransactionBridge, createMicrotransactionNonce, createMicrotransactionRestoreBridge, Glitch as default, openMicrotransactionOverlay, openMicrotransactionRestoreOverlay };
+export { type FestivalApplicationInput, type FestivalApplicationState, type FestivalConversation, type FestivalMediaUpload, type FestivalNetworkingFilters, type FestivalNetworkingProfile, type FestivalNetworkingResponse, type FestivalNetworkingSettings, type FestivalPost, type FestivalPostInput, type FestivalPostKind, type FestivalPostState, type FestivalPreferences, type FestivalReportInput, type FestivalRequestOptions, type FestivalWorkType, type MicrotransactionAbility, type MicrotransactionBranding, type MicrotransactionBridge, type MicrotransactionBridgeOptions, type MicrotransactionCapabilities, type MicrotransactionCatalog, type MicrotransactionCatalogFilter, type MicrotransactionCheckoutInput, type MicrotransactionCheckoutResult, type MicrotransactionCheckoutSession, type MicrotransactionCheckoutSessionInput, type MicrotransactionConsumeInput, type MicrotransactionCreatedCheckoutSession, type MicrotransactionCurrency, type MicrotransactionDelivery, type MicrotransactionDeliveryListFilters, type MicrotransactionDeliveryResult, type MicrotransactionDeliverySettings, type MicrotransactionDeliverySettingsInput, type MicrotransactionDeliveryStatus, type MicrotransactionEarnings, type MicrotransactionEntitlement, type MicrotransactionEnvironment, type MicrotransactionEnvironmentFilter, type MicrotransactionError, type MicrotransactionErrorCode, type MicrotransactionFramePolicy, type MicrotransactionFulfillmentStatus, type MicrotransactionGrant, type MicrotransactionGrantUsage, type MicrotransactionGrantUsageStatus, type MicrotransactionHandoff, type MicrotransactionHandoffClaim, type MicrotransactionHandoffClaimInput, type MicrotransactionLegacyConfirmation, type MicrotransactionManagementListFilters, type MicrotransactionMedia, type MicrotransactionMyPurchases, type MicrotransactionMyPurchasesFilters, type MicrotransactionOperation, type MicrotransactionOperationCapability, type MicrotransactionOrder, type MicrotransactionOrderDetail, type MicrotransactionOrderListFilters, type MicrotransactionOverlay, type MicrotransactionOverlayOptions, type MicrotransactionPaymentStatus, type MicrotransactionPayout, type MicrotransactionPayoutListFilters, type MicrotransactionPayoutStatus, type MicrotransactionPlayerPurchase, type MicrotransactionPrice, type MicrotransactionProduct, type MicrotransactionProductInput, type MicrotransactionProductListFilters, type MicrotransactionProductStatus, type MicrotransactionProductType, type MicrotransactionProvider, type MicrotransactionProviderConfiguration, type MicrotransactionProviderInput, type MicrotransactionProviderName, type MicrotransactionProviderOnboarding, type MicrotransactionProviderOnboardingInput, type MicrotransactionProviderSku, type MicrotransactionPurchaseInput, type MicrotransactionPurchaseMessage, type MicrotransactionPurchasePagination, type MicrotransactionQuote, type MicrotransactionReadiness, type MicrotransactionReadyMessage, type MicrotransactionRefund, type MicrotransactionRefundInput, type MicrotransactionRefundListFilters, type MicrotransactionRefundRecord, type MicrotransactionRefundRequest, type MicrotransactionRefundStatus, type MicrotransactionRelatedListFilters, type MicrotransactionRequestOptions, type MicrotransactionResponse, type MicrotransactionRestoreBridgeOptions, type MicrotransactionSessionOptions, type MicrotransactionSettings, type MicrotransactionSettingsInput, type MicrotransactionVerifiedSession, createMicrotransactionBridge, createMicrotransactionNonce, createMicrotransactionRestoreBridge, Glitch as default, openMicrotransactionOverlay, openMicrotransactionRestoreOverlay };

package/guides/commerce-delivery-receiver.mjs

@@ -0,0 +1,117 @@
+/**
+ * Node 24+ example: verify and durably queue Glitch Ed25519 notifications.
+ * Run behind your HTTPS reverse proxy. This is NOT an inventory grant engine:
+ * a worker/game session refreshes current entitlements with its own authorized
+ * player session after durable queue handling. Never apply payload snapshots.
+ */
+import { createPublicKey, verify } from 'node:crypto';
+import { createServer } from 'node:http';
+import { DatabaseSync } from 'node:sqlite';
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const uuid = /^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/;
+function reject(code, status = 400) { const error = new Error(code); error.code = code; error.status = status; throw error; }
+function decodeBase64(value, length) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) reject('invalid_base64');
+  const bytes = Buffer.from(value, 'base64');
+  if (bytes.length !== length || bytes.toString('base64') !== value) reject('invalid_base64');
+  return bytes;
+}
+
+/** Configuration comes from authenticated delivery-settings, never the message. */
+export function createDeliveryInbox({ titleId, environment, keyId, publicKeyBase64, databasePath }) {
+  if (!uuid.test(titleId) || !uuid.test(keyId) || !['sandbox', 'live'].includes(environment)) reject('invalid_receiver_configuration');
+  if (typeof databasePath !== 'string' || !isAbsolute(databasePath)) reject('durable_absolute_database_path_required');
+  // Ed25519 raw public keys need the standard SubjectPublicKeyInfo DER wrapper.
+  const publicKey = createPublicKey({ key: Buffer.concat([
+    Buffer.from('302a300506032b6570032100', 'hex'), decodeBase64(publicKeyBase64, 32)
+  ]), format: 'der', type: 'spki' });
+  const db = new DatabaseSync(databasePath);
+  db.exec('PRAGMA busy_timeout=5000');
+  db.exec(`CREATE TABLE IF NOT EXISTS commerce_notifications (
+    title_id TEXT NOT NULL, environment TEXT NOT NULL, event_id TEXT NOT NULL,
+    order_id TEXT NOT NULL, event_type TEXT NOT NULL, order_version INTEGER NOT NULL,
+    received_at INTEGER NOT NULL, handled_at INTEGER,
+    PRIMARY KEY(title_id, environment, event_id)
+  )`);
+  const existing = db.prepare('SELECT order_id,event_type FROM commerce_notifications WHERE title_id=? AND environment=? AND event_id=?');
+  const insert = db.prepare('INSERT INTO commerce_notifications(title_id,environment,event_id,order_id,event_type,order_version,received_at) VALUES(?,?,?,?,?,?,?)');
+
+  return {
+    /** rawBody must be the EXACT bytes received before any JSON parser. */
+    receive(headers, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
+      if (!Buffer.isBuffer(rawBody) || rawBody.length > 1048576) reject('invalid_body_size', 413);
+      const h = Object.fromEntries(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
+      if (h['x-glitch-signature-algorithm'] !== 'ed25519' || h['x-glitch-key-id'] !== keyId) reject('unexpected_signing_key_or_algorithm', 401);
+      const timestamp = h['x-glitch-timestamp'];
+      if (typeof timestamp !== 'string' || !/^[0-9]{1,12}$/.test(timestamp) || Math.abs(nowSeconds - Number(timestamp)) > 300) reject('expired_timestamp', 401);
+      const signature = decodeBase64(h['x-glitch-signature'], 64);
+      const signed = Buffer.concat([Buffer.from(timestamp + '.', 'ascii'), rawBody]);
+      if (!verify(null, signed, publicKey, signature)) reject('invalid_signature', 401);
+      let event;
+      try { event = JSON.parse(rawBody.toString('utf8')); } catch { reject('invalid_json'); }
+      if (!event || event.title_id !== titleId || event.environment !== environment || !uuid.test(event.id || '')
+        || event.id !== h['x-glitch-event-id'] || typeof event.type !== 'string'
+        || !Number.isSafeInteger(event.order_version) || event.order_version < 0
+        || !event.authoritative_order || !uuid.test(event.authoritative_order.id || '')
+        || event.authoritative_order.title_id !== titleId || event.authoritative_order.environment !== environment) reject('event_scope_mismatch', 401);
+      const orderId = event.authoritative_order.id;
+      let duplicate = false;
+      db.exec('BEGIN IMMEDIATE');
+      try {
+        const prior = existing.get(titleId, environment, event.id);
+        if (prior) {
+          if (prior.order_id !== orderId || prior.event_type !== event.type) reject('event_identity_conflict', 409);
+          duplicate = true;
+        } else {
+          // Queue IDs only. Aggregate balances in an older signed notification
+          // are not safe to apply across out-of-order events from other orders.
+          insert.run(titleId, environment, event.id, orderId, event.type, event.order_version, nowSeconds);
+        }
+        db.exec('COMMIT');
+      } catch (error) { db.exec('ROLLBACK'); throw error; }
+      // Retry bodies may carry refreshed authoritative facts. The stable event
+      // identity is deduped; embedded inventory is NEVER reapplied on a retry.
+      return { event_id: event.id, duplicate };
+    },
+    close() { db.close(); },
+  };
+}
+
+/** Complete HTTP receiver. JSON/body middleware must not run before this handler. */
+export function createDeliveryServer(inbox) {
+  return createServer(async (request, response) => {
+    if (request.method !== 'POST' || request.url !== '/glitch/commerce') { response.writeHead(404).end(); return; }
+    try {
+      const chunks = []; let size = 0;
+      for await (const chunk of request) {
+        size += chunk.length;
+        if (size > 1048576) reject('invalid_body_size', 413);
+        chunks.push(chunk);
+      }
+      const acknowledgement = inbox.receive(request.headers, Buffer.concat(chunks));
+      response.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      response.end(JSON.stringify(acknowledgement)); // Only after durable commit.
+    } catch (error) {
+      response.writeHead(error.status || 500, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      response.end(JSON.stringify({ error: error.code || 'delivery_handling_failed' }));
+      // Do not log raw payload, signatures, credentials or private player data.
+    }
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.umask(0o077); // Keep the new application inbox/journal private.
+  const inbox = createDeliveryInbox({
+    titleId: process.env.GLITCH_TITLE_ID,
+    environment: process.env.GLITCH_COMMERCE_ENVIRONMENT,
+    keyId: process.env.GLITCH_DELIVERY_KEY_ID,
+    publicKeyBase64: process.env.GLITCH_DELIVERY_PUBLIC_KEY,
+    databasePath: process.env.GAME_DELIVERY_DATABASE,
+  });
+  const server = createDeliveryServer(inbox);
+  server.listen(Number(process.env.PORT || 8787), '127.0.0.1');
+  const stop = () => server.close(() => { inbox.close(); process.exit(0); });
+  process.once('SIGINT', stop); process.once('SIGTERM', stop);
+}