@usdctofiat/offramp 0.1.5 → 0.2.0

package/dist/index.d.cts

@@ -1,38 +1,62 @@
 import { WalletClient } from 'viem';
-import { O as OfframpParams, a as OnProgress, b as OfframpResult, D as DepositInfo, P as PlatformInfo, c as Platform, C as CurrencyInfo, d as OfframpStep } from './types-DjkNvO-k.cjs';
-export { e as CURRENCIES, f as Currency, g as DepositStatus, h as OfframpProgress, i as PAYMENT_PLATFORMS, S as SUPPORTED_CURRENCIES } from './types-DjkNvO-k.cjs';
+import { O as OfframpParams, a as OnProgress, b as OfframpResult, D as DepositInfo, P as PlatformInfo, c as Platform, C as CurrencyInfo } from './errors-DQqv1xfX.cjs';
+export { d as CURRENCIES, e as Currency, f as DepositStatus, g as OfframpError, h as OfframpErrorCode, i as OfframpProgress, j as OfframpStep, k as PAYMENT_PLATFORMS, S as SUPPORTED_CURRENCIES } from './errors-DQqv1xfX.cjs';
 
 declare class Offramp {
     /**
      * Create an offramp deposit: approve USDC, register payee, create deposit,
      * confirm on-chain, and delegate to the vault. All in one call.
+     *
+     * @param walletClient - viem WalletClient with an account
+     * @param params - Deposit parameters (amount, platform, currency, identifier)
+     * @param onProgress - Optional callback for step-by-step progress updates
      */
     createDeposit(walletClient: WalletClient, params: OfframpParams, onProgress?: OnProgress): Promise<OfframpResult>;
     /**
-     * Fetch deposits for a wallet address. Returns active, empty, and closed deposits
-     * sorted by status (active first) then recency.
+     * Fetch all deposits for a wallet address. Read-only, no wallet needed.
+     * Returns active, empty, and closed deposits sorted by status then recency.
      */
     getDeposits(walletAddress: string): Promise<DepositInfo[]>;
     /**
-     * Delegate an existing deposit to the vault. Use this to:
+     * Find a deposit by its transaction hash. Useful for recovering from
+     * CONFIRMATION_FAILED errors where you have a txHash but no depositId.
+     *
+     * @param walletAddress - The depositor's wallet address
+     * @param txHash - The transaction hash from createDeposit
+     */
+    getDepositByTxHash(walletAddress: string, txHash: string): Promise<DepositInfo | null>;
+    /**
+     * Delegate an existing deposit to the Delegate vault. Use this to:
      * - Retry after a DELEGATION_FAILED error
      * - Delegate a deposit created outside the SDK
      * - Delegate a deposit created via usdctofiat.xyz
+     *
+     * @param walletClient - viem WalletClient with the deposit owner's account
+     * @param depositId - The numeric deposit ID (not the composite escrow_id format)
      */
     delegateDeposit(walletClient: WalletClient, depositId: string, escrowAddress?: string): Promise<string>;
     /**
-     * Withdraw and close a deposit, returning remaining USDC to the wallet.
+     * Withdraw remaining USDC and close a deposit.
+     *
+     * @param walletClient - viem WalletClient with the deposit owner's account
+     * @param depositId - The numeric deposit ID (not the composite escrow_id format)
      */
     withdrawDeposit(walletClient: WalletClient, depositId: string, escrowAddress?: string): Promise<string>;
-    /** List available payment platforms and their supported currencies. */
+    /** List available payment platforms with currencies, labels, and format requirements. */
     getPlatforms(): PlatformInfo[];
     /** Get supported currencies for a specific platform. */
     getCurrencies(platform: Platform): string[];
-    /** Get currency metadata (symbol, name, country code) for a currency code. */
+    /**
+     * Get currency metadata for UI rendering.
+     * @returns Symbol (€), full name (Euro), and country code (eu), or null if unsupported.
+     */
     getCurrencyInfo(code: string): CurrencyInfo | null;
     /** Get all supported currencies with metadata. */
     getAllCurrencies(): CurrencyInfo[];
-    /** Validate a payment identifier for a platform without creating a deposit. */
+    /**
+     * Validate and normalize a payment identifier for a platform.
+     * Strips leading @/$ characters, validates format (email, IBAN, etc).
+     */
     validateIdentifier(platform: Platform, identifier: string): {
         valid: boolean;
         normalized: string;
@@ -40,17 +64,4 @@ declare class Offramp {
     };
 }
 
-type OfframpErrorCode = "VALIDATION" | "APPROVAL_FAILED" | "REGISTRATION_FAILED" | "DEPOSIT_FAILED" | "CONFIRMATION_FAILED" | "DELEGATION_FAILED" | "USER_CANCELLED" | "UNSUPPORTED";
-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 { CurrencyInfo, DepositInfo, Offramp, OfframpError, type OfframpErrorCode, OfframpParams, OfframpResult, OfframpStep, OnProgress, Platform, PlatformInfo };
+export { CurrencyInfo, DepositInfo, Offramp, OfframpParams, OfframpResult, OnProgress, Platform, PlatformInfo };

package/dist/index.d.ts

@@ -1,38 +1,62 @@
 import { WalletClient } from 'viem';
-import { O as OfframpParams, a as OnProgress, b as OfframpResult, D as DepositInfo, P as PlatformInfo, c as Platform, C as CurrencyInfo, d as OfframpStep } from './types-DjkNvO-k.js';
-export { e as CURRENCIES, f as Currency, g as DepositStatus, h as OfframpProgress, i as PAYMENT_PLATFORMS, S as SUPPORTED_CURRENCIES } from './types-DjkNvO-k.js';
+import { O as OfframpParams, a as OnProgress, b as OfframpResult, D as DepositInfo, P as PlatformInfo, c as Platform, C as CurrencyInfo } from './errors-DQqv1xfX.js';
+export { d as CURRENCIES, e as Currency, f as DepositStatus, g as OfframpError, h as OfframpErrorCode, i as OfframpProgress, j as OfframpStep, k as PAYMENT_PLATFORMS, S as SUPPORTED_CURRENCIES } from './errors-DQqv1xfX.js';
 
 declare class Offramp {
     /**
      * Create an offramp deposit: approve USDC, register payee, create deposit,
      * confirm on-chain, and delegate to the vault. All in one call.
+     *
+     * @param walletClient - viem WalletClient with an account
+     * @param params - Deposit parameters (amount, platform, currency, identifier)
+     * @param onProgress - Optional callback for step-by-step progress updates
      */
     createDeposit(walletClient: WalletClient, params: OfframpParams, onProgress?: OnProgress): Promise<OfframpResult>;
     /**
-     * Fetch deposits for a wallet address. Returns active, empty, and closed deposits
-     * sorted by status (active first) then recency.
+     * Fetch all deposits for a wallet address. Read-only, no wallet needed.
+     * Returns active, empty, and closed deposits sorted by status then recency.
      */
     getDeposits(walletAddress: string): Promise<DepositInfo[]>;
     /**
-     * Delegate an existing deposit to the vault. Use this to:
+     * Find a deposit by its transaction hash. Useful for recovering from
+     * CONFIRMATION_FAILED errors where you have a txHash but no depositId.
+     *
+     * @param walletAddress - The depositor's wallet address
+     * @param txHash - The transaction hash from createDeposit
+     */
+    getDepositByTxHash(walletAddress: string, txHash: string): Promise<DepositInfo | null>;
+    /**
+     * Delegate an existing deposit to the Delegate vault. Use this to:
      * - Retry after a DELEGATION_FAILED error
      * - Delegate a deposit created outside the SDK
      * - Delegate a deposit created via usdctofiat.xyz
+     *
+     * @param walletClient - viem WalletClient with the deposit owner's account
+     * @param depositId - The numeric deposit ID (not the composite escrow_id format)
      */
     delegateDeposit(walletClient: WalletClient, depositId: string, escrowAddress?: string): Promise<string>;
     /**
-     * Withdraw and close a deposit, returning remaining USDC to the wallet.
+     * Withdraw remaining USDC and close a deposit.
+     *
+     * @param walletClient - viem WalletClient with the deposit owner's account
+     * @param depositId - The numeric deposit ID (not the composite escrow_id format)
      */
     withdrawDeposit(walletClient: WalletClient, depositId: string, escrowAddress?: string): Promise<string>;
-    /** List available payment platforms and their supported currencies. */
+    /** List available payment platforms with currencies, labels, and format requirements. */
     getPlatforms(): PlatformInfo[];
     /** Get supported currencies for a specific platform. */
     getCurrencies(platform: Platform): string[];
-    /** Get currency metadata (symbol, name, country code) for a currency code. */
+    /**
+     * Get currency metadata for UI rendering.
+     * @returns Symbol (€), full name (Euro), and country code (eu), or null if unsupported.
+     */
     getCurrencyInfo(code: string): CurrencyInfo | null;
     /** Get all supported currencies with metadata. */
     getAllCurrencies(): CurrencyInfo[];
-    /** Validate a payment identifier for a platform without creating a deposit. */
+    /**
+     * Validate and normalize a payment identifier for a platform.
+     * Strips leading @/$ characters, validates format (email, IBAN, etc).
+     */
     validateIdentifier(platform: Platform, identifier: string): {
         valid: boolean;
         normalized: string;
@@ -40,17 +64,4 @@ declare class Offramp {
     };
 }
 
-type OfframpErrorCode = "VALIDATION" | "APPROVAL_FAILED" | "REGISTRATION_FAILED" | "DEPOSIT_FAILED" | "CONFIRMATION_FAILED" | "DELEGATION_FAILED" | "USER_CANCELLED" | "UNSUPPORTED";
-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 { CurrencyInfo, DepositInfo, Offramp, OfframpError, type OfframpErrorCode, OfframpParams, OfframpResult, OfframpStep, OnProgress, Platform, PlatformInfo };
+export { CurrencyInfo, DepositInfo, Offramp, OfframpParams, OfframpResult, OnProgress, Platform, PlatformInfo };

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   OfframpError,
   PAYMENT_PLATFORMS,
   SUPPORTED_CURRENCIES
-} from "./chunk-3WIEHXOV.js";
+} from "./chunk-E4AJU3FA.js";
 export {
   CURRENCIES,
   Offramp,

package/dist/react.cjs

@@ -31,6 +31,20 @@ var import_react = require("react");
 var import_viem2 = require("viem");
 var import_sdk4 = require("@zkp2p/sdk");
 
+// src/types.ts
+var PLATFORMS = [
+  "venmo",
+  "cashapp",
+  "chime",
+  "revolut",
+  "wise",
+  "mercadopago",
+  "zelle",
+  "paypal",
+  "monzo",
+  "n26"
+];
+
 // src/deposit.ts
 var import_viem = require("viem");
 var import_chains = require("viem/chains");
@@ -61,22 +75,6 @@ var PAYEE_REGISTRATION_TIMEOUT_MS = 8e3;
 // src/platforms.ts
 var import_sdk2 = require("@zkp2p/sdk");
 var import_zod = require("zod");
-
-// src/types.ts
-var PLATFORMS = [
-  "venmo",
-  "cashapp",
-  "chime",
-  "revolut",
-  "wise",
-  "mercadopago",
-  "zelle",
-  "paypal",
-  "monzo",
-  "n26"
-];
-
-// src/platforms.ts
 var ZELLE_HASH_LOOKUP_NAMES = ["zelle", "zelle-bofa", "zelle-chase", "zelle-citi"];
 var PAYMENT_CATALOG = (0, import_sdk2.getPaymentMethodsCatalog)(BASE_CHAIN_ID, RUNTIME_ENV);
 var FALLBACK_CURRENCIES = {
@@ -590,6 +588,14 @@ async function createOfframpDeposit(walletClient, params, onProgress) {
 }
 
 // src/client.ts
+var indexerClient = null;
+function getIndexerService() {
+  if (!indexerClient) {
+    const client = new import_sdk4.IndexerClient(`${API_BASE_URL.replace(/\/+$/, "")}`);
+    indexerClient = new import_sdk4.IndexerDepositService(client);
+  }
+  return indexerClient;
+}
 function toBigInt(value) {
   try {
     return BigInt(value || "0");
@@ -609,7 +615,7 @@ function resolveMethodNames(hashes) {
   const names = /* @__PURE__ */ new Set();
   for (const { paymentMethodHash } of hashes) {
     const normalized = paymentMethodHash.toLowerCase();
-    for (const platform of ["venmo", "cashapp", "chime", "revolut", "wise", "mercadopago", "zelle", "paypal", "monzo", "n26"]) {
+    for (const platform of PLATFORMS) {
       const platformHashes = getPaymentMethodHashes(platform);
       if (platformHashes.some((h) => h.toLowerCase() === normalized)) {
         names.add(getPlatformConfig(platform).name);
@@ -619,63 +625,87 @@ function resolveMethodNames(hashes) {
   }
   return Array.from(names);
 }
+function mapDeposit(d) {
+  const delegationState = (0, import_sdk4.classifyDelegationState)(
+    d.rateManagerId ?? void 0,
+    d.rateManagerAddress ?? void 0,
+    DELEGATE_RATE_MANAGER_ID,
+    RATE_MANAGER_REGISTRY_ADDRESS
+  );
+  return {
+    depositId: d.depositId,
+    compositeId: d.id,
+    txHash: d.txHash,
+    status: resolveStatus(d),
+    remainingUsdc: toUsdc(d.remainingDeposits),
+    outstandingUsdc: toUsdc(d.outstandingIntentAmount),
+    totalTakenUsdc: toUsdc(d.totalAmountTaken),
+    fulfilledIntents: d.fulfilledIntents ?? 0,
+    paymentMethods: resolveMethodNames(d.paymentMethods),
+    currencies: d.currencies.map((c) => {
+      const info = (0, import_sdk4.getCurrencyInfoFromHash)(c.currencyCode);
+      return info?.currencyCode ?? c.currencyCode;
+    }),
+    rateSource: d.currencies[0]?.rateSource || "unknown",
+    delegated: delegationState === "delegated_here",
+    escrowAddress: d.escrowAddress
+  };
+}
+function extractTxHash(result) {
+  if (typeof result === "string") return result;
+  if (result && typeof result === "object" && "hash" in result) return result.hash;
+  if (result && typeof result === "object" && "transactionHash" in result) return result.transactionHash;
+  throw new Error("Unexpected transaction result format");
+}
 var Offramp = class {
   /**
    * Create an offramp deposit: approve USDC, register payee, create deposit,
    * confirm on-chain, and delegate to the vault. All in one call.
+   *
+   * @param walletClient - viem WalletClient with an account
+   * @param params - Deposit parameters (amount, platform, currency, identifier)
+   * @param onProgress - Optional callback for step-by-step progress updates
    */
   async createDeposit(walletClient, params, onProgress) {
     return createOfframpDeposit(walletClient, params, onProgress);
   }
   /**
-   * Fetch deposits for a wallet address. Returns active, empty, and closed deposits
-   * sorted by status (active first) then recency.
+   * Fetch all deposits for a wallet address. Read-only, no wallet needed.
+   * Returns active, empty, and closed deposits sorted by status then recency.
    */
   async getDeposits(walletAddress) {
-    const client = createSdkClient(
-      // Read-only client -- no wallet needed for indexer queries
-      { account: void 0, chain: void 0, transport: void 0 }
-    );
-    const raw = await client.indexer.getDepositsWithRelations(
+    const service = getIndexerService();
+    const raw = await service.fetchDepositsWithRelations(
       { depositor: walletAddress },
       { limit: 100 }
     );
     const statusOrder = { active: 0, empty: 1, closed: 2 };
-    return (raw || []).map((d) => {
-      const delegationState = (0, import_sdk4.classifyDelegationState)(
-        d.rateManagerId ?? void 0,
-        d.rateManagerAddress ?? void 0,
-        DELEGATE_RATE_MANAGER_ID,
-        RATE_MANAGER_REGISTRY_ADDRESS
-      );
-      return {
-        depositId: d.depositId,
-        compositeId: d.id,
-        status: resolveStatus(d),
-        remainingUsdc: toUsdc(d.remainingDeposits),
-        outstandingUsdc: toUsdc(d.outstandingIntentAmount),
-        totalTakenUsdc: toUsdc(d.totalAmountTaken),
-        fulfilledIntents: d.fulfilledIntents ?? 0,
-        paymentMethods: resolveMethodNames(d.paymentMethods),
-        currencies: d.currencies.map((c) => {
-          const info = (0, import_sdk4.getCurrencyInfoFromHash)(c.currencyCode);
-          return info?.currencyCode ?? c.currencyCode;
-        }),
-        rateSource: d.currencies[0]?.rateSource || "unknown",
-        delegated: delegationState === "delegated_here",
-        escrowAddress: d.escrowAddress
-      };
-    }).sort((a, b) => {
+    return (raw || []).map(mapDeposit).sort((a, b) => {
       const diff = statusOrder[a.status] - statusOrder[b.status];
       if (diff !== 0) return diff;
       return Number(BigInt(b.depositId) - BigInt(a.depositId));
     });
   }
   /**
-   * Delegate an existing deposit to the vault. Use this to:
+   * Find a deposit by its transaction hash. Useful for recovering from
+   * CONFIRMATION_FAILED errors where you have a txHash but no depositId.
+   *
+   * @param walletAddress - The depositor's wallet address
+   * @param txHash - The transaction hash from createDeposit
+   */
+  async getDepositByTxHash(walletAddress, txHash) {
+    const deposits = await this.getDeposits(walletAddress);
+    const normalized = txHash.toLowerCase();
+    return deposits.find((d) => d.txHash?.toLowerCase() === normalized) ?? null;
+  }
+  /**
+   * Delegate an existing deposit to the Delegate vault. Use this to:
    * - Retry after a DELEGATION_FAILED error
    * - Delegate a deposit created outside the SDK
    * - Delegate a deposit created via usdctofiat.xyz
+   *
+   * @param walletClient - viem WalletClient with the deposit owner's account
+   * @param depositId - The numeric deposit ID (not the composite escrow_id format)
    */
   async delegateDeposit(walletClient, depositId, escrowAddress) {
     const client = createSdkClient(walletClient);
@@ -686,10 +716,13 @@ var Offramp = class {
       escrowAddress: escrowAddress || ESCROW_ADDRESS,
       txOverrides: { referrer: [REFERRER] }
     });
-    return typeof result === "string" ? result : result.hash;
+    return extractTxHash(result);
   }
   /**
-   * Withdraw and close a deposit, returning remaining USDC to the wallet.
+   * Withdraw remaining USDC and close a deposit.
+   *
+   * @param walletClient - viem WalletClient with the deposit owner's account
+   * @param depositId - The numeric deposit ID (not the composite escrow_id format)
    */
   async withdrawDeposit(walletClient, depositId, escrowAddress) {
     const client = createSdkClient(walletClient);
@@ -698,9 +731,9 @@ var Offramp = class {
       escrowAddress: escrowAddress || ESCROW_ADDRESS,
       txOverrides: { referrer: [REFERRER] }
     });
-    return typeof result === "string" ? result : result.hash;
+    return extractTxHash(result);
   }
-  /** List available payment platforms and their supported currencies. */
+  /** List available payment platforms with currencies, labels, and format requirements. */
   getPlatforms() {
     return getPlatforms();
   }
@@ -708,7 +741,10 @@ var Offramp = class {
   getCurrencies(platform) {
     return getCurrencies(platform);
   }
-  /** Get currency metadata (symbol, name, country code) for a currency code. */
+  /**
+   * Get currency metadata for UI rendering.
+   * @returns Symbol (€), full name (Euro), and country code (eu), or null if unsupported.
+   */
   getCurrencyInfo(code) {
     const info = import_sdk4.currencyInfo[code];
     if (!info) return null;
@@ -725,7 +761,10 @@ var Offramp = class {
       return this.getCurrencyInfo(code);
     }).filter(Boolean);
   }
-  /** Validate a payment identifier for a platform without creating a deposit. */
+  /**
+   * Validate and normalize a payment identifier for a platform.
+   * Strips leading @/$ characters, validates format (email, IBAN, etc).
+   */
   validateIdentifier(platform, identifier) {
     return validateIdentifier(platform, identifier);
   }
@@ -756,7 +795,7 @@ function useOfframp() {
   }, []);
   const createDeposit = (0, import_react.useCallback)(
     async (walletClient, params) => {
-      if (lockRef.current) throw new Error("Deposit already in progress");
+      if (lockRef.current) throw new OfframpError("Deposit already in progress", "VALIDATION");
       lockRef.current = true;
       setIsLoading(true);
       setError(null);
@@ -773,8 +812,8 @@ function useOfframp() {
         setTxHash(result.txHash);
         return result;
       } catch (err) {
-        const message = err instanceof Error ? err.message : "Offramp failed";
-        setError(message);
+        const offrampError = err instanceof OfframpError ? err : new OfframpError(err instanceof Error ? err.message : "Offramp failed", "DEPOSIT_FAILED");
+        setError(offrampError);
         throw err;
       } finally {
         setIsLoading(false);
@@ -783,21 +822,7 @@ function useOfframp() {
     },
     []
   );
-  const getDeposits = (0, import_react.useCallback)(async (walletAddress) => {
-    return getOfframp().getDeposits(walletAddress);
-  }, []);
-  const delegateDeposit = (0, import_react.useCallback)(
-    async (walletClient, id, escrowAddress) => {
-      return getOfframp().delegateDeposit(walletClient, id, escrowAddress);
-    },
-    []
-  );
-  const withdrawDeposit = (0, import_react.useCallback)(
-    async (walletClient, id, escrowAddress) => {
-      return getOfframp().withdrawDeposit(walletClient, id, escrowAddress);
-    },
-    []
-  );
+  const o = getOfframp();
   return {
     step,
     txHash,
@@ -805,14 +830,15 @@ function useOfframp() {
     error,
     isLoading,
     createDeposit,
-    getDeposits,
-    delegateDeposit,
-    withdrawDeposit,
+    getDeposits: (0, import_react.useCallback)((addr) => o.getDeposits(addr), [o]),
+    getDepositByTxHash: (0, import_react.useCallback)((addr, hash) => o.getDepositByTxHash(addr, hash), [o]),
+    delegateDeposit: (0, import_react.useCallback)((wc, id, esc) => o.delegateDeposit(wc, id, esc), [o]),
+    withdrawDeposit: (0, import_react.useCallback)((wc, id, esc) => o.withdrawDeposit(wc, id, esc), [o]),
     reset,
     getPlatforms,
     getCurrencies,
-    getCurrencyInfo: (code) => getOfframp().getCurrencyInfo(code),
-    getAllCurrencies: () => getOfframp().getAllCurrencies(),
+    getCurrencyInfo: (0, import_react.useCallback)((code) => o.getCurrencyInfo(code), [o]),
+    getAllCurrencies: (0, import_react.useCallback)(() => o.getAllCurrencies(), [o]),
     validateIdentifier
   };
 }