@zkp2p/sdk 0.2.4 → 0.3.0

package/README.md

@@ -73,13 +73,13 @@ const client = new Zkp2pClient({
 - Supported runtime environments: `'production'`, `'preproduction'`, `'staging'`
 - `runtimeEnv` default: `'production'`
 - `rpcUrl`: optional RPC URL override (defaults to wallet's chain RPC)
-- `apiKey`: optional curator API key — enhances some responses (e.g. `getQuote` returns `depositData` when authenticated) but is **not required** for any SDK method
+- `apiKey`: optional curator-issued API key — used when the SDK auto-fetches `signalIntent()` gating signatures and enables richer authenticated `getQuote()` responses with maker `depositData`; curator may also attach `skipTierEnforce` to trusted keys on hybrid intent-signing endpoints
 - `authorizationToken` / `getAuthorizationToken`: optional bearer auth for hybrid client and indexer flows
 - `indexerApiKey`: optional `x-api-key` for indexer proxy auth
 - `indexerUrl` and `baseApiUrl`: override defaults when you are targeting custom deployments
 - `timeouts`: `{ api?: number }` — API timeout in milliseconds (default 15000)
 
-**No API key is required to get started.** `createDeposit`, `registerPayeeDetails`, `getQuote`, `getTakerTier`, and all other SDK methods work without `apiKey` or `authorizationToken`. Auth credentials are optional and only affect response richness (e.g. authenticated quotes include maker `depositData`).
+**No API key is required to get started.** `createDeposit`, `registerPayeeDetails`, `getQuote`, `getTakerTier`, and the rest of the SDK work without `apiKey` or `authorizationToken`. The main tradeoff is that `signalIntent()` only auto-fetches a gating service signature from curator `/v3/intent` when `apiKey` or `authorizationToken` is available; otherwise provide both `gatingServiceSignature` and `signatureExpiration` manually if your integration needs one. Authenticated quotes also include richer maker `depositData`, and curator-issued API keys may carry `skipTierEnforce` on hybrid intent-signing endpoints.
 
 Indexer defaults by environment:
 

package/dist/index.cjs

@@ -1099,15 +1099,9 @@ var init_protocolViewerParsers = __esm({
 
 // src/client/clientUtils.ts
 init_bigint();
+
+// src/utils/address.ts
 var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
-var MIN_ORACLE_SPREAD_BPS = -32768;
-var MAX_ORACLE_SPREAD_BPS = 32767;
-var EMPTY_ORACLE_RATE_CONFIG = {
-  adapter: ZERO_ADDRESS,
-  adapterConfig: "0x",
-  spreadBps: 0,
-  maxStaleness: 0
-};
 var isValidHexAddress = (addr) => {
   if (typeof addr !== "string") return false;
   return /^0x[0-9a-fA-F]{40}$/.test(addr);
@@ -1116,6 +1110,16 @@ var normalizeAddress = (addr) => {
   if (!isValidHexAddress(addr)) return void 0;
   return addr;
 };
+
+// src/client/clientUtils.ts
+var MIN_ORACLE_SPREAD_BPS = -32768;
+var MAX_ORACLE_SPREAD_BPS = 32767;
+var EMPTY_ORACLE_RATE_CONFIG = {
+  adapter: ZERO_ADDRESS,
+  adapterConfig: "0x",
+  spreadBps: 0,
+  maxStaleness: 0
+};
 var parseEscrowAddressFromCompositeDepositId = (depositId) => {
   if (typeof depositId !== "string") return void 0;
   const parts = depositId.split("_");
@@ -1422,9 +1426,6 @@ function parseAPIError(response, responseText) {
   } catch {
     if (responseText && responseText.length < 200) message = responseText;
   }
-  if (response.status === 429) {
-    message = "Too many requests. Please try again later.";
-  }
   return new exports.APIError(message, response.status, { url: response.url });
 }
 async function withRetry(fn, maxRetries = 3, delayMs = 1e3, timeoutMs) {
@@ -1488,11 +1489,13 @@ async function apiSignIntentV3(request, opts) {
   const sig = json?.responseObject?.signedIntent;
   const expStr = json?.responseObject?.intentData?.signatureExpiration ?? json?.responseObject?.signatureExpiration;
   const preIntentHookData = json?.responseObject?.intentData?.preIntentHookData ?? json?.responseObject?.preIntentHookData;
+  const referralFees = json?.responseObject?.intentData?.referralFees ?? json?.responseObject?.referralFees;
   if (!sig || !expStr) throw new Error("v3/intent missing signature or expiration");
   return {
     signature: sig,
     signatureExpiration: BigInt(expStr),
-    preIntentHookData
+    preIntentHookData,
+    referralFees
   };
 }
 
@@ -1919,7 +1922,7 @@ var IntentOperations = class {
     const depositId = parseRawDepositId(params.depositId);
     const amount = typeof params.amount === "bigint" ? params.amount : BigInt(params.amount);
     const conversionRate = typeof params.conversionRate === "bigint" ? params.conversionRate : BigInt(params.conversionRate);
-    const referralFees = referrerFeeConfig !== void 0 ? [
+    let referralFees = referrerFeeConfig !== void 0 ? [
       {
         recipient: referrerFeeConfig.recipient,
         fee: referrerFeeConfigToPreciseUnits(referrerFeeConfig)
@@ -1961,6 +1964,23 @@ var IntentOperations = class {
       gatingServiceSignature = response.signature;
       signatureExpiration = response.signatureExpiration;
       preIntentHookData = response.preIntentHookData ?? preIntentHookData;
+      if (response.referralFees !== void 0) {
+        referralFees = response.referralFees.map((referralFee) => {
+          if (!isValidReferrerFeeRecipient(referralFee.recipient)) {
+            throw new Error("v3/intent returned invalid referral fee recipient");
+          }
+          let fee;
+          try {
+            fee = BigInt(referralFee.fee);
+          } catch {
+            throw new Error("v3/intent returned non-integer referral fee value");
+          }
+          return {
+            recipient: referralFee.recipient,
+            fee
+          };
+        });
+      }
     }
     if (!gatingServiceSignature || !signatureExpiration) {
       throw new Error("Missing gatingServiceSignature/signatureExpiration");
@@ -4590,9 +4610,10 @@ function convertIndexerDepositToEscrowView(deposit, _chainId, _escrowAddress) {
     verifiers
   };
 }
-function convertDepositsForLiquidity(deposits, chainId, escrowAddress) {
+function convertDepositsForLiquidity(deposits, chainId, escrowAddress, options = {}) {
+  const { includePrivateOrderbooks = false } = options;
   return deposits.filter(
-    (d) => d.depositor && d.depositor.toLowerCase() !== ZERO && normalizeAddress2(d.whitelistHookAddress).toLowerCase() === ZERO && d.acceptingIntents && toBigInt(d.remainingDeposits) > 0n && d.status === "ACTIVE"
+    (d) => d.depositor && d.depositor.toLowerCase() !== ZERO && (includePrivateOrderbooks || normalizeAddress2(d.whitelistHookAddress).toLowerCase() === ZERO) && d.acceptingIntents && toBigInt(d.remainingDeposits) > 0n && d.status === "ACTIVE"
   ).map((d) => convertIndexerDepositToEscrowView(d));
 }
 function convertIndexerIntentsToEscrowViews(intents, depositViewsById) {
@@ -5927,13 +5948,11 @@ function convertIndexerDepositToLegacyApiDeposit(deposit) {
     verifiers
   };
 }
-async function apiPostDepositDetails(req, baseApiUrl, timeoutMs, apiKey, authToken) {
+async function apiPostDepositDetails(req, baseApiUrl, timeoutMs, _apiKey, _authToken) {
   return apiFetch({
     url: `${withApiBase(baseApiUrl)}/v1/makers/create`,
     method: "POST",
     body: req,
-    apiKey,
-    authToken,
     timeoutMs
   });
 }
@@ -5943,13 +5962,25 @@ async function apiGetQuote(req, baseApiUrl, timeoutMs, apiKey, authToken) {
       throw new exports.ValidationError("quotesToReturn must be a positive integer", "quotesToReturn");
     }
   }
+  if (!isValidHexAddress(req.user)) {
+    throw new exports.ValidationError("user must be a valid Ethereum address", "user");
+  }
+  if (!isValidHexAddress(req.recipient)) {
+    throw new exports.ValidationError("recipient must be a valid Ethereum address", "recipient");
+  }
+  if (!isValidHexAddress(req.destinationToken)) {
+    throw new exports.ValidationError(
+      "destinationToken must be a valid Ethereum address",
+      "destinationToken"
+    );
+  }
   const isExactFiat = req.isExactFiat !== false;
   const endpoint = isExactFiat ? "exact-fiat" : "exact-token";
   let url = `${withApiBase(baseApiUrl)}/v2/quote/${endpoint}`;
   if (req.quotesToReturn) url += `?quotesToReturn=${req.quotesToReturn}`;
   const requestBody = {
     ...req,
-    [isExactFiat ? "exactFiatAmount" : "exactTokenAmount"]: req.amount,
+    [isExactFiat ? "exactFiatAmount" : "exactTokenAmount"]: String(req.amount),
     amount: void 0,
     isExactFiat: void 0,
     quotesToReturn: void 0
@@ -5964,6 +5995,29 @@ async function apiGetQuote(req, baseApiUrl, timeoutMs, apiKey, authToken) {
     timeoutMs
   });
 }
+async function apiGetQuotesBestByPlatform(req, baseApiUrl, timeoutMs, apiKey, authToken) {
+  const isExactFiat = req.isExactFiat !== false;
+  const endpoint = isExactFiat ? "best-by-platform" : "best-by-platform-exact-token";
+  const url = `${withApiBase(baseApiUrl)}/v2/quote/${endpoint}`;
+  const requestBody = {
+    ...req,
+    [isExactFiat ? "exactFiatAmount" : "exactTokenAmount"]: String(req.amount),
+    amount: void 0,
+    isExactFiat: void 0,
+    referrerFeeConfig: void 0
+  };
+  Object.keys(requestBody).forEach(
+    (key) => requestBody[key] === void 0 && delete requestBody[key]
+  );
+  return apiFetch({
+    url,
+    method: "POST",
+    body: requestBody,
+    apiKey,
+    authToken,
+    timeoutMs
+  });
+}
 async function apiGetPayeeDetails(req, apiKey, baseApiUrl, authToken, timeoutMs) {
   return apiFetch({
     url: `${baseApiUrl.replace(/\/$/, "")}/v1/makers/${req.processorName}/${req.hashedOnchainId}`,
@@ -6030,7 +6084,6 @@ async function apiGetTakerTier(req, apiKey, baseApiUrl, timeoutMs) {
   return apiFetch({
     url: `${withApiBase(baseApiUrl)}${endpoint}`,
     method: "GET",
-    apiKey,
     timeoutMs
   });
 }
@@ -6132,6 +6185,23 @@ var appendReferrerFeeDisplayFields = (quoteResponse, referrerFeeConfig) => {
     }
   };
 };
+var appendReferrerFeeDisplayFieldsToBestByPlatform = (quoteResponse, referrerFeeConfig) => {
+  if (!referrerFeeConfig) {
+    return quoteResponse;
+  }
+  const decimals = quoteResponse.responseObject?.token?.decimals ?? 6;
+  const enrichedPlatformQuotes = (quoteResponse.responseObject?.platformQuotes ?? []).map((platformQuote) => ({
+    ...platformQuote,
+    bestQuote: platformQuote.available && platformQuote.bestQuote ? applyReferrerFeeDisplayFieldsToQuote(platformQuote.bestQuote, referrerFeeConfig, decimals) : platformQuote.bestQuote
+  }));
+  return {
+    ...quoteResponse,
+    responseObject: {
+      ...quoteResponse.responseObject,
+      platformQuotes: enrichedPlatformQuotes
+    }
+  };
+};
 
 // src/utils/erc20.ts
 var ERC20_ABI = [
@@ -6704,7 +6774,9 @@ var Zkp2pClient = class {
      * sending fiat payment to the deposit's payee.
      *
      * If `gatingServiceSignature` is not provided, the SDK will automatically
-     * fetch one from the API (requires `apiKey` or `authorizationToken`).
+     * fetch one from curator `/v3/intent` when `apiKey` or `authorizationToken`
+     * is available. Otherwise you must provide `gatingServiceSignature` and
+     * `signatureExpiration` yourself.
      *
      * **Prepare Mode**: Use `.prepare()` to get the transaction calldata without sending:
      * ```typescript
@@ -8043,15 +8115,7 @@ var Zkp2pClient = class {
       })
     );
     const apiResponses = await Promise.all(
-      depositDetails.map(
-        (req) => apiPostDepositDetails(
-          req,
-          baseApiUrl,
-          this.apiTimeoutMs,
-          this.apiKey,
-          this.authorizationToken
-        )
-      )
+      depositDetails.map((req) => apiPostDepositDetails(req, baseApiUrl, this.apiTimeoutMs))
     );
     if (!apiResponses.every((r) => r?.success)) {
       const failed = apiResponses.find((r) => !r?.success);
@@ -8178,15 +8242,7 @@ var Zkp2pClient = class {
       } else {
         const baseApiUrl = (this.baseApiUrl ?? "https://api.zkp2p.xyz").replace(/\/$/, "");
         const apiResponses = await Promise.all(
-          depositDetails.map(
-            (req) => apiPostDepositDetails(
-              req,
-              baseApiUrl,
-              this.apiTimeoutMs,
-              this.apiKey,
-              this.authorizationToken
-            )
-          )
+          depositDetails.map((req) => apiPostDepositDetails(req, baseApiUrl, this.apiTimeoutMs))
         );
         if (!apiResponses.every((r) => r?.success)) {
           const failed = apiResponses.find((r) => !r?.success);
@@ -8389,6 +8445,57 @@ var Zkp2pClient = class {
     }
     return appendReferrerFeeDisplayFields(quote, referrerFeeConfig);
   }
+  /**
+   * **Supporting Method** - Fetches the best available quote per supported payment platform.
+   *
+   * Returns one quote per platform when available. When authenticated, the API
+   * returns payee details in each platform's best quote.
+   *
+   * @param req - Best-by-platform quote request parameters
+   * @param opts - Optional overrides for API URL and timeout
+   * @returns Best-by-platform quote response
+   */
+  async getQuotesBestByPlatform(req, opts) {
+    const referrerFeeConfig = assertValidReferrerFeeConfig(
+      req.referrerFeeConfig,
+      "getQuotesBestByPlatform"
+    );
+    const baseApiUrl = (opts?.baseApiUrl ?? this.baseApiUrl ?? "https://api.zkp2p.xyz").replace(
+      /\/$/,
+      ""
+    );
+    const timeoutMs = opts?.timeoutMs ?? this.apiTimeoutMs;
+    const reqWithEscrow = { ...req };
+    if (!reqWithEscrow.escrowAddresses || reqWithEscrow.escrowAddresses.length === 0) {
+      const configuredEscrows = this.escrowAddresses.length > 0 ? [...this.escrowAddresses] : this.escrowAddress ? [this.escrowAddress] : [];
+      if (configuredEscrows.length > 0) {
+        reqWithEscrow.escrowAddresses = configuredEscrows;
+      }
+    }
+    const quote = await apiGetQuotesBestByPlatform(
+      reqWithEscrow,
+      baseApiUrl,
+      timeoutMs,
+      this.apiKey,
+      this.authorizationToken
+    );
+    const enrichedQuote = quote ? {
+      ...quote,
+      responseObject: {
+        ...quote.responseObject,
+        platformQuotes: (quote.responseObject?.platformQuotes ?? []).map((platformQuote) => {
+          const bestQuote = platformQuote?.bestQuote;
+          const makerDepositData = bestQuote?.maker?.depositData;
+          if (!bestQuote || !makerDepositData) return platformQuote;
+          return {
+            ...platformQuote,
+            bestQuote: { ...bestQuote, payeeData: makerDepositData }
+          };
+        })
+      }
+    } : quote;
+    return appendReferrerFeeDisplayFieldsToBestByPlatform(enrichedQuote, referrerFeeConfig);
+  }
   // ───────────────────────────────────────────────────────────────────────────
   // SUPPORTING: TAKER TIER
   // (Used by frontends to display taker limits)
@@ -8408,7 +8515,7 @@ var Zkp2pClient = class {
       ""
     );
     const timeoutMs = opts?.timeoutMs ?? this.apiTimeoutMs;
-    return apiGetTakerTier(req, this.apiKey, baseApiUrl, timeoutMs);
+    return apiGetTakerTier(req, void 0, baseApiUrl, timeoutMs);
   }
   // ╔═══════════════════════════════════════════════════════════════════════════╗
   // ║ CORE: ON-CHAIN DEPOSIT VIEWS                                             ║
@@ -8838,6 +8945,7 @@ exports.ZKP2P_IOS_REFERRER = ZKP2P_IOS_REFERRER;
 exports.Zkp2pClient = Zkp2pClient;
 exports.apiGetOwnerDeposits = apiGetOwnerDeposits;
 exports.apiGetPayeeDetails = apiGetPayeeDetails;
+exports.apiGetQuotesBestByPlatform = apiGetQuotesBestByPlatform;
 exports.apiGetTakerTier = apiGetTakerTier;
 exports.apiPostDepositDetails = apiPostDepositDetails;
 exports.apiValidatePayeeDetails = apiValidatePayeeDetails;