@catena/sdk 0.0.0-bootstrap.0 → 0.4.0

package/dist/mpp.d.mts

@@ -0,0 +1,327 @@
+import { J as WalletCounterpartyRail, N as IntentResult, i as FetchLike, n as CatenaClient } from "./client-B_Gi0aqH.mjs";
+import { Method, z } from "mppx";
+//#region src/mpp.d.ts
+/**
+ * CAIP-2 network carried by an EVM MPP charge. Known values provide editor
+ * hints, while other strings remain representable because the server decides
+ * which networks are payable.
+ */
+export type MppNetwork = "eip155:8453" | "eip155:84532" | "eip155:5042" | (string & {});
+declare const evmCharge: {
+  readonly name: "evm";
+  readonly intent: "charge";
+  readonly schema: {
+    credential: {
+      payload: z.ZodMiniObject<{
+        type: z.ZodMiniLiteral<"authorization">;
+        from: z.ZodMiniString<string>;
+        to: z.ZodMiniString<string>;
+        value: z.ZodMiniString<string>;
+        validAfter: z.ZodMiniString<string>;
+        validBefore: z.ZodMiniString<string>;
+        nonce: z.ZodMiniString<string>;
+        signature: z.ZodMiniString<string>;
+      }, z.core.$strip>;
+    };
+    request: z.ZodMiniObject<{
+      amount: z.ZodMiniString<string>;
+      currency: z.ZodMiniString<string>;
+      description: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      externalId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      recipient: z.ZodMiniString<string>;
+      methodDetails: z.ZodMiniObject<{
+        chainId: z.ZodMiniNumber<number>;
+        credentialTypes: z.ZodMiniArray<z.ZodMiniLiteral<"authorization">>;
+        decimals: z.ZodMiniLiteral<6>;
+        permit2Address: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        splits: z.ZodMiniOptional<z.ZodMiniNever>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
+};
+declare const usdcCharge: {
+  readonly name: "usdc";
+  readonly intent: "charge";
+  readonly schema: {
+    credential: {
+      payload: z.ZodMiniObject<{
+        type: z.ZodMiniLiteral<"authorization">;
+        from: z.ZodMiniString<string>;
+        to: z.ZodMiniString<string>;
+        value: z.ZodMiniString<string>;
+        validAfter: z.ZodMiniString<string>;
+        validBefore: z.ZodMiniString<string>;
+        nonce: z.ZodMiniString<string>;
+        signature: z.ZodMiniString<string>;
+      }, z.core.$strip>;
+    };
+    request: z.ZodMiniObject<{
+      amount: z.ZodMiniString<string>;
+      currency: z.ZodMiniString<string>;
+      description: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      externalId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      recipient: z.ZodMiniString<string>;
+      methodDetails: z.ZodMiniObject<{
+        type: z.ZodMiniLiteral<"evm">;
+        evm: z.ZodMiniObject<{
+          chainId: z.ZodMiniNumber<number>;
+          credentialTypes: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniLiteral<"authorization">>>;
+          decimals: z.ZodMiniLiteral<6>;
+          permit2Address: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          splits: z.ZodMiniOptional<z.ZodMiniNever>;
+        }, z.core.$strip>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
+};
+/**
+ * Parameters shared by both Catena MPP charge methods.
+ */
+export interface CatenaMppParameters {
+  /**
+   * A linked Catena SDK client used to submit the payment intent.
+   */
+  readonly client: CatenaClient;
+  /**
+   * Catena account whose wallet will authorize the charge.
+   */
+  readonly accountId: string;
+  /**
+   * Price ceiling in atomic USDC units (6 decimals). Challenges asking for
+   * more are refused before any intent is created.
+   */
+  readonly maxAtomicAmount?: bigint;
+}
+/**
+ * Catena-backed `evm/charge` mppx client method.
+ */
+export type CatenaEvmChargeMethod = Method.Client<typeof evmCharge>;
+/**
+ * Catena-backed `usdc/charge` mppx client method.
+ */
+export type CatenaUsdcChargeMethod = Method.Client<typeof usdcCharge>;
+/**
+ * Both Catena methods registered by the factory.
+ */
+export type CatenaMppMethods = readonly [CatenaEvmChargeMethod, CatenaUsdcChargeMethod];
+/**
+ * Callable Catena MPP factory, with the conventional charge alias.
+ */
+export interface CatenaMppFactory {
+  (parameters: CatenaMppParameters): CatenaMppMethods;
+  charge(parameters: CatenaMppParameters): CatenaMppMethods;
+}
+/**
+ * Status of a Catena MPP intent that did not yield a usable credential.
+ */
+export type MppPaymentStatus = IntentResult["status"];
+/**
+ * A Catena MPP intent completed without a usable credential or stopped in a
+ * non-completed state. Inspect `status` to choose a recovery path and
+ * `intentId` to reconcile the payment with `client.getIntent(intentId)`.
+ */
+export declare class MppPaymentError extends Error {
+  readonly intentId: string;
+  readonly status: MppPaymentStatus;
+  readonly reasons: readonly string[];
+  readonly expiresAt: string | null;
+  constructor(message: string, details: {
+    readonly intentId: string;
+    readonly status: MppPaymentStatus;
+    readonly reasons: readonly string[];
+    readonly expiresAt: string | null;
+  });
+}
+/**
+ * Credential-free record of an MPP payment completed by the managed fetch
+ * wrapper.
+ */
+export interface MppPaymentReceipt {
+  /**
+   * Catena intent that completed the payment.
+   */
+  readonly intentId: string;
+  /**
+   * Validated MPP method selected from the seller's challenge.
+   */
+  readonly method: "evm" | "usdc";
+  /**
+   * Paid amount in atomic USDC units (6 decimals).
+   */
+  readonly atomicAmount: string;
+  /**
+   * CAIP-2 network on which the payment was authorized.
+   */
+  readonly network: MppNetwork;
+  /**
+   * EVM address that received the payment authorization.
+   */
+  readonly recipient: string;
+  /**
+   * Canonical final URL of the resource that was paid.
+   */
+  readonly resourceUrl: string;
+}
+/**
+ * Base error for managed MPP negotiation failures. `intentId` is present only
+ * after Catena created an intent; `reasons` carries server recovery detail
+ * without exposing the payment credential.
+ */
+export declare class MppFetchPaymentError extends Error {
+  /**
+   * Catena intent to reconcile, when one was created.
+   */
+  readonly intentId: string | undefined;
+  /**
+   * Stable recovery detail returned by Catena.
+   */
+  readonly reasons: readonly string[];
+  constructor(message: string, details?: {
+    readonly intentId?: string;
+    readonly reasons?: readonly string[];
+    readonly cause?: unknown;
+  });
+}
+/**
+ * None of the offered MPP networks can be funded by the selected account.
+ */
+export declare class MppNetworkMismatchError extends MppFetchPaymentError {
+  /**
+   * Account that needs a wallet on one of the required networks.
+   */
+  readonly accountId: string;
+  /**
+   * Offered networks that Catena reported as mismatches.
+   */
+  readonly requiredNetworks: readonly MppNetwork[];
+  constructor(accountId: string, requiredNetworks: readonly MppNetwork[], reasons: readonly string[]);
+}
+/**
+ * The selected MPP recipient is not saved as a usable Catena counterparty
+ * rail.
+ */
+export declare class MppCounterpartyNotFoundError extends MppFetchPaymentError {
+  /**
+   * Recipient address that must be added.
+   */
+  readonly recipient: string;
+  /**
+   * Network on which the recipient was offered.
+   */
+  readonly network: MppNetwork;
+  /**
+   * Server-resolved Catena rail that can be passed to a
+   * `create_counterparty` intent. Absent when the server sends no valid rail,
+   * or when the rail names a different recipient than the challenge.
+   */
+  readonly requiredRail: WalletCounterpartyRail | undefined;
+  constructor(recipient: string, network: MppNetwork, reasons: readonly string[], requiredRail?: WalletCounterpartyRail);
+}
+/**
+ * The MPP payment is parked for human approval. Retry the original request
+ * after approval so a fresh challenge can consume the grant.
+ */
+export declare class MppApprovalPendingError extends MppFetchPaymentError {
+  /**
+   * Time at which the pending approval expires, when supplied by Catena.
+   */
+  readonly expiresAt: string | null;
+  constructor(intentId: string, reasons: readonly string[], expiresAt: string | null);
+}
+/**
+ * Catena terminally blocked or failed the selected MPP payment.
+ */
+export declare class MppPaymentDeclinedError extends MppFetchPaymentError {
+  /**
+   * Terminal intent disposition.
+   */
+  readonly status: "blocked" | "failed";
+  constructor(intentId: string, status: "blocked" | "failed", reasons: readonly string[]);
+}
+/**
+ * Submission failed where Catena may already have acted. Reconcile the intent
+ * before authorizing another payment.
+ */
+export declare class MppSubmitInterruptedError extends MppFetchPaymentError {
+  /**
+   * Validated MPP method whose submission became ambiguous.
+   */
+  readonly method: "evm" | "usdc";
+  /**
+   * Potentially paid amount in atomic USDC units.
+   */
+  readonly atomicAmount: string;
+  /**
+   * Network on which submission may have occurred.
+   */
+  readonly network: MppNetwork;
+  /**
+   * Recipient whose payment may have been submitted.
+   */
+  readonly recipient: string;
+  /**
+   * Canonical resource URL bound to the ambiguous intent.
+   */
+  readonly resourceUrl: string;
+  constructor(intentId: string, terms: {
+    readonly method: "evm" | "usdc";
+    readonly atomicAmount: string;
+    readonly network: MppNetwork;
+    readonly recipient: string;
+  }, resourceUrl: string, cause: unknown);
+}
+/**
+ * Payment completed but `onPayment` or the single paid retry failed. The
+ * credential-free receipt identifies the settled intent for reconciliation.
+ */
+export declare class MppRetryFailedError extends MppFetchPaymentError {
+  /**
+   * Completed payment that must not be paid a second time.
+   */
+  readonly receipt: MppPaymentReceipt;
+  constructor(receipt: MppPaymentReceipt, cause: unknown);
+}
+/**
+ * Options for the managed MPP fetch wrapper.
+ */
+export interface MppFetchOptions {
+  /**
+   * Catena account whose wallet authorizes payments.
+   */
+  readonly accountId: string;
+  /**
+   * Custom fetch transport, defaulting to `globalThis.fetch`.
+   */
+  readonly baseFetch?: FetchLike;
+  /**
+   * Maximum acceptable price in atomic USDC units (6 decimals).
+   */
+  readonly maxAtomicAmount?: bigint;
+  /**
+   * Called once after payment completes and before the paid retry. The receipt
+   * deliberately excludes the MPP credential.
+   */
+  readonly onPayment?: (receipt: MppPaymentReceipt) => void | Promise<void>;
+}
+/**
+ * Create Catena-backed mppx EVM charge methods. The Catena server decides
+ * which networks and token contracts are payable. Pass the returned tuple
+ * directly in `Mppx.create({ methods: [...] })`.
+ */
+export declare const catena: CatenaMppFactory;
+/**
+ * Wrap `fetch` with one managed MPP payment attempt. Ordinary responses and
+ * 402s without a decodable MPP challenge pass through unchanged. For a
+ * supported challenge, the wrapper binds the payment to the final same-origin
+ * resource URL, submits one Catena intent at a time, calls `onPayment`, and
+ * retries the original request exactly once through the configured Fetch
+ * transport with Mppx's credential transport.
+ *
+ * Stream and consumed `Request` bodies are rejected before payment because
+ * they cannot be replayed safely. Once an intent completes, continuation
+ * failures throw `MppRetryFailedError`; do not run the payment loop again
+ * without first reconciling that receipt's intent.
+ */
+export declare function wrapFetchWithMppPayment(client: CatenaClient, options: MppFetchOptions): FetchLike;
+//#endregion
+export type { WalletCounterpartyRail };