@usdctofiat/offramp 1.3.0 → 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 };

package/dist/index.cjs

@@ -22,12 +22,15 @@ var index_exports = {};
 __export(index_exports, {
   CURRENCIES: () => CURRENCIES,
   ESCROW_ADDRESS: () => ESCROW_ADDRESS,
+  MakersCreateError: () => MakersCreateError,
   OFFRAMP_ERROR_CODES: () => OFFRAMP_ERROR_CODES,
   Offramp: () => Offramp,
   OfframpError: () => OfframpError,
+  PEER_EXTENSION_CHROME_URL: () => import_sdk7.PEER_EXTENSION_CHROME_URL,
   PLATFORMS: () => PLATFORMS,
   close: () => close,
   createOfframp: () => createOfframp,
+  createPeerExtensionSdk: () => import_sdk7.createPeerExtensionSdk,
   createTelemetryContext: () => createTelemetryContext,
   delegate: () => delegate,
   deposits: () => deposits,
@@ -35,7 +38,14 @@ __export(index_exports, {
   emitEvent: () => emitEvent,
   enableOtc: () => enableOtc,
   getOtcLink: () => getOtcLink,
+  getPeerExtensionRegistrationInfo: () => getPeerExtensionRegistrationInfo,
+  getPeerExtensionState: () => import_sdk7.getPeerExtensionState,
+  isPeerExtensionAvailable: () => import_sdk7.isPeerExtensionAvailable,
+  isPeerExtensionRegistrationError: () => isPeerExtensionRegistrationError,
+  normalizePaypalMeUsername: () => normalizePaypalMeUsername,
   offramp: () => offramp,
+  openPeerExtensionInstallPage: () => import_sdk7.openPeerExtensionInstallPage,
+  peerExtensionSdk: () => import_sdk7.peerExtensionSdk,
   sanitizeAttributionId: () => sanitizeAttributionId,
   sendTelemetryEvent: () => sendTelemetryEvent,
   undelegate: () => undelegate
@@ -166,6 +176,17 @@ function resolveSupportedCurrencies(platform) {
   }
   return Array.from(codes).sort();
 }
+function normalizePaypalMeUsername(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  const withoutProtocol = trimmed.replace(/^https?:\/\//i, "").replace(/^www\./i, "");
+  if (/^paypal\.me(?:[?#].*)?$/i.test(withoutProtocol)) return "";
+  const withoutDomain = withoutProtocol.replace(/^paypal\.me\//i, "");
+  const [pathWithoutQuery] = withoutDomain.split(/[?#]/, 1);
+  const sanitizedPath = pathWithoutQuery.replace(/^\/+/, "");
+  const [username] = sanitizedPath.split("/", 1);
+  return username.replace(/^@+/, "").trim().toLowerCase();
+}
 var BLUEPRINTS = {
   venmo: {
     id: "venmo",
@@ -213,7 +234,13 @@ var BLUEPRINTS = {
     placeholder: "wisetag (no @)",
     helperText: "Your Wise @wisetag (no @)",
     validation: import_zod.z.string().min(1).regex(/^[a-zA-Z0-9_-]+$/),
-    transform: (v) => v.replace(/^@+/, "").trim()
+    transform: (v) => v.replace(/^@+/, "").trim(),
+    extensionRegistration: {
+      providerId: "wise",
+      requiredPrompt: "This Wisetag is not registered yet. Verify it in the Peer extension, then refresh and retry with the same Wisetag.",
+      ctaLabel: "Install Peer Extension",
+      minExtensionVersion: "0.4.12"
+    }
   },
   mercadopago: {
     id: "mercadopago",
@@ -234,10 +261,18 @@ var BLUEPRINTS = {
   paypal: {
     id: "paypal",
     name: "PayPal",
-    identifierLabel: "Email",
-    placeholder: "email",
-    helperText: "Email linked to PayPal account",
-    validation: import_zod.z.string().email()
+    identifierLabel: "PayPal.me Username",
+    placeholder: "paypal.me/your-username",
+    helperText: "Your PayPal.me username, not your email",
+    validation: import_zod.z.string().min(1, "PayPal.me username is required").regex(/^[a-z0-9._-]+$/i, "Use your PayPal.me username (letters, numbers, . _ -)"),
+    transform: normalizePaypalMeUsername,
+    extensionRegistration: {
+      providerId: "paypal",
+      requiredPrompt: "This PayPal username is not registered yet. Verify it in the Peer extension, then refresh and retry with the same PayPal username.",
+      ctaLabel: "Install Peer Extension",
+      ctaSubtext: "PayPal Business accounts are not supported at this time.",
+      minExtensionVersion: "0.4.14"
+    }
   },
   monzo: {
     id: "monzo",
@@ -268,6 +303,7 @@ function buildPlatformEntry(bp) {
       placeholder: bp.placeholder,
       help: bp.helperText
     },
+    ...bp.extensionRegistration ? { extensionRegistration: bp.extensionRegistration } : {},
     validate(input) {
       const transformed = bp.transform ? bp.transform(input) : input;
       const result = bp.validation.safeParse(transformed);
@@ -294,6 +330,9 @@ var PLATFORMS = {
   MONZO: buildPlatformEntry(BLUEPRINTS.monzo),
   N26: buildPlatformEntry(BLUEPRINTS.n26)
 };
+function getPlatformById(id) {
+  return Object.values(PLATFORMS).find((p) => p.id === id) ?? null;
+}
 function normalizePaymentMethodLookupName(platform) {
   const normalized = platform.trim().toLowerCase();
   if (!normalized) return null;
@@ -337,34 +376,37 @@ function getPaymentMethodHashes(platform) {
   }
   return Array.from(hashes);
 }
-function buildDepositData(platform, identifier) {
-  switch (platform) {
-    case "venmo":
-      return { venmoUsername: identifier, telegramUsername: "" };
-    case "cashapp":
-      return { cashtag: identifier, telegramUsername: "" };
-    case "chime":
-      return { chimesign: identifier.toLowerCase(), telegramUsername: "" };
-    case "revolut":
-      return { revolutUsername: identifier, telegramUsername: "" };
-    case "wise":
-      return { wisetag: identifier, telegramUsername: "" };
-    case "mercadopago":
-      return { cvu: identifier, telegramUsername: "" };
-    case "zelle":
-      return { zelleEmail: identifier, telegramUsername: "" };
-    case "paypal":
-      return { paypalEmail: identifier, telegramUsername: "" };
-    case "monzo":
-      return { monzoMeUsername: identifier, telegramUsername: "" };
-    case "n26":
-      return { iban: identifier, telegramUsername: "" };
-    default:
-      return { identifier, telegramUsername: "" };
-  }
+function buildDepositData(platform, identifier, telegramUsername = "") {
+  const offchainId = platform === "chime" ? identifier.toLowerCase() : identifier;
+  return telegramUsername ? { offchainId, telegramUsername } : { offchainId };
+}
+function getPeerExtensionRegistrationInfo(platform) {
+  const entry = getPlatformById(platform);
+  return entry?.extensionRegistration ?? null;
+}
+var EXTENSION_REGISTRATION_ERROR_PATTERNS = ["creating the maker", "create the maker"];
+function isPeerExtensionRegistrationError(platform, message, statusCode) {
+  const info = getPeerExtensionRegistrationInfo(platform);
+  if (!info) return false;
+  const normalized = (message ?? "").trim();
+  if (normalized === info.requiredPrompt) return true;
+  if (statusCode === 400) return true;
+  if (!normalized) return false;
+  const lower = normalized.toLowerCase();
+  return EXTENSION_REGISTRATION_ERROR_PATTERNS.some((p) => lower.includes(p));
 }
 
 // src/errors.ts
+var MakersCreateError = class extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "MakersCreateError";
+    this.status = status;
+    this.body = body;
+  }
+};
 var OfframpError = class extends Error {
   code;
   step;
@@ -1153,23 +1195,39 @@ function extractDepositIdFromLogs(logs) {
   }
   return null;
 }
-async function registerPayeeDetails(processorName, depositData) {
+async function registerPayeeDetails(processorName, payload) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), PAYEE_REGISTRATION_TIMEOUT_MS);
   try {
-    const res = await fetch(`${API_BASE_URL}/v1/makers/create`, {
+    const res = await fetch(`${API_BASE_URL}/v2/makers/create`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ processorName, depositData }),
+      body: JSON.stringify({ processorName, ...payload }),
       signal: controller.signal
     });
     if (!res.ok) {
       const txt = await res.text().catch(() => "");
-      throw new Error(`makers/create failed (${res.status}): ${txt || res.statusText}`);
+      let detail = txt || res.statusText;
+      try {
+        const parsed = JSON.parse(txt);
+        if (typeof parsed.message === "string" && parsed.message.trim()) {
+          detail = parsed.message;
+        }
+      } catch {
+      }
+      throw new MakersCreateError(
+        `makers/create failed (${res.status}): ${detail}`,
+        res.status,
+        txt
+      );
     }
     const json = await res.json();
     if (!json.success || !json.responseObject?.hashedOnchainId) {
-      throw new Error(json.message || "makers/create returned no hashedOnchainId");
+      throw new MakersCreateError(
+        json.message || "makers/create returned no hashedOnchainId",
+        json.statusCode ?? null,
+        ""
+      );
     }
     return json.responseObject.hashedOnchainId;
   } finally {
@@ -1371,11 +1429,21 @@ async function offramp(walletClient, params, onProgress, telemetryContext) {
     }
     emitProgress({ step: "registering" });
     let hashedOnchainId;
+    const canonicalName = platformId.startsWith("zelle") ? "zelle" : platformId;
     try {
-      const canonicalName = platformId.startsWith("zelle") ? "zelle" : platformId;
-      const depositData = buildDepositData(platformId, normalizedIdentifier);
-      hashedOnchainId = await registerPayeeDetails(canonicalName, depositData);
+      const payeePayload = buildDepositData(canonicalName, normalizedIdentifier);
+      hashedOnchainId = await registerPayeeDetails(canonicalName, payeePayload);
     } catch (err) {
+      const status = err instanceof MakersCreateError ? err.status : null;
+      const message = err instanceof Error ? err.message : String(err);
+      if (isPeerExtensionRegistrationError(canonicalName, message, status)) {
+        throw new OfframpError(
+          `${platform.name} maker is not yet registered in the Peer extension. Verify this handle in the extension, then retry.`,
+          "EXTENSION_REGISTRATION_REQUIRED",
+          "registering",
+          err
+        );
+      }
       throw new OfframpError(
         "Payee registration failed",
         "REGISTRATION_FAILED",
@@ -1713,22 +1781,37 @@ var OFFRAMP_ERROR_CODES = {
   VALIDATION: "VALIDATION",
   APPROVAL_FAILED: "APPROVAL_FAILED",
   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.
+   */
+  EXTENSION_REGISTRATION_REQUIRED: "EXTENSION_REGISTRATION_REQUIRED",
   DEPOSIT_FAILED: "DEPOSIT_FAILED",
   CONFIRMATION_FAILED: "CONFIRMATION_FAILED",
   DELEGATION_FAILED: "DELEGATION_FAILED",
   USER_CANCELLED: "USER_CANCELLED",
   UNSUPPORTED: "UNSUPPORTED"
 };
+
+// src/extension.ts
+var import_sdk7 = require("@zkp2p/sdk");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CURRENCIES,
   ESCROW_ADDRESS,
+  MakersCreateError,
   OFFRAMP_ERROR_CODES,
   Offramp,
   OfframpError,
+  PEER_EXTENSION_CHROME_URL,
   PLATFORMS,
   close,
   createOfframp,
+  createPeerExtensionSdk,
   createTelemetryContext,
   delegate,
   deposits,
@@ -1736,7 +1819,14 @@ var OFFRAMP_ERROR_CODES = {
   emitEvent,
   enableOtc,
   getOtcLink,
+  getPeerExtensionRegistrationInfo,
+  getPeerExtensionState,
+  isPeerExtensionAvailable,
+  isPeerExtensionRegistrationError,
+  normalizePaypalMeUsername,
   offramp,
+  openPeerExtensionInstallPage,
+  peerExtensionSdk,
   sanitizeAttributionId,
   sendTelemetryEvent,
   undelegate