@usdctofiat/offramp 1.1.4 → 2.0.0

package/dist/errors-Deoi_xYZ.d.ts

@@ -0,0 +1,236 @@
+import { currencyInfo } from '@zkp2p/sdk';
+
+type PlatformId = "venmo" | "cashapp" | "chime" | "revolut" | "wise" | "mercadopago" | "zelle" | "paypal" | "monzo" | "n26";
+/**
+ * Describes the Peer browser-extension pre-registration requirement for a
+ * platform. When present, curator's `/v2/makers/create` will reject the maker
+ * until the user has registered their handle inside the Peer (PeerAuth)
+ * extension at `/verify/<providerId>`.
+ *
+ * Drives the {@link isPeerExtensionRegistrationError} check and the React
+ * `usePeerExtensionRegistration` hook in `@usdctofiat/offramp/react`.
+ */
+interface PeerExtensionRegistrationInfo {
+    /**
+     * Upstream provider id — matches the Peer extension verify handler. Used
+     * to build the sidebar route (`/verify/<providerId>`).
+     */
+    readonly providerId: string;
+    /** Human-readable message surfaced when curator rejects the maker. */
+    readonly requiredPrompt: string;
+    /** Label for the install / connect / verify CTA. */
+    readonly ctaLabel: string;
+    /** Optional subtext (e.g. PayPal Business disclaimer). */
+    readonly ctaSubtext?: string;
+    /** Minimum Peer extension version expected for this provider. */
+    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;
+    };
+    /**
+     * Present when curator requires the maker to first register this handle in
+     * the Peer extension before `/v2/makers/create` will succeed. Today this
+     * applies to PayPal and Wise. See `@usdctofiat/offramp/react` for the
+     * `usePeerExtensionRegistration` hook that drives the handshake.
+     */
+    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;
+/** 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;
+};
+/** Platform key type for PLATFORMS constant. */
+type PlatformKey = keyof typeof PLATFORMS;
+/**
+ * Shape curator's `/v2/makers/create` expects since the flat-offchainId
+ * migration (upstream #580). The endpoint hashes `offchainId + processorName`
+ * directly — legacy platform-specific keys (`paypalEmail`, `venmoUsername`,
+ * `wisetag`, …) are no longer accepted.
+ */
+interface PayeeDepositData {
+    offchainId: string;
+    telegramUsername?: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * 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;
+/**
+ * True when a failed `/v2/makers/create` response should be interpreted as
+ * "maker needs to register in the Peer extension first". Platforms without
+ * an `extensionRegistration` config always return false.
+ *
+ * Mirrors upstream `isExtensionRegistrationRequiredPostError`: a 400 status
+ * on a registration-required platform is treated as registration required,
+ * and so is any response whose message contains the curator 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 `peerExtensionSdk`
+     * directly, then call `offramp()` again.
+     */
+    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. */
+    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;
+    feeRateBps: number;
+    escrow: string;
+    isActive: boolean;
+}
+interface OfframpCreateOptions {
+    integratorId?: string;
+    referralId?: string;
+    telemetry?: boolean;
+}
+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 { type CurrencyEntry as C, type DepositInfo as D, MakersCreateError as M, type OfframpParams as O, type PlatformEntry as P, type OnProgress as a, type OfframpResult as b, type OfframpCreateOptions as c, type OfframpQuoteInput as d, type OfframpQuote as e, type OfframpVaultStatus as f, CURRENCIES as g, type DepositStatus as h, OFFRAMP_ERROR_CODES as i, OfframpError as j, type OfframpErrorCode as k, type OfframpProgress as l, type OfframpState as m, type OfframpStep as n, PLATFORMS as o, type PayeeDepositData as p, type PeerExtensionRegistrationInfo as q, type PlatformKey as r, getPeerExtensionRegistrationInfo as s, isPeerExtensionRegistrationError as t, normalizePaypalMeUsername as u };