@moonpay/platform-protocol 0.0.0 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1081 @@
+/**
+ * A fiat currency or crypto token
+ */
+type Asset = {
+    /**
+     * A fiat or crypto currency code.
+     *
+     * **Fiat**
+     * Fiat codes are represented as [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) codes.
+     *
+     * Currently only `USD` is supported.
+     *
+     * **Crypto**
+     * For crypto currency codes, see [supported currencies](https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies).
+     *
+     * Examples: `BTC` `SOL` `ETH` `USDC_BASE` `USDC_SOL`
+     */
+    code: string;
+    /**
+     * The human-readable name
+     */
+    name?: string;
+    /**
+     * The number of supported decimal places
+     */
+    precision?: number;
+};
+type AssetBase = {
+    /**
+     * A fiat or crypto currency code.
+     *
+     * **Fiat**
+     * Fiat codes are represented as [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) codes.
+     *
+     * Currently only `USD` is supported.
+     *
+     * **Crypto**
+     * For crypto currency codes, see [supported currencies](https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies).
+     *
+     * Examples: `BTC` `SOL` `ETH` `USDC_BASE` `USDC_SOL`
+     */
+    code: string;
+};
+type CreateSessionTokenRequestBody = {
+    /**
+     * A unique identifier for the customer from your system.
+     */
+    externalCustomerId: string;
+    /**
+     * The IP address of the user's device to ensure the integrity of the session. Both IPv4 and IPv6 values are supported.
+     */
+    deviceIp: IPv4Address | IPv6Address;
+    /**
+     * The customer's email address. Must be a valid email. If provided, `phoneNumber` must also be provided.
+     */
+    email?: string;
+    /**
+     * The customer's phone number in E.164 format. If provided, `email` must also be provided.
+     */
+    phoneNumber?: string;
+};
+type CreateSessionTokenResponse = {
+    /**
+     * An opaque session token used to set up a connection on your frontend. This token is single-use and must be generated each time the customer visits your app.
+     *
+     * Token expires 24 hours after issuance.
+     */
+    sessionToken: string;
+};
+type Fees = {
+    /**
+     * Network fees (in fiat) for the transaction.
+     */
+    network?: MonetaryFeeAmount;
+    /**
+     * MoonPay fees (in fiat) for the transaction.
+     */
+    moonpay?: MonetaryFeeAmount;
+    /**
+     * Ecosystem fees (in fiat) for the transaction, if applicable.
+     */
+    ecosystem?: MonetaryFeeAmount;
+    /**
+     * Partner fees (in fiat) for the transaction, if applicable. Deprecated: use `fees.ecosystem` instead. This field will be removed in a future release.
+     * @deprecated
+     */
+    partner?: MonetaryFeeAmount;
+};
+type GetQuoteBody = {
+    /**
+     * Source asset in fiat. Amount can be set in `source` or `destination`.
+     */
+    source: {
+        /**
+         * The currency or token being spent
+         */
+        asset: AssetBase;
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount?: string;
+    };
+    /**
+     * Destination asset in crypto. Amount can be set in `destination` or `source`.
+     */
+    destination: {
+        asset: AssetBase;
+        /**
+         * The amount being received, if known
+         */
+        amount?: string;
+    };
+    /**
+     * Wallet address and optional tag where the crypto will be sent. Required for the quote to be executable.
+     */
+    wallet?: Wallet;
+    /**
+     * Payment method for the transaction. Required for the quote to be executable.
+     */
+    paymentMethod?: QuotePaymentMethod;
+};
+/**
+ * Quote for a fiat-to-crypto buy. Contains locked rate, fees, expiry, and signature for payment execution.
+ */
+type GetQuoteResponse = {
+    /**
+     * Source side of the quote: amount and asset (fiat currency) you send.
+     */
+    source: {
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount: string;
+        /**
+         * The currency or token being spent
+         */
+        asset: Asset;
+    };
+    /**
+     * Destination side of the quote: amount and asset (cryptocurrency) the customer receives.
+     */
+    destination: {
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount: string;
+        asset: Asset;
+    };
+    /**
+     * Breakdown of network, MoonPay, and ecosystem fees.
+     */
+    fees: Fees;
+    /**
+     * Wallet address and optional tag where the crypto will be sent. Null when not provided.
+     */
+    wallet: Wallet | null;
+    /**
+     * The payment method used for the quote.
+     */
+    paymentMethod: QuotePaymentMethod | null;
+    limits: QuoteLimits | null;
+    /**
+     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of when the quote expires.
+     */
+    expiresAt: string;
+    /**
+     * Whether the quote can be executed. Only `executable` quotes can be used to initiate payment frames.
+     */
+    executable: boolean;
+    /**
+     * The rate used to convert fiat <-> crypto, expressed as the crypto value of one unit of fiat.
+     */
+    exchangeRate: string;
+    /**
+     * An opaque token representing the quote to initiate payment frames.
+     */
+    signature: string;
+};
+type IPv4Address = string;
+type IPv6Address = string;
+type LimitWithAsset = {
+    /**
+     * A stringified amount, which can include decimals.
+     */
+    amount: string;
+    asset: AssetBase;
+};
+type MonetaryFeeAmount = {
+    /**
+     * The amount of fees in fiat.
+     */
+    amount: string;
+    /**
+     * The fiat currency used to pay the fees.
+     */
+    asset: AssetBase;
+};
+type MoonPayCorePaginationInfo = {
+    /**
+     * The cursor to use as the starting point for the next page of results.
+     */
+    nextCursor: string | null;
+};
+/**
+ * The card network brand.
+ */
+type MoonPayPaymentsCardBrand = 'visa' | 'mastercard' | 'maestro' | 'american_express' | 'other';
+/**
+ * The type of card: credit, debit, or unknown.
+ */
+type MoonPayPaymentsCardType = 'credit' | 'debit' | 'unknown';
+type MoonPayPaymentsListPaymentMethodsResponse = {
+    /**
+     * List of available payment method configurations
+     */
+    paymentMethodConfigs?: Array<MoonPayPaymentsPaymentMethod>;
+    /**
+     * List of stored payment methods available for the customer
+     */
+    paymentMethods?: Array<MoonPayPaymentsStoredPaymentMethod>;
+};
+type MoonPayPaymentsPaymentMethod = {
+    type: PaymentMethodType;
+    /**
+     * Details of how the payment method can be used.
+     */
+    capabilities: MoonPayPaymentsPaymentMethodCapabilities;
+    availability: MoonPayPaymentsPaymentMethodAvailability;
+};
+type MoonPayPaymentsPaymentMethodAvailability = {
+    /**
+     * Whether the payment method is available
+     */
+    active: boolean;
+    /**
+     * If the payment method is not available, reasons explaining why.
+     */
+    reasons?: Array<string>;
+};
+type MoonPayPaymentsPaymentMethodCapabilities = {
+    /**
+     * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) codes of fiat currencies supported by this payment method.
+     */
+    supportedCurrencies: Array<string>;
+    /**
+     * Transaction types supported by this payment method.
+     */
+    supportedTransactionTypes: Array<string>;
+    /**
+     * Whether this payment method can be deleted.
+     */
+    allowsDeletion: boolean;
+    /**
+     * Whether this payment method requires the MoonPay widget to complete the payment flow.
+     */
+    requiresWidget: boolean;
+};
+type MoonPayPaymentsStoredCardPaymentMethod = MoonPayPaymentsStoredPaymentMethodBase & {
+    cardType: MoonPayPaymentsCardType;
+    /**
+     * The card network brand
+     */
+    brand: MoonPayPaymentsCardBrand;
+    /**
+     * Last 4 digits of the card number
+     */
+    last4: string;
+    /**
+     * Expiration month as 2-digit string
+     */
+    expirationMonth: string;
+    /**
+     * Expiration year as 4-digit string
+     */
+    expirationYear: string;
+    /**
+     * Current availability of this stored card
+     */
+    availability: MoonPayPaymentsPaymentMethodAvailability;
+};
+/**
+ * A stored payment method.
+ */
+type MoonPayPaymentsStoredPaymentMethod = MoonPayPaymentsStoredPaymentMethodBase | MoonPayPaymentsStoredCardPaymentMethod;
+type MoonPayPaymentsStoredPaymentMethodBase = {
+    /**
+     * Unique identifier for the stored payment method
+     */
+    id: string;
+    type: PaymentMethodType;
+};
+type PaymentMethodType = 'apple_pay' | 'card' | 'ach' | 'fps' | 'fps_open_banking' | 'google_pay' | 'sepa' | 'sepa_open_banking' | 'pix' | 'paypal' | 'venmo' | 'revolut_pay' | 'moonpay_balance' | 'interac';
+type QuoteLimitEntry = {
+    /**
+     * The maximum amount.
+     */
+    limit: LimitWithAsset;
+    /**
+     * The remaining amount.
+     */
+    remaining: LimitWithAsset;
+};
+/**
+ * Limits applicable to the quote.
+ */
+type QuoteLimits = {
+    /**
+     * The daily limit.
+     */
+    daily?: QuoteLimitEntry;
+    /**
+     * The monthly limit.
+     */
+    monthly?: QuoteLimitEntry;
+    /**
+     * The yearly limit.
+     */
+    yearly?: QuoteLimitEntry;
+};
+type QuotePaymentMethod = {
+    type: PaymentMethodType;
+    /**
+     * Unique identifier of the payment method. Used to identify the specific card when type is card.
+     */
+    id?: string;
+};
+/**
+ * A stage in the transaction lifecycle
+ */
+type Stage = {
+    kind?: StageKind;
+    /**
+     * The human-readable name of the stage.
+     */
+    name?: string;
+    status?: StageStatus;
+    /**
+     * A developer-friendly message if the status is `failed`
+     */
+    failureReason?: string | null;
+};
+/**
+ * The stages in a transaction lifecycle.
+ */
+type StageKind = 'ordering' | 'waiting_payment' | 'waiting_authentication' | 'verification' | 'processing' | 'delivery' | 'crypto_hold';
+/**
+ * The status of a transaction stage.
+ */
+type StageStatus = 'not_started' | 'in_progress' | 'success' | 'failed';
+type TermsAttestation = {
+    /**
+     * The MoonPay ID of the terms attestation.
+     */
+    id: string;
+    /**
+     * Your identifier for the end customer who accepted MoonPay's terms.
+     */
+    externalCustomerId: string;
+    /**
+     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted string indicating when the attestation was recorded.
+     */
+    attestedAt: string;
+};
+type Transaction = {
+    /**
+     * The MoonPay ID of the transaction.
+     */
+    id: string;
+    /**
+     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of when the transaction was created.
+     */
+    createdAt: string;
+    /**
+     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of when the transaction was last updated.
+     */
+    updatedAt: string;
+    status: TransactionStatus;
+    /**
+     * Source amount and asset (fiat currency) the customer paid.
+     */
+    source: {
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount: string;
+        /**
+         * The currency or token being spent
+         */
+        asset: AssetBase;
+    };
+    /**
+     * Destination amount and asset (cryptocurrency) the customer receives.
+     */
+    destination: {
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount: string;
+        asset: AssetBase;
+    };
+    /**
+     * Details of fees for the transaction.
+     */
+    fees: Fees;
+    /**
+     * The wallet used for the transaction.
+     */
+    wallet: Wallet;
+    customer: TransactionCustomer;
+    paymentMethod?: TransactionPaymentMethod;
+};
+type TransactionCustomer = {
+    /**
+     * The MoonPay ID of the customer associated with the transaction.
+     */
+    id: string;
+};
+type TransactionPaymentMethod = {
+    type: PaymentMethodType;
+};
+/**
+ * The status of a transaction.
+ *
+ * - `completed`: The transaction is finalized and assets were delivered.
+ * - `failed`: The transaction failed. No payment was executed and funds were not transferred.
+ * - `pending`: The transaction was created and payment is accepted. The transfer is in progress.
+ */
+type TransactionStatus = 'completed' | 'failed' | 'pending';
+/**
+ * Transaction with lifecycle stages showing step-by-step progress.
+ */
+type TransactionWithStages = Transaction & {
+    /**
+     * Details of the stages in the transaction lifecycle.
+     */
+    stages?: Array<Stage>;
+};
+type Wallet = {
+    /**
+     * The wallet address used for the transaction.
+     */
+    address: string;
+    /**
+     * An optional memo or destination tag (used by some blockchains such as XRP or XLM).
+     */
+    tag?: string;
+};
+
+declare enum ConnectionStatus {
+    /**
+     * New or expired user — needs the full connect flow.
+     */
+    connectionRequired = "connectionRequired",
+    /**
+     * Valid connection — encrypted credentials are included.
+     */
+    active = "active",
+    /**
+     * Restricted location — connection cannot be used.
+     */
+    unavailable = "unavailable",
+    /**
+     * KYC decision delayed — may resolve on a subsequent visit.
+     */
+    pending = "pending",
+    /**
+     * Terminal failure — KYC fail, rejection, etc.
+     */
+    failed = "failed",
+    /**
+     * Customer has no valid Terms of Use attestation on file (headless/Identity API partners).
+     * Display Terms of Use in your own UI, capture acceptance, call
+     * `POST /platform/v1/terms/attestations`, then retry the connection.
+     */
+    termsAcceptanceRequired = "termsAcceptanceRequired"
+}
+interface ConnectionRequired {
+    status: ConnectionStatus.connectionRequired;
+    /**
+     * Base64-encoded, X25519+AES-GCM encrypted anonymous token payload.
+     * These are frame-internal tokens used by the connect frame — they cannot be
+     * used to call MoonPay APIs directly. Decrypt via `decryptCredentials()` only
+     * if you need the `clientToken` to bootstrap the connect frame manually.
+     */
+    credentials: string;
+    /**
+     * Capabilities and regulatory requirements available before authentication, if any.
+     * Present when Apple Pay 1TAP is enabled for the partner.
+     */
+    capabilities?: CustomerCapabilities;
+}
+interface ActiveConnection {
+    status: ConnectionStatus.active;
+    /** The authenticated MoonPay customer. */
+    customer: {
+        id: string;
+    };
+    /**
+     * Base64-encoded, X25519+AES-GCM encrypted JSON containing:
+     * ```json
+     * {
+     *   "accessToken": "<token>",
+     *   "clientToken": "<token>",
+     *   "expiresAt": "<iso8601>"
+     * }
+     * ```
+     *
+     * - `accessToken`: A token that can be used to make API requests from the client.
+     * - `clientToken`: A token that can be used to initialize sensitive frames such as Apple Pay.
+     * - `expiresAt`: An ISO 8601 formatted string indicating when the tokens expire.
+     */
+    credentials: string;
+    /**
+     * Capabilities and regulatory requirements for the authenticated customer.
+     */
+    capabilities: CustomerCapabilities;
+}
+interface UnavailableConnection {
+    status: ConnectionStatus.unavailable;
+}
+interface PendingConnection {
+    status: ConnectionStatus.pending;
+}
+interface FailedConnection {
+    status: ConnectionStatus.failed;
+    reason: string;
+}
+interface TermsAcceptanceRequiredConnection {
+    status: ConnectionStatus.termsAcceptanceRequired;
+}
+/** Discriminated union of all connection result statuses. */
+type Connection = ConnectionRequired | ActiveConnection | UnavailableConnection | PendingConnection | FailedConnection | TermsAcceptanceRequiredConnection;
+interface DecryptedCredentials {
+    accessToken: string;
+    clientToken: string;
+    expiresAt: string;
+}
+/**
+ * Capabilities and regulatory requirements for the authenticated customer.
+ */
+interface CustomerCapabilities {
+    /** Capabilities for the ramps (buy and sell) product. */
+    ramps?: RampsCapability;
+    /** Capabilities for the Apple Pay 1TAP flow. Present when 1TAP is enabled for the partner and the customer matches. */
+    oneTapApplePay?: RampsCapability;
+}
+/**
+ * Capabilities and requirements for the ramps (buy and sell) product.
+ */
+interface RampsCapability {
+    /** Regulatory requirements for ramps operations in the customer's jurisdiction. */
+    requirements: RampsRequirements;
+}
+/**
+ * Regulatory requirements that apply to ramps operations for the customer.
+ */
+interface RampsRequirements {
+    /**
+     * Present when the customer's jurisdiction requires payment disclosures
+     * before a ramps transaction. Omitted when no disclosures are required.
+     */
+    paymentDisclosures?: PaymentDisclosuresRequirement;
+}
+/**
+ * A jurisdiction that requires payment disclosures before a ramps transaction.
+ */
+interface PaymentDisclosuresRequirement {
+    /** The ISO 3166-1 alpha-3 country code for the jurisdiction. */
+    country: string;
+    /** The state or province code within the country. */
+    administrativeArea: string;
+}
+
+declare enum ConnectionErrorCode {
+    validationError = "validationError",
+    /** Wire value is `'generic'`. */
+    connectionFailedGeneric = "generic"
+}
+interface ConfigValidationFieldError {
+    code: 'invalidSessionToken' | 'invalidClientToken' | 'invalidPublicKey';
+    message: string;
+}
+type ConnectionError = {
+    code: ConnectionErrorCode.validationError;
+    errors: ConfigValidationFieldError[];
+} | {
+    code: ConnectionErrorCode.connectionFailedGeneric;
+    message?: string;
+};
+declare const DevPlatformApiErrorCodes: {
+    readonly unknownError: "unknown_error";
+    readonly unauthorized: "unauthorized";
+    readonly forbidden: "forbidden";
+    readonly notFound: "not_found";
+    readonly invalidRequest: "invalid_request";
+    readonly notImplemented: "not_implemented";
+    readonly tooManyRequests: "too_many_requests";
+    readonly notAllowed: "not_allowed";
+    readonly conflict: "conflict";
+    readonly unprocessableEntity: "unprocessable_entity";
+    readonly sseTimeout: "sse_timeout";
+    readonly sseError: "sse_error";
+    readonly connectionRequired: "connection_required";
+    readonly connectionPending: "connection_pending";
+    readonly connectionUnavailable: "connection_unavailable";
+    readonly serviceUnavailable: "service_unavailable";
+    readonly requirementsIncomplete: "requirements_incomplete";
+    readonly verificationRejected: "verification_rejected";
+    readonly countryMismatch: "country_mismatch";
+    readonly unsupportedCountry: "unsupported_country";
+};
+type DevPlatformApiErrorCode = (typeof DevPlatformApiErrorCodes)[keyof typeof DevPlatformApiErrorCodes];
+interface DevPlatformApiErrorDetail {
+    field?: string;
+    message: string;
+}
+/** Shape returned by the MoonPay Platform API on error responses. */
+interface DevPlatformApiError {
+    code: DevPlatformApiErrorCode;
+    message: string;
+    errors?: DevPlatformApiErrorDetail[];
+}
+interface GetConnectionError {
+    message: string;
+}
+interface ConnectError {
+    message: string;
+}
+interface SetupWidgetError {
+    kind: 'configurationError' | 'apiError' | 'genericError';
+    message: string;
+}
+interface SetupApplePayError {
+    kind: 'invalidQuote' | 'quoteExpired' | 'applePayUnavailable' | 'oneTapApplePaySecondFactorRequired' | 'genericError';
+    message: string;
+}
+interface SetupGooglePayError {
+    kind: 'invalidQuote' | 'quoteExpired' | 'googlePayUnavailable' | 'genericError';
+    message: string;
+}
+type GetQuoteError = DevPlatformApiError;
+type GetPaymentMethodsError = DevPlatformApiError;
+type GetTransactionsError = DevPlatformApiError;
+type CreateSessionError = DevPlatformApiError;
+type RevokeSessionError = DevPlatformApiError;
+interface SetupBuyError {
+    kind: 'configurationError' | 'genericError';
+    message: string;
+}
+interface SetupBuyButtonError {
+    kind: 'configurationError' | 'genericError';
+    message: string;
+}
+interface SetupChallengeError {
+    kind: 'configurationError' | 'genericError';
+    message: string;
+}
+interface SetupAddCardError {
+    kind: 'configurationError' | 'genericError';
+    message: string;
+}
+interface ResetConnectionError {
+    message: string;
+}
+
+/** The V2 protocol envelope sent over postMessage between frames and SDK. */
+interface ProtocolMessage<K extends string = string, P = unknown> {
+    version: 2;
+    meta: {
+        channelId: string;
+    };
+    kind: K;
+    payload?: P;
+}
+declare const HANDSHAKE_REQUEST_KIND: "handshake";
+declare const HANDSHAKE_ACK_KIND: "ack";
+type HandshakeRequest = ProtocolMessage<typeof HANDSHAKE_REQUEST_KIND>;
+type HandshakeAck = ProtocolMessage<typeof HANDSHAKE_ACK_KIND>;
+/**
+ * Maps message `kind` to its payload type for the widget frame.
+ * Frames use this to type-check what they send; SDK uses it to type-check
+ * what it receives.
+ */
+interface WidgetMessageMap {
+    ready: void;
+    error: {
+        code: 'configurationError' | 'apiError' | 'generic';
+        message: string;
+    };
+    transactionCreated: {
+        transaction: {
+            id: string;
+            status: string;
+        };
+    };
+    complete: {
+        transaction: FrameTransaction;
+    };
+    close: void;
+}
+/**
+ * Maps message `kind` to its payload type for the Apple Pay frame
+ * (child → parent direction).
+ */
+interface ApplePayInboundMessageMap {
+    ready: void;
+    error: {
+        code: 'configurationError' | 'quoteExpired' | 'invalidQuote' | 'applePayUnavailable' | 'generic' | 'oneTapApplePaySecondFactorRequired';
+        message: string;
+    };
+    complete: {
+        transaction: FrameTransaction;
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the Apple Pay frame
+ * (parent → child direction).
+ */
+interface ApplePayOutboundMessageMap {
+    setQuote: {
+        quote: {
+            signature: string;
+        };
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the Google Pay frame
+ * (child → parent direction).
+ */
+interface GooglePayInboundMessageMap {
+    ready: void;
+    error: {
+        code: 'configurationError' | 'quoteExpired' | 'invalidQuote' | 'googlePayUnavailable' | 'generic';
+        message: string;
+    };
+    /** Signals that the pipeline requires a challenge step. Load `url` in a challenge frame. */
+    challenge: {
+        kind: 'frame';
+        url: string;
+    };
+    complete: {
+        transaction: FrameTransaction;
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the Google Pay frame
+ * (parent → child direction).
+ */
+interface GooglePayOutboundMessageMap {
+    setQuote: {
+        quote: {
+            signature: string;
+        };
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the connect/check-connection
+ * frame (child → parent direction).
+ */
+interface ConnectMessageMap {
+    ready: void;
+    error: ConnectionError;
+    complete: ConnectionRequired | ActiveConnection | UnavailableConnection | PendingConnection | FailedConnection | TermsAcceptanceRequiredConnection;
+}
+/**
+ * Maps message `kind` to its payload type for the buy frame
+ * (child → parent direction).
+ *
+ * The buy frame executes the full buy pipeline (pre-check → create →
+ * post-check) headlessly. It may escalate to a challenge frame mid-pipeline.
+ */
+interface BuyMessageMap {
+    ready: void;
+    complete: {
+        transaction: FrameTransaction;
+    };
+    /** Signals that the pipeline requires a challenge step. Load `url` in a challenge frame. */
+    challenge: {
+        kind: string;
+        url: string;
+    };
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the buy frame
+ * (parent → child direction).
+ */
+interface BuyOutboundMessageMap {
+    setQuote: {
+        quote: {
+            signature: string;
+        };
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the buy-button frame
+ * (child → parent direction).
+ *
+ * The buy-button frame renders a payment button (card, Apple Pay, Google Pay)
+ * and runs the buy pipeline on tap. It may escalate to a challenge frame.
+ */
+interface BuyButtonMessageMap {
+    complete: {
+        transaction: FrameTransaction;
+    };
+    /** Signals that the pipeline requires a challenge step. Load `url` in a challenge frame. */
+    challenge: {
+        kind: string;
+        url: string;
+    };
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the buy-button frame
+ * (parent → child direction).
+ */
+interface BuyButtonOutboundMessageMap {
+    setQuote: {
+        quote: {
+            signature: string;
+        };
+    };
+}
+type ChallengeCompleteResult = {
+    flow: 'buy';
+    transaction: FrameTransaction;
+} | {
+    flow: 'identity';
+    identityId: string;
+};
+type ChallengeCancellation = {
+    flow: 'buy';
+    transactionId?: string;
+    challengeToken?: string;
+} | {
+    flow: 'identity';
+};
+/**
+ * Maps message `kind` to its payload type for the challenge frame
+ * (child → parent direction).
+ *
+ * The challenge frame is fully self-contained — it is driven by the
+ * `challengeToken` URL param. There is no parent → child message map.
+ */
+interface ChallengeMessageMap {
+    ready: void;
+    complete: ChallengeCompleteResult;
+    /** User dismissed the challenge. Carry `transactionId` / `challengeToken` to resume. */
+    cancelled: ChallengeCancellation;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the reset frame
+ * (child → parent direction).
+ *
+ * The reset frame clears the customer's MoonPay connection for the partner.
+ * It is fully driven by the `sessionToken` URL param. There is no
+ * parent → child message map.
+ */
+interface ResetMessageMap {
+    complete: void;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/** Card returned by the add-card frame on successful creation. */
+interface CardResponse {
+    id: string;
+    /** Payment method type, e.g. `'card'`. */
+    type: string;
+    /** Card sub-type, e.g. `'credit'` or `'debit'`. */
+    cardType: string;
+    /** Card network brand, e.g. `'visa'` or `'mastercard'`. */
+    brand: string;
+    last4: string;
+    expirationMonth: string;
+    expirationYear: string;
+    availability: {
+        active: true;
+    };
+}
+/**
+ * Maps message `kind` to its payload type for the add-card frame
+ * (child → parent direction).
+ *
+ * There is no parent → child message map for the add-card frame.
+ */
+interface AddCardMessageMap {
+    complete: {
+        card: CardResponse;
+    };
+    error: {
+        code: 'generic' | 'configurationError';
+        message: string;
+    };
+}
+
+/** Transaction shape as sent within frame postMessage payloads. */
+type FrameTransaction = {
+    id: string;
+    status: string;
+} | {
+    id?: string;
+    status: 'failed';
+    failureReason: string;
+};
+/** A ProtocolMessage typed to a specific message map entry. */
+type TypedMessage<Map extends Record<string, unknown>, K extends keyof Map & string> = Map[K] extends void ? ProtocolMessage<K, undefined> : ProtocolMessage<K, Map[K]>;
+/** Union of all typed messages for a given message map. */
+type MessageUnion<Map extends Record<string, unknown>> = {
+    [K in keyof Map & string]: TypedMessage<Map, K>;
+}[keyof Map & string];
+
+/** A parent→child message to update the quote in the Apple Pay frame. */
+type SetQuoteCommand = ProtocolMessage<'setQuote', ApplePayOutboundMessageMap['setQuote']>;
+/** A parent→child message to update the quote in the Google Pay frame. */
+type SetGooglePayQuoteCommand = ProtocolMessage<'setQuote', GooglePayOutboundMessageMap['setQuote']>;
+/** A parent→child message to update the quote in the buy frame. */
+type SetBuyQuoteCommand = ProtocolMessage<'setQuote', BuyOutboundMessageMap['setQuote']>;
+/** A parent→child message to update the quote in the buy-button frame. */
+type SetBuyButtonQuoteCommand = ProtocolMessage<'setQuote', BuyButtonOutboundMessageMap['setQuote']>;
+
+type WidgetEvent = {
+    kind: 'ready';
+} | {
+    kind: 'error';
+    payload: WidgetMessageMap['error'];
+} | {
+    kind: 'transactionCreated';
+    payload: WidgetMessageMap['transactionCreated'];
+} | {
+    kind: 'complete';
+    payload: {
+        transaction: FrameTransaction;
+    };
+} | {
+    kind: 'close';
+};
+type ApplePayEventError = {
+    kind: 'configurationError' | 'invalidQuote' | 'quoteExpired' | 'oneTapApplePaySecondFactorRequired' | 'genericError';
+    message: string;
+};
+type ApplePayEvent = {
+    kind: 'ready';
+} | {
+    kind: 'complete';
+    payload: {
+        transaction: FrameTransaction;
+    };
+} | {
+    kind: 'quoteExpired';
+    payload: {
+        setQuote: (signature: string) => void;
+    };
+} | {
+    kind: 'error';
+    payload: ApplePayEventError;
+} | {
+    kind: 'unsupported';
+};
+type GooglePayEventError = {
+    kind: 'configurationError' | 'invalidQuote' | 'quoteExpired' | 'genericError';
+    message: string;
+};
+type GooglePayEvent = {
+    kind: 'ready';
+} | {
+    kind: 'complete';
+    payload: {
+        transaction: FrameTransaction;
+    };
+} | {
+    kind: 'challenge';
+    payload: GooglePayInboundMessageMap['challenge'];
+} | {
+    kind: 'quoteExpired';
+    payload: {
+        setQuote: (signature: string) => void;
+    };
+} | {
+    kind: 'error';
+    payload: GooglePayEventError;
+} | {
+    kind: 'unsupported';
+};
+type ConnectEvent = {
+    kind: 'ready';
+} | {
+    kind: 'error';
+    payload: ConnectMessageMap['error'];
+} | {
+    kind: 'complete';
+    payload: ConnectMessageMap['complete'];
+};
+type BuyEvent = {
+    kind: 'ready';
+} | {
+    kind: 'complete';
+    payload: BuyMessageMap['complete'];
+} | {
+    kind: 'challenge';
+    payload: BuyMessageMap['challenge'];
+} | {
+    kind: 'error';
+    payload: BuyMessageMap['error'];
+};
+type BuyButtonEvent = {
+    kind: 'complete';
+    payload: BuyButtonMessageMap['complete'];
+} | {
+    kind: 'challenge';
+    payload: BuyButtonMessageMap['challenge'];
+} | {
+    kind: 'error';
+    payload: BuyButtonMessageMap['error'];
+};
+type ChallengeEvent = {
+    kind: 'ready';
+} | {
+    kind: 'complete';
+    payload: ChallengeCompleteResult;
+} | {
+    kind: 'cancelled';
+    payload: ChallengeCancellation;
+} | {
+    kind: 'error';
+    payload: {
+        code: string;
+        message: string;
+    };
+};
+type AddCardEvent = {
+    kind: 'complete';
+    payload: {
+        card: CardResponse;
+    };
+} | {
+    kind: 'error';
+    payload: AddCardMessageMap['error'];
+};
+
+/**
+ * A discriminated union representing either a successful value or an error.
+ * SDK methods return this type instead of throwing exceptions.
+ */
+type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+/** A Result variant for operations that produce no value on success. */
+type EmptyResult<E> = {
+    ok: true;
+} | {
+    ok: false;
+    error: E;
+};
+/** Construct a successful Result. */
+declare const ok: <T>(value: T) => {
+    ok: true;
+    value: T;
+};
+/** Construct a failed Result. */
+declare const err: <E>(error: E) => {
+    ok: false;
+    error: E;
+};
+
+export { type ActiveConnection, type AddCardEvent, type AddCardMessageMap, type ApplePayEvent, type ApplePayEventError, type ApplePayInboundMessageMap, type ApplePayOutboundMessageMap, type Asset, type AssetBase, type BuyButtonEvent, type BuyButtonMessageMap, type BuyButtonOutboundMessageMap, type BuyEvent, type BuyMessageMap, type BuyOutboundMessageMap, type CardResponse, type ChallengeCancellation, type ChallengeCompleteResult, type ChallengeEvent, type ChallengeMessageMap, type ConfigValidationFieldError, type ConnectError, type ConnectEvent, type ConnectMessageMap, type Connection, type ConnectionError, ConnectionErrorCode, type ConnectionRequired, ConnectionStatus, type CreateSessionError, type CreateSessionTokenRequestBody, type CreateSessionTokenResponse as CreateSessionTokenReturnType, type CustomerCapabilities, type DecryptedCredentials, type DevPlatformApiError, type DevPlatformApiErrorCode, DevPlatformApiErrorCodes, type DevPlatformApiErrorDetail, type EmptyResult, type FailedConnection, type Fees, type FrameTransaction, type GetConnectionError, type GetPaymentMethodsError, type GetQuoteError, type GetQuoteBody as GetQuoteParams, type GetTransactionsError, type GooglePayEvent, type GooglePayEventError, type GooglePayInboundMessageMap, type GooglePayOutboundMessageMap, HANDSHAKE_ACK_KIND, HANDSHAKE_REQUEST_KIND, type HandshakeAck, type HandshakeRequest, type LimitWithAsset, type MoonPayPaymentsListPaymentMethodsResponse as ListPaymentMethodsResponse, type MessageUnion, type MonetaryFeeAmount, type MoonPayCorePaginationInfo as PaginationInfo, type PaymentDisclosuresRequirement, type MoonPayPaymentsPaymentMethodAvailability as PaymentMethodAvailability, type MoonPayPaymentsPaymentMethodCapabilities as PaymentMethodCapabilities, type MoonPayPaymentsPaymentMethod as PaymentMethodConfig, type PaymentMethodType, type PendingConnection, type ProtocolMessage, type GetQuoteResponse as Quote, type QuoteLimitEntry, type QuoteLimits, type QuotePaymentMethod, type RampsCapability, type RampsRequirements, type ResetConnectionError, type ResetMessageMap, type Result, type RevokeSessionError, type SetBuyButtonQuoteCommand, type SetBuyQuoteCommand, type SetGooglePayQuoteCommand, type SetQuoteCommand, type SetupAddCardError, type SetupApplePayError, type SetupBuyButtonError, type SetupBuyError, type SetupChallengeError, type SetupGooglePayError, type SetupWidgetError, type Stage, type StageKind, type StageStatus, type MoonPayPaymentsStoredCardPaymentMethod as StoredCardPaymentMethod, type MoonPayPaymentsStoredPaymentMethod as StoredPaymentMethod, type TermsAcceptanceRequiredConnection, type TermsAttestation, type Transaction, type TransactionCustomer, type TransactionPaymentMethod, type TransactionStatus, type TransactionWithStages, type TypedMessage, type UnavailableConnection, type Wallet, type WidgetEvent, type WidgetMessageMap, err, ok };