@usdctofiat/offramp 3.0.3 → 3.1.0

package/dist/{errors-D9bV_DWE.d.ts → errors-DzTiflBh.d.ts}

@@ -1,4 +1,121 @@
-import { currencyInfo } from '@zkp2p/sdk';
+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";
 /**
@@ -97,7 +214,19 @@ declare function getPlatformLimits(platform: string): PlatformLimits | null;
 interface PayeeDepositData {
     offchainId: string;
     telegramUsername?: string;
-    metadata?: Record<string, 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
@@ -106,6 +235,10 @@ interface PayeeDepositData {
  * 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
@@ -136,8 +269,8 @@ declare const OFFRAMP_ERROR_CODES: {
      * 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.
+     * `usePeerExtensionRegistration(platform)` (React) or
+     * `completePeerExtensionRegistration(...)`, then retrying `offramp()`.
      */
     readonly EXTENSION_REGISTRATION_REQUIRED: "EXTENSION_REGISTRATION_REQUIRED";
     readonly DEPOSIT_FAILED: "DEPOSIT_FAILED";
@@ -162,7 +295,16 @@ interface OfframpParams {
     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. */
+    /**
+     * 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 {
@@ -196,6 +338,11 @@ interface OfframpQuote {
 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;
@@ -204,6 +351,14 @@ 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()`. */
@@ -251,4 +406,4 @@ declare class OfframpError extends Error {
     });
 }
 
-export { CURRENCIES as C, type DepositInfo as D, MakersCreateError as M, OFFRAMP_ERROR_CODES as O, PLATFORMS as P, type CurrencyEntry as a, type DepositStatus as b, type OfframpCreateOptions as c, OfframpError as d, type OfframpErrorCode as e, type OfframpParams as f, type OfframpProgress as g, type OfframpQuote as h, type OfframpQuoteInput as i, type OfframpResult as j, type OfframpState as k, type OfframpStep as l, type OfframpVaultStatus as m, type OnProgress as n, PLATFORM_LIMITS as o, type PayeeDepositData as p, type PeerExtensionRegistrationInfo as q, type PlatformEntry as r, type PlatformKey as s, type PlatformLimits as t, type PlatformTier as u, getPeerExtensionRegistrationInfo as v, getPlatformLimits as w, isPeerExtensionRegistrationError as x, isValidIBAN as y, normalizePaypalMeUsername as z };
+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 };