@usdctofiat/offramp 3.0.2 → 3.1.0

package/dist/errors-DzTiflBh.d.cts

@@ -0,0 +1,409 @@
+import { PeerOnrampPreparedTransactionCallback, PeerOnrampPreparedTransactionResult, PeerExtensionOnrampParams, CuratorSellerCredentialUploadResponse, currencyInfo } from '@zkp2p/sdk';
+
+/**
+ * Peer browser-extension surface for PayPal + Wise makers. Drive the
+ * headless metadata bridge via `usePeerExtensionRegistration` in
+ * `@usdctofiat/offramp/react`, or manually:
+ *
+ * ```ts
+ * import {
+ *   completePeerExtensionRegistration,
+ *   isPeerExtensionMetadataBridgeAvailable,
+ *   peerExtensionSdk,
+ * } from "@usdctofiat/offramp";
+ *
+ * const state = await peerExtensionSdk.getState();
+ * if (state === "needs_install" || !isPeerExtensionMetadataBridgeAvailable()) {
+ *   peerExtensionSdk.openInstallPage();
+ * } else if (state === "needs_connection") {
+ *   await peerExtensionSdk.requestConnection();
+ * } else {
+ *   peerExtensionSdk.authenticate({
+ *     actionType: "transfer_paypal",
+ *     captureMode: "sellerCredential",
+ *     platform: "paypal",
+ *   });
+ *   // Pass the captured metadata to completePeerExtensionRegistration(...), then retry.
+ * }
+ * ```
+ */
+
+type PeerConnectionStatus = "connected" | "disconnected" | "pending";
+type PeerMetadataCaptureMode = "buyerTee" | "sellerCredential";
+type PeerMetadataProviderConfig = Record<string, unknown>;
+type PeerAuthenticateParams = {
+    actionType: string;
+    attestationActionType?: string | null;
+    attestationServiceUrl?: string | null;
+    captureMode?: PeerMetadataCaptureMode;
+    platform: string;
+    providerConfig?: PeerMetadataProviderConfig;
+};
+type PeerBuyerTeePaymentParams = Record<string, string | number | boolean>;
+type PeerBuyerTeePaymentCapture = {
+    encryptedSessionMaterial: string;
+    params?: PeerBuyerTeePaymentParams[];
+};
+type PeerSarCredentialBundle = {
+    bundleSignature: string;
+    credentialExpiresAt: string | null;
+    credentialType: string;
+    credentialValidatedAt: string;
+    encryptedBlob: string;
+    encryptedDataKey: string;
+    nonce: string;
+    payeeIdHash: `0x${string}`;
+    platform: string;
+};
+type PeerSarCredentialCapture = {
+    credentialBundle: PeerSarCredentialBundle;
+    offchainId: string;
+};
+type PeerMetadataRow = {
+    amount?: string;
+    currency?: string;
+    date?: string;
+    hidden: boolean;
+    originalIndex: number;
+    params?: PeerBuyerTeePaymentParams;
+    paymentId?: string;
+    recipient?: string;
+    [key: string]: unknown;
+};
+type PeerMetadataMessage = {
+    buyerTeeCapture?: PeerBuyerTeePaymentCapture | null;
+    errorMessage?: string;
+    expiresAt: number;
+    metadata: PeerMetadataRow[];
+    platform: string;
+    requestId: string;
+    sarCredentialCapture?: PeerSarCredentialCapture | null;
+};
+type PeerMetadataMessageCallback = (message: PeerMetadataMessage) => void;
+type PeerExtensionApi = {
+    requestConnection(): Promise<boolean>;
+    checkConnectionStatus(): Promise<PeerConnectionStatus>;
+    getVersion(): Promise<string>;
+    authenticate?: (params: PeerAuthenticateParams) => void;
+    onMetadataMessage?: (callback: PeerMetadataMessageCallback) => () => void;
+    openSidebar?: (route: string) => void;
+    onramp?: (queryString: string, callback: PeerOnrampPreparedTransactionCallback) => void;
+    getOnrampTransaction?: (intentHash: string) => Promise<PeerOnrampPreparedTransactionResult | null>;
+};
+type PeerExtensionWindow = Window & {
+    peer?: PeerExtensionApi;
+};
+type PeerExtensionSdkOptions = {
+    window?: PeerExtensionWindow;
+};
+type PeerExtensionSdk = {
+    requestConnection(): Promise<boolean>;
+    checkConnectionStatus(): Promise<PeerConnectionStatus>;
+    getVersion(): Promise<string>;
+    authenticate(params: PeerAuthenticateParams): void;
+    onMetadataMessage(callback: PeerMetadataMessageCallback): () => void;
+    openSidebar(route: string): void;
+    onramp(params: PeerExtensionOnrampParams, callback: PeerOnrampPreparedTransactionCallback): void;
+    getOnrampTransaction(intentHash: string): Promise<PeerOnrampPreparedTransactionResult | null>;
+    isAvailable(): boolean;
+    openInstallPage(): void;
+    getState(): Promise<PeerExtensionState>;
+};
+type PeerExtensionState = "needs_install" | "needs_connection" | "ready";
+declare const isPeerExtensionAvailable: (options?: PeerExtensionSdkOptions) => boolean;
+declare const isPeerExtensionMetadataBridgeAvailable: (options?: PeerExtensionSdkOptions) => boolean;
+declare const openPeerExtensionInstallPage: (options?: PeerExtensionSdkOptions) => void;
+declare const getPeerExtensionState: (options?: PeerExtensionSdkOptions) => Promise<PeerExtensionState>;
+declare const createPeerExtensionSdk: (options?: PeerExtensionSdkOptions) => PeerExtensionSdk;
+declare const peerExtensionSdk: PeerExtensionSdk;
+
+type PlatformId = "venmo" | "cashapp" | "chime" | "revolut" | "wise" | "mercadopago" | "zelle" | "paypal" | "monzo" | "n26" | "luxon";
+/**
+ * Extension pre-registration requirement for a platform. When present,
+ * curator's `/v2/makers/create` rejects the maker until the user has
+ * registered their handle with PeerAuth.
+ */
+interface PeerExtensionRegistrationInfo {
+    /** Peer extension provider id. */
+    readonly providerId: string;
+    /** Message shown to the user when curator rejects the maker. */
+    readonly requiredPrompt: string;
+    /** Label for the registration CTA. */
+    readonly ctaLabel: string;
+    /** Optional subtext (e.g. PayPal Business disclaimer). */
+    readonly ctaSubtext?: string;
+    /** Minimum Peer extension version required. */
+    readonly minExtensionVersion: string;
+}
+interface PlatformEntry {
+    readonly id: PlatformId;
+    readonly name: string;
+    readonly currencies: readonly string[];
+    readonly identifier: {
+        readonly label: string;
+        readonly placeholder: string;
+        readonly help: string;
+    };
+    /** Set for platforms that require Peer extension registration (PayPal, Wise). */
+    readonly extensionRegistration?: PeerExtensionRegistrationInfo;
+    validate(input: string): {
+        valid: boolean;
+        normalized: string;
+        error?: string;
+    };
+}
+/**
+ * Extracts the bare PayPal.me username from any accepted input shape
+ * (`paypal.me/user`, `https://paypal.me/user`, `@user`, `user`). Mirrors the
+ * upstream zkp2p-clients normalizer so our offchainId hashes identically.
+ */
+declare function normalizePaypalMeUsername(value: string): string;
+/**
+ * Validates an IBAN using the MOD-97 algorithm (ISO 13616), mirroring
+ * curator's N26 processor so a malformed-but-well-formed IBAN is rejected
+ * client-side before the maker approves USDC + pays gas. Expects no spaces
+ * (the n26 transform strips them and uppercases first).
+ */
+declare function isValidIBAN(iban: string): boolean;
+/** All supported payment platforms. Access via `PLATFORMS.REVOLUT`, `PLATFORMS.WISE`, etc. */
+declare const PLATFORMS: {
+    readonly VENMO: PlatformEntry;
+    readonly CASHAPP: PlatformEntry;
+    readonly CHIME: PlatformEntry;
+    readonly REVOLUT: PlatformEntry;
+    readonly WISE: PlatformEntry;
+    readonly MERCADO_PAGO: PlatformEntry;
+    readonly ZELLE: PlatformEntry;
+    readonly PAYPAL: PlatformEntry;
+    readonly MONZO: PlatformEntry;
+    readonly N26: PlatformEntry;
+    readonly LUXON: PlatformEntry;
+};
+/** Platform key type for PLATFORMS constant. */
+type PlatformKey = keyof typeof PLATFORMS;
+/** Taker account tiers curator gates fills behind, lowest → highest. */
+type PlatformTier = "PEASANT" | "PEER" | "PLUS" | "PRO" | "PLATINUM";
+interface PlatformLimits {
+    /**
+     * Hard per-platform max fill (USD) curator enforces regardless of taker
+     * tier. Omitted when a platform has no absolute cap — its effective limit is
+     * `capMultiplier × tierCap`, which depends on the taker's tier and so can't
+     * be known when a maker creates a deposit.
+     */
+    readonly platformCapUsd?: number;
+    /**
+     * Minimum taker account tier curator requires to fill on this platform.
+     * Omitted when any tier may fill.
+     */
+    readonly minTier?: PlatformTier;
+}
+/**
+ * Per-platform constraints mirrored from curator's `PLATFORM_RISK_CONFIG`
+ * (curator `platformRisk.ts`). ONLY the absolute, tier-independent rules are
+ * mirrored: PayPal's PLUS-tier gate and the hard Venmo / N26 caps. Per-tier
+ * effective caps are intentionally excluded — they're `capMultiplier × tierCap`
+ * and depend on the taker, not the maker. Curator exposes no public "list
+ * limits" endpoint, so this static mirror can drift if a PeerHQ admin changes
+ * a value; treat as an advisory hint, never as enforcement — curator remains
+ * the source of truth at intent-signing time.
+ */
+declare const PLATFORM_LIMITS: Partial<Record<PlatformId, PlatformLimits>>;
+/** Returns curator's constraints for a platform id, or null if unconstrained. */
+declare function getPlatformLimits(platform: string): PlatformLimits | null;
+/** Flat payload accepted by `POST /v2/makers/create`. */
+interface PayeeDepositData {
+    offchainId: string;
+    telegramUsername?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CompletePeerExtensionRegistrationInput {
+    readonly platform: PlatformEntry;
+    readonly identifier: string;
+    readonly capturedMetadata: PeerMetadataMessage;
+}
+interface CompletePeerExtensionRegistrationResult {
+    readonly processorName: "paypal" | "wise";
+    readonly offchainId: string;
+    readonly hashedOnchainId: string;
+    readonly sellerCredentialResponse: CuratorSellerCredentialUploadResponse;
+    readonly sellerCredentialStatus: CuratorSellerCredentialUploadResponse["responseObject"];
+}
+/**
+ * Returns the extension-registration metadata for a platform, or `null` if
+ * the platform does not require Peer-extension pre-registration. Use this to
+ * decide whether to surface an "Install / Connect Peer Extension" CTA in
+ * your UI before calling `offramp()` for PayPal or Wise.
+ */
+declare function getPeerExtensionRegistrationInfo(platform: string): PeerExtensionRegistrationInfo | null;
+declare function getPeerExtensionRegistrationAuthParams(platform: string, options?: {
+    attestationServiceUrl?: string | null;
+}): PeerAuthenticateParams | null;
+declare function completePeerExtensionRegistration(input: CompletePeerExtensionRegistrationInput): Promise<CompletePeerExtensionRegistrationResult>;
+/**
+ * True when a failed `/v2/makers/create` response should be treated as
+ * "maker needs to register in the Peer extension first". Platforms without
+ * an `extensionRegistration` config always return false. A 400 on a
+ * registration-required platform is treated as registration required, and
+ * so is any response whose message contains curator's phrasing.
+ */
+declare function isPeerExtensionRegistrationError(platform: string, message?: string | null, statusCode?: number | null): boolean;
+
+interface CurrencyEntry {
+    readonly code: string;
+    readonly name: string;
+    readonly symbol: string;
+    readonly countryCode: string;
+}
+type CurrencyMap = {
+    readonly [K in keyof typeof currencyInfo]: CurrencyEntry;
+};
+/** All supported currencies with metadata. Access via `CURRENCIES.EUR.symbol` etc. */
+declare const CURRENCIES: CurrencyMap;
+
+declare const OFFRAMP_ERROR_CODES: {
+    readonly VALIDATION: "VALIDATION";
+    readonly APPROVAL_FAILED: "APPROVAL_FAILED";
+    readonly REGISTRATION_FAILED: "REGISTRATION_FAILED";
+    /**
+     * Curator rejected the maker because the user has not registered this
+     * handle in the Peer extension yet. Thrown from `offramp()` for PayPal
+     * and Wise when `/v2/makers/create` returns 400 or a "creating the maker"
+     * message. Recover by prompting the user through the Peer extension via
+     * `usePeerExtensionRegistration(platform)` (React) or
+     * `completePeerExtensionRegistration(...)`, then retrying `offramp()`.
+     */
+    readonly EXTENSION_REGISTRATION_REQUIRED: "EXTENSION_REGISTRATION_REQUIRED";
+    readonly DEPOSIT_FAILED: "DEPOSIT_FAILED";
+    readonly CONFIRMATION_FAILED: "CONFIRMATION_FAILED";
+    readonly DELEGATION_FAILED: "DELEGATION_FAILED";
+    readonly USER_CANCELLED: "USER_CANCELLED";
+    readonly UNSUPPORTED: "UNSUPPORTED";
+};
+type OfframpErrorCode = (typeof OFFRAMP_ERROR_CODES)[keyof typeof OFFRAMP_ERROR_CODES];
+interface OfframpParams {
+    /** USDC amount as decimal string, min 1. */
+    amount: string;
+    /** Payment platform — use `PLATFORMS.REVOLUT` etc. */
+    platform: PlatformEntry;
+    /** Fiat currency — use `CURRENCIES.EUR` etc. */
+    currency: CurrencyEntry;
+    /** Platform-specific identifier (username, email, IBAN). */
+    identifier: string;
+    /** Optional: restrict the deposit to this taker wallet (OTC private order). */
+    otcTaker?: string;
+    /** Optional SDK-only referral metadata for telemetry attribution. */
+    referralId?: string;
+    /** Optional SDK-only integrator metadata for telemetry attribution. */
+    integratorId?: string;
+    /**
+     * Optional per-wallet key to replay the first successful result for 10 minutes.
+     *
+     * Browser-only: the replay cache is backed by `sessionStorage` and is a no-op
+     * in Node/worker runtimes (no duplicate protection there). It is honored only
+     * by the `Offramp` class (`createDeposit`) / the `useOfframp` hook — the
+     * standalone `offramp()` function ignores it. For server-side dedup, call
+     * `deposits(walletAddress)` and reuse an existing open deposit before creating
+     * a new one (the SDK's own resume behavior does this for the delegation step).
+     */
+    idempotencyKey?: string;
+}
+interface OfframpResult {
+    depositId: string;
+    txHash: string;
+    /** Whether an existing undelegated deposit was resumed. */
+    resumed: boolean;
+    /** OTC link for the taker, present when `otcTaker` was provided. */
+    otcLink?: string;
+}
+type OfframpStep = "approving" | "registering" | "depositing" | "confirming" | "delegating" | "restricting" | "resuming" | "done";
+type OfframpState = "idle" | "approving" | "registering" | "depositing" | "confirming" | "delegating" | "done" | "error";
+interface OfframpProgress {
+    step: OfframpStep;
+    txHash?: string;
+    depositId?: string;
+}
+type OnProgress = (progress: OfframpProgress) => void;
+type DepositStatus = "active" | "empty" | "closed";
+interface OfframpQuoteInput {
+    amount: string;
+    currency: CurrencyEntry;
+    platform: PlatformEntry;
+}
+interface OfframpQuote {
+    amountUsdc: number;
+    expectedFiat: number;
+    effectiveRate: number;
+    vaultSpreadBps: number;
+}
+interface OfframpVaultStatus {
+    rateManagerId: string;
+    rateManagerAddress: string;
+    /**
+     * Delegate vault manager fee in basis points (currently 10 = 0.10%). Charged
+     * by the vault's rate manager on each fill and deducted from the USDC released
+     * to the buyer; not added to the maker's deposit cost. See the README "Fees".
+     */
+    feeRateBps: number;
+    escrow: string;
+    isActive: boolean;
+}
+interface OfframpCreateOptions {
+    integratorId?: string;
+    referralId?: string;
+    telemetry?: boolean;
+    /**
+     * Override the curator REST base URL (default `https://api.zkp2p.xyz`) used
+     * for maker registration/validation and the SDK's REST calls. For
+     * testing/proxying/mocking only — the indexer and Base RPC always target
+     * mainnet. Honored by the `Offramp` class (`createDeposit`); absent ⇒ default
+     * behavior is unchanged.
+     */
+    apiBaseUrl?: string;
+}
+interface DepositInfo {
+    /** Numeric deposit ID. Pass this to `close()`. */
+    depositId: string;
+    /** Composite ID (escrowAddress_depositId). */
+    compositeId: string;
+    /** Creation transaction hash. */
+    txHash?: string;
+    status: DepositStatus;
+    remainingUsdc: number;
+    outstandingUsdc: number;
+    totalTakenUsdc: number;
+    fulfilledIntents: number;
+    paymentMethods: string[];
+    currencies: string[];
+    rateSource: string;
+    delegated: boolean;
+    escrowAddress: string;
+}
+
+/**
+ * Error thrown when curator's `/v2/makers/create` returns a non-success
+ * response. Preserves the HTTP status so callers can distinguish a
+ * "needs Peer-extension registration" 400 from a transient server error.
+ *
+ * `offramp()` re-raises this as an {@link OfframpError} with code
+ * `EXTENSION_REGISTRATION_REQUIRED` (for PayPal/Wise 400s) or
+ * `REGISTRATION_FAILED` (for any other curator error); `MakersCreateError`
+ * is attached as the `cause`.
+ */
+declare class MakersCreateError extends Error {
+    readonly status: number | null;
+    readonly body: string;
+    constructor(message: string, status: number | null, body: string);
+}
+declare class OfframpError extends Error {
+    readonly code: OfframpErrorCode;
+    readonly step?: OfframpStep;
+    readonly cause?: unknown;
+    readonly txHash?: string;
+    readonly depositId?: string;
+    constructor(message: string, code: OfframpErrorCode, step?: OfframpStep, cause?: unknown, details?: {
+        txHash?: string;
+        depositId?: string;
+    });
+}
+
+export { isValidIBAN as $, type PeerExtensionState as A, type PeerExtensionWindow as B, CURRENCIES as C, type DepositInfo as D, type PeerMetadataCaptureMode as E, type PeerMetadataMessage as F, type PeerMetadataMessageCallback as G, type PeerMetadataProviderConfig as H, type PeerMetadataRow as I, type PeerSarCredentialBundle as J, type PeerSarCredentialCapture as K, type PlatformEntry as L, MakersCreateError as M, type PlatformKey as N, OFFRAMP_ERROR_CODES as O, PLATFORMS as P, type PlatformLimits as Q, type PlatformTier as R, completePeerExtensionRegistration as S, createPeerExtensionSdk as T, getPeerExtensionRegistrationAuthParams as U, getPeerExtensionRegistrationInfo as V, getPeerExtensionState as W, getPlatformLimits as X, isPeerExtensionAvailable as Y, isPeerExtensionMetadataBridgeAvailable as Z, isPeerExtensionRegistrationError as _, type CompletePeerExtensionRegistrationInput as a, normalizePaypalMeUsername as a0, openPeerExtensionInstallPage as a1, peerExtensionSdk as a2, type CompletePeerExtensionRegistrationResult as b, type CurrencyEntry as c, type DepositStatus as d, type OfframpCreateOptions as e, OfframpError as f, type OfframpErrorCode as g, type OfframpParams as h, type OfframpProgress as i, type OfframpQuote as j, type OfframpQuoteInput as k, type OfframpResult as l, type OfframpState as m, type OfframpStep as n, type OfframpVaultStatus as o, type OnProgress as p, PLATFORM_LIMITS as q, type PayeeDepositData as r, type PeerAuthenticateParams as s, type PeerBuyerTeePaymentCapture as t, type PeerBuyerTeePaymentParams as u, type PeerConnectionStatus as v, type PeerExtensionApi as w, type PeerExtensionRegistrationInfo as x, type PeerExtensionSdk as y, type PeerExtensionSdkOptions as z };