@neus/sdk 1.0.1 → 1.0.2

package/README.md

@@ -36,9 +36,6 @@ const client = new NeusClient({
   apiUrl: 'https://api.neus.network',
   // Optional: request timeout (ms)
   timeout: 30000,
-  // Optional: server-side enterprise API key for higher limits on eligible endpoints
-  // (Do not embed API keys in browser apps.)
-  apiKey: process.env.NEUS_API_KEY
 });
 ```
 
@@ -90,36 +87,11 @@ if (!res.data?.eligible) {
 
 Note: `gateCheck` evaluates **existing public/discoverable proofs**. For strict real-time decisions, create a new proof via `client.verify(...)` (or `POST /api/v1/verification`) and use the final status.
 
-## Lookup mode (Premium, server-side only; non-persistent)
+## Resilience & Polling
 
-If you need a **real-time assessment** without minting/storing proofs (no `qHash`), use lookup mode:
-
-- **Endpoint:** `POST /api/v1/verification/lookup`
-- **Auth:** `Authorization: Bearer sk_live_...` (or `sk_test_...`)
-- **Semantics:** runs `external_lookup` verifiers only; **does not** create a proof record
-
-Note: lookup mode is deployment-dependent and is not part of the stable public integrator OpenAPI (`docs/api/public-api.json`).
-
-```javascript
-const res = await client.lookup({
-  // Premium API key (keep server-side only)
-  apiKey: process.env.NEUS_API_KEY,
-  verifierIds: ['wallet-risk'],
-  targetWalletAddress: '0x...',
-  data: { chainId: 1 }
-});
-
-if (!res.data?.verified) {
-  throw new Error('Rejected');
-}
-```
-
-Note: `gateCheck()` and `lookup()` are different tools.
-- Use **`gateCheck()`** when you want to gate based on **existing public/discoverable proofs** (fast, minimal response).
-- Use **`lookup()`** when you want a **fresh, non-persistent** decision (typically billable in hosted deployments).
-- Only combine them if you are intentionally doing a cache-first strategy (gate-check first to avoid unnecessary lookups).
-
-## Private proof reads (owner)
+The SDK is designed for production stability:
+- **Automatic Backoff**: `pollProofStatus()` automatically detects rate limiting (`429`) and applies jittered exponential backoff.
+- **Wallet Identification**: Automatically attaches headers to preferred wallet-based limiting for higher reliability behind shared IPs (NATs).
 
 - Private proof by Proof ID (qHash): `client.getPrivateStatus(qHash, wallet)`
 - Private proofs by wallet/DID: `client.getPrivateProofsByWallet(walletOrDid, { limit, offset }, wallet)`

package/cjs/client.cjs

@@ -159,7 +159,7 @@ function constructVerificationMessage({ walletAddress, signedTimestamp, data, ve
   }
   const chainContext = typeof chain === "string" && chain.length > 0 ? chain : chainId;
   if (!chainContext) {
-    throw new SDKError("chainId is required (or provide chain for preview mode)", "INVALID_CHAIN_CONTEXT");
+    throw new SDKError("chainId is required (or provide chain for universal mode)", "INVALID_CHAIN_CONTEXT");
   }
   if (chainContext === chainId && typeof chainId !== "number") {
     throw new SDKError("chainId must be a number when provided", "INVALID_CHAIN_ID");
@@ -230,6 +230,67 @@ var validateVerifierData = (verifierId, data) => {
       if (!data.owner || !validateWalletAddress(data.owner)) {
         return { valid: false, error: "owner (wallet address) is required" };
       }
+      if (data.content !== void 0 && data.content !== null) {
+        if (typeof data.content !== "string") {
+          return { valid: false, error: "content must be a string when provided" };
+        }
+        if (data.content.length > 5e4) {
+          return { valid: false, error: "content exceeds 50KB inline limit" };
+        }
+      }
+      if (data.contentHash !== void 0 && data.contentHash !== null) {
+        if (typeof data.contentHash !== "string" || !/^0x[a-fA-F0-9]{64}$/.test(data.contentHash)) {
+          return { valid: false, error: "contentHash must be a 32-byte hex string (0x + 64 hex chars) when provided" };
+        }
+      }
+      if (data.contentType !== void 0 && data.contentType !== null) {
+        if (typeof data.contentType !== "string" || data.contentType.length > 100) {
+          return { valid: false, error: "contentType must be a string (max 100 chars) when provided" };
+        }
+        const base = String(data.contentType).split(";")[0].trim().toLowerCase();
+        if (!base || base.includes(" ") || !base.includes("/")) {
+          return { valid: false, error: "contentType must be a valid MIME type when provided" };
+        }
+      }
+      if (data.provenance !== void 0 && data.provenance !== null) {
+        if (!data.provenance || typeof data.provenance !== "object" || Array.isArray(data.provenance)) {
+          return { valid: false, error: "provenance must be an object when provided" };
+        }
+        const dk = data.provenance.declaredKind;
+        if (dk !== void 0 && dk !== null) {
+          const allowed = ["human", "ai", "mixed", "unknown"];
+          if (typeof dk !== "string" || !allowed.includes(dk)) {
+            return { valid: false, error: `provenance.declaredKind must be one of: ${allowed.join(", ")}` };
+          }
+        }
+        const ai = data.provenance.aiContext;
+        if (ai !== void 0 && ai !== null) {
+          if (typeof ai !== "object" || Array.isArray(ai)) {
+            return { valid: false, error: "provenance.aiContext must be an object when provided" };
+          }
+          if (ai.generatorType !== void 0 && ai.generatorType !== null) {
+            const allowed = ["local", "saas", "agent"];
+            if (typeof ai.generatorType !== "string" || !allowed.includes(ai.generatorType)) {
+              return { valid: false, error: `provenance.aiContext.generatorType must be one of: ${allowed.join(", ")}` };
+            }
+          }
+          if (ai.provider !== void 0 && ai.provider !== null) {
+            if (typeof ai.provider !== "string" || ai.provider.length > 64) {
+              return { valid: false, error: "provenance.aiContext.provider must be a string (max 64 chars) when provided" };
+            }
+          }
+          if (ai.model !== void 0 && ai.model !== null) {
+            if (typeof ai.model !== "string" || ai.model.length > 128) {
+              return { valid: false, error: "provenance.aiContext.model must be a string (max 128 chars) when provided" };
+            }
+          }
+          if (ai.runId !== void 0 && ai.runId !== null) {
+            if (typeof ai.runId !== "string" || ai.runId.length > 128) {
+              return { valid: false, error: "provenance.aiContext.runId must be a string (max 128 chars) when provided" };
+            }
+          }
+        }
+      }
       if (data.reference !== void 0) {
         if (!data.reference || typeof data.reference !== "object") {
           return { valid: false, error: "reference must be an object when provided" };
@@ -368,6 +429,17 @@ var validateVerifierData = (verifierId, data) => {
         if (!validTypes.includes(contentType)) {
           return { valid: false, error: `contentType must be one of: ${validTypes.join(", ")}` };
         }
+        const isTextual = contentType.startsWith("text/") || contentType.includes("markdown");
+        if (isTextual) {
+          try {
+            const maxBytes = 50 * 1024;
+            const bytes = typeof TextEncoder !== "undefined" ? new TextEncoder().encode(data.content).length : String(data.content).length;
+            if (bytes > maxBytes) {
+              return { valid: false, error: `content exceeds ${maxBytes} bytes limit for ai-content-moderation verifier (text)` };
+            }
+          } catch {
+          }
+        }
       }
       if (data.content.length > 13653334) {
         return { valid: false, error: "content exceeds 10MB limit" };
@@ -455,7 +527,7 @@ var NeusClient = class {
    *   data: {
    *     content: "My content",
    *     owner: walletAddress, // or ownerAddress for nft-ownership/token-holding
-   *     reference: { type: 'content', id: 'my-unique-identifier' }
+   *     reference: { type: 'other', id: 'my-unique-identifier' }
    *   },
    *   walletAddress: '0x...',
    *   signature: '0x...',
@@ -543,6 +615,7 @@ var NeusClient = class {
             reference: data2.reference,
             ...data2.content && { content: data2.content },
             ...data2.contentHash && { contentHash: data2.contentHash },
+            ...data2.contentType && { contentType: data2.contentType },
             ...data2.provenance && { provenance: data2.provenance }
           };
         } else {
@@ -1037,9 +1110,11 @@ ${bytes.length}`;
       throw new ValidationError("qHash is required");
     }
     const startTime = Date.now();
+    let consecutiveRateLimits = 0;
     while (Date.now() - startTime < timeout) {
       try {
         const status = await this.getStatus(qHash);
+        consecutiveRateLimits = 0;
         if (onProgress && typeof onProgress === "function") {
           onProgress(status.data || status);
         }
@@ -1054,7 +1129,17 @@ ${bytes.length}`;
         if (error instanceof ValidationError) {
           throw error;
         }
-        await new Promise((resolve) => setTimeout(resolve, interval));
+        let nextDelay = interval;
+        if (error instanceof ApiError && Number(error.statusCode) === 429) {
+          consecutiveRateLimits += 1;
+          const exp = Math.min(6, consecutiveRateLimits);
+          const base = Math.max(500, Number(interval) || 0);
+          const max = 3e4;
+          const backoff = Math.min(max, base * Math.pow(2, exp));
+          const jitter = Math.floor(backoff * (0.5 + Math.random() * 0.5));
+          nextDelay = jitter;
+        }
+        await new Promise((resolve) => setTimeout(resolve, nextDelay));
       }
     }
     throw new NetworkError(`Polling timeout after ${timeout}ms`, "POLLING_TIMEOUT");
@@ -1148,7 +1233,7 @@ ${bytes.length}`;
     return true;
   }
   // ============================================================================
-  // GATE & LOOKUP METHODS
+  // PROOFS & GATING METHODS
   // ============================================================================
   /**
    * GET PROOFS BY WALLET - Fetch proofs for a wallet address
@@ -1281,45 +1366,6 @@ ${bytes.length}`;
       nextOffset: response.data?.nextOffset ?? null
     };
   }
-  /**
-   * LOOKUP MODE (API) - Non-persistent server-to-server checks
-   *
-   * Runs `external_lookup` verifiers without minting/storing a proof.
-   * Requires an enterprise API key (server-side only).
-   *
-   * @param {Object} params
-   * @param {string} params.apiKey - Enterprise API key (sk_live_... or sk_test_...)
-   * @param {Array<string>} params.verifierIds - Verifiers to run (external_lookup only)
-   * @param {string} params.targetWalletAddress - Wallet to evaluate
-   * @param {Object} [params.data] - Verifier input data (e.g., contractAddress/tokenId/chainId)
-   * @returns {Promise<Object>} API response ({ success, data })
-   */
-  async lookup(params = {}) {
-    const apiKey = (params.apiKey || "").toString().trim();
-    if (!apiKey || !(apiKey.startsWith("sk_live_") || apiKey.startsWith("sk_test_"))) {
-      throw new ValidationError("lookup requires apiKey (sk_live_* or sk_test_*)");
-    }
-    const verifierIds = Array.isArray(params.verifierIds) ? params.verifierIds.map((v) => String(v).trim()).filter(Boolean) : [];
-    if (verifierIds.length === 0) {
-      throw new ValidationError("lookup requires verifierIds (non-empty array)");
-    }
-    const targetWalletAddress = (params.targetWalletAddress || "").toString().trim();
-    if (!targetWalletAddress || !/^0x[a-fA-F0-9]{40}$/i.test(targetWalletAddress)) {
-      throw new ValidationError("lookup requires a valid targetWalletAddress (0x...)");
-    }
-    const body = {
-      verifierIds,
-      targetWalletAddress,
-      data: params.data && typeof params.data === "object" ? params.data : {}
-    };
-    const response = await this._makeRequest("POST", "/api/v1/verification/lookup", body, {
-      Authorization: `Bearer ${apiKey}`
-    });
-    if (!response.success) {
-      throw new ApiError(`Lookup failed: ${response.error?.message || "Unknown error"}`, response.error);
-    }
-    return response;
-  }
   /**
    * GATE CHECK (API) - Minimal eligibility check
    *
@@ -1337,7 +1383,6 @@ ${bytes.length}`;
    * @param {number} [params.sinceDays] - Optional time window in days
    * @param {number} [params.since] - Optional unix timestamp in ms (lower bound)
    * @param {number} [params.limit] - Max rows to scan (server may clamp)
-   * @param {string} [params.select] - Comma-separated projections (handle,provider,profileUrl,traits.<key>)
    * @returns {Promise<Object>} API response ({ success, data })
    */
   async gateCheck(params = {}) {
@@ -1377,7 +1422,6 @@ ${bytes.length}`;
     setIfPresent("sinceDays", params.sinceDays);
     setIfPresent("since", params.since);
     setIfPresent("limit", params.limit);
-    setCsvIfPresent("select", params.select);
     setIfPresent("referenceType", params.referenceType);
     setIfPresent("referenceId", params.referenceId);
     setIfPresent("tag", params.tag);
@@ -1391,7 +1435,6 @@ ${bytes.length}`;
     setIfPresent("domain", params.domain);
     setIfPresent("minBalance", params.minBalance);
     setIfPresent("provider", params.provider);
-    setIfPresent("handle", params.handle);
     setIfPresent("ownerAddress", params.ownerAddress);
     setIfPresent("riskLevel", params.riskLevel);
     setBoolIfPresent("sanctioned", params.sanctioned);
@@ -1399,8 +1442,6 @@ ${bytes.length}`;
     setIfPresent("primaryWalletAddress", params.primaryWalletAddress);
     setIfPresent("secondaryWalletAddress", params.secondaryWalletAddress);
     setIfPresent("verificationMethod", params.verificationMethod);
-    setIfPresent("traitPath", params.traitPath);
-    setIfPresent("traitGte", params.traitGte);
     const response = await this._makeRequest("GET", `/api/v1/proofs/gate/check?${qs.toString()}`);
     if (!response.success) {
       throw new ApiError(`Gate check failed: ${response.error?.message || "Unknown error"}`, response.error);

package/cjs/index.cjs

@@ -197,7 +197,7 @@ function constructVerificationMessage({ walletAddress, signedTimestamp, data, ve
   }
   const chainContext = typeof chain === "string" && chain.length > 0 ? chain : chainId;
   if (!chainContext) {
-    throw new SDKError("chainId is required (or provide chain for preview mode)", "INVALID_CHAIN_CONTEXT");
+    throw new SDKError("chainId is required (or provide chain for universal mode)", "INVALID_CHAIN_CONTEXT");
   }
   if (chainContext === chainId && typeof chainId !== "number") {
     throw new SDKError("chainId must be a number when provided", "INVALID_CHAIN_ID");
@@ -472,10 +472,14 @@ function validateVerifierPayload(verifierId, data) {
       result.warnings.push("ownerAddress omitted (most deployments default to the signed walletAddress)");
     }
   } else if (id === "ownership-basic") {
-    ["content"].forEach((key) => {
-      if (!(key in data))
-        result.missing.push(key);
-    });
+    if (!("owner" in data))
+      result.missing.push("owner");
+    const hasContent = typeof data.content === "string" && data.content.length > 0;
+    const hasContentHash = typeof data.contentHash === "string" && data.contentHash.length > 0;
+    const hasRefId = typeof data.reference?.id === "string" && data.reference.id.length > 0;
+    if (!hasContent && !hasContentHash && !hasRefId) {
+      result.missing.push("content (or contentHash or reference.id)");
+    }
   }
   if (result.missing.length > 0) {
     result.valid = false;
@@ -648,10 +652,24 @@ var init_utils = __esm({
               }
               setTimeout(pollAttempt, this.currentInterval);
             } catch (error) {
-              reject(new SDKError(
-                `Polling failed: ${error.message}`,
-                "POLLING_ERROR"
-              ));
+              if (error instanceof ValidationError) {
+                reject(error);
+                return;
+              }
+              if (error instanceof ApiError && error.statusCode === 429 || error?.isRetryable === true) {
+                if (this.options.exponentialBackoff) {
+                  const next = Math.min(this.currentInterval * 2, this.options.maxInterval);
+                  const jitter = next * (0.5 + Math.random() * 0.5);
+                  this.currentInterval = Math.max(250, Math.floor(jitter));
+                }
+                if (this.attempt >= this.options.maxAttempts) {
+                  reject(new SDKError("Verification polling timeout", "POLLING_TIMEOUT"));
+                  return;
+                }
+                setTimeout(pollAttempt, this.currentInterval);
+                return;
+              }
+              reject(new SDKError(`Polling failed: ${error.message}`, "POLLING_ERROR"));
             }
           };
           pollAttempt();
@@ -714,6 +732,67 @@ var init_client = __esm({
           if (!data.owner || !validateWalletAddress(data.owner)) {
             return { valid: false, error: "owner (wallet address) is required" };
           }
+          if (data.content !== void 0 && data.content !== null) {
+            if (typeof data.content !== "string") {
+              return { valid: false, error: "content must be a string when provided" };
+            }
+            if (data.content.length > 5e4) {
+              return { valid: false, error: "content exceeds 50KB inline limit" };
+            }
+          }
+          if (data.contentHash !== void 0 && data.contentHash !== null) {
+            if (typeof data.contentHash !== "string" || !/^0x[a-fA-F0-9]{64}$/.test(data.contentHash)) {
+              return { valid: false, error: "contentHash must be a 32-byte hex string (0x + 64 hex chars) when provided" };
+            }
+          }
+          if (data.contentType !== void 0 && data.contentType !== null) {
+            if (typeof data.contentType !== "string" || data.contentType.length > 100) {
+              return { valid: false, error: "contentType must be a string (max 100 chars) when provided" };
+            }
+            const base = String(data.contentType).split(";")[0].trim().toLowerCase();
+            if (!base || base.includes(" ") || !base.includes("/")) {
+              return { valid: false, error: "contentType must be a valid MIME type when provided" };
+            }
+          }
+          if (data.provenance !== void 0 && data.provenance !== null) {
+            if (!data.provenance || typeof data.provenance !== "object" || Array.isArray(data.provenance)) {
+              return { valid: false, error: "provenance must be an object when provided" };
+            }
+            const dk = data.provenance.declaredKind;
+            if (dk !== void 0 && dk !== null) {
+              const allowed = ["human", "ai", "mixed", "unknown"];
+              if (typeof dk !== "string" || !allowed.includes(dk)) {
+                return { valid: false, error: `provenance.declaredKind must be one of: ${allowed.join(", ")}` };
+              }
+            }
+            const ai = data.provenance.aiContext;
+            if (ai !== void 0 && ai !== null) {
+              if (typeof ai !== "object" || Array.isArray(ai)) {
+                return { valid: false, error: "provenance.aiContext must be an object when provided" };
+              }
+              if (ai.generatorType !== void 0 && ai.generatorType !== null) {
+                const allowed = ["local", "saas", "agent"];
+                if (typeof ai.generatorType !== "string" || !allowed.includes(ai.generatorType)) {
+                  return { valid: false, error: `provenance.aiContext.generatorType must be one of: ${allowed.join(", ")}` };
+                }
+              }
+              if (ai.provider !== void 0 && ai.provider !== null) {
+                if (typeof ai.provider !== "string" || ai.provider.length > 64) {
+                  return { valid: false, error: "provenance.aiContext.provider must be a string (max 64 chars) when provided" };
+                }
+              }
+              if (ai.model !== void 0 && ai.model !== null) {
+                if (typeof ai.model !== "string" || ai.model.length > 128) {
+                  return { valid: false, error: "provenance.aiContext.model must be a string (max 128 chars) when provided" };
+                }
+              }
+              if (ai.runId !== void 0 && ai.runId !== null) {
+                if (typeof ai.runId !== "string" || ai.runId.length > 128) {
+                  return { valid: false, error: "provenance.aiContext.runId must be a string (max 128 chars) when provided" };
+                }
+              }
+            }
+          }
           if (data.reference !== void 0) {
             if (!data.reference || typeof data.reference !== "object") {
               return { valid: false, error: "reference must be an object when provided" };
@@ -852,6 +931,17 @@ var init_client = __esm({
             if (!validTypes.includes(contentType)) {
               return { valid: false, error: `contentType must be one of: ${validTypes.join(", ")}` };
             }
+            const isTextual = contentType.startsWith("text/") || contentType.includes("markdown");
+            if (isTextual) {
+              try {
+                const maxBytes = 50 * 1024;
+                const bytes = typeof TextEncoder !== "undefined" ? new TextEncoder().encode(data.content).length : String(data.content).length;
+                if (bytes > maxBytes) {
+                  return { valid: false, error: `content exceeds ${maxBytes} bytes limit for ai-content-moderation verifier (text)` };
+                }
+              } catch {
+              }
+            }
           }
           if (data.content.length > 13653334) {
             return { valid: false, error: "content exceeds 10MB limit" };
@@ -939,7 +1029,7 @@ var init_client = __esm({
        *   data: {
        *     content: "My content",
        *     owner: walletAddress, // or ownerAddress for nft-ownership/token-holding
-       *     reference: { type: 'content', id: 'my-unique-identifier' }
+       *     reference: { type: 'other', id: 'my-unique-identifier' }
        *   },
        *   walletAddress: '0x...',
        *   signature: '0x...',
@@ -1027,6 +1117,7 @@ var init_client = __esm({
                 reference: data2.reference,
                 ...data2.content && { content: data2.content },
                 ...data2.contentHash && { contentHash: data2.contentHash },
+                ...data2.contentType && { contentType: data2.contentType },
                 ...data2.provenance && { provenance: data2.provenance }
               };
             } else {
@@ -1521,9 +1612,11 @@ ${bytes.length}`;
           throw new ValidationError("qHash is required");
         }
         const startTime = Date.now();
+        let consecutiveRateLimits = 0;
         while (Date.now() - startTime < timeout) {
           try {
             const status = await this.getStatus(qHash);
+            consecutiveRateLimits = 0;
             if (onProgress && typeof onProgress === "function") {
               onProgress(status.data || status);
             }
@@ -1538,7 +1631,17 @@ ${bytes.length}`;
             if (error instanceof ValidationError) {
               throw error;
             }
-            await new Promise((resolve) => setTimeout(resolve, interval));
+            let nextDelay = interval;
+            if (error instanceof ApiError && Number(error.statusCode) === 429) {
+              consecutiveRateLimits += 1;
+              const exp = Math.min(6, consecutiveRateLimits);
+              const base = Math.max(500, Number(interval) || 0);
+              const max = 3e4;
+              const backoff = Math.min(max, base * Math.pow(2, exp));
+              const jitter = Math.floor(backoff * (0.5 + Math.random() * 0.5));
+              nextDelay = jitter;
+            }
+            await new Promise((resolve) => setTimeout(resolve, nextDelay));
           }
         }
         throw new NetworkError(`Polling timeout after ${timeout}ms`, "POLLING_TIMEOUT");
@@ -1632,7 +1735,7 @@ ${bytes.length}`;
         return true;
       }
       // ============================================================================
-      // GATE & LOOKUP METHODS
+      // PROOFS & GATING METHODS
       // ============================================================================
       /**
        * GET PROOFS BY WALLET - Fetch proofs for a wallet address
@@ -1765,45 +1868,6 @@ ${bytes.length}`;
           nextOffset: response.data?.nextOffset ?? null
         };
       }
-      /**
-       * LOOKUP MODE (API) - Non-persistent server-to-server checks
-       *
-       * Runs `external_lookup` verifiers without minting/storing a proof.
-       * Requires an enterprise API key (server-side only).
-       *
-       * @param {Object} params
-       * @param {string} params.apiKey - Enterprise API key (sk_live_... or sk_test_...)
-       * @param {Array<string>} params.verifierIds - Verifiers to run (external_lookup only)
-       * @param {string} params.targetWalletAddress - Wallet to evaluate
-       * @param {Object} [params.data] - Verifier input data (e.g., contractAddress/tokenId/chainId)
-       * @returns {Promise<Object>} API response ({ success, data })
-       */
-      async lookup(params = {}) {
-        const apiKey = (params.apiKey || "").toString().trim();
-        if (!apiKey || !(apiKey.startsWith("sk_live_") || apiKey.startsWith("sk_test_"))) {
-          throw new ValidationError("lookup requires apiKey (sk_live_* or sk_test_*)");
-        }
-        const verifierIds = Array.isArray(params.verifierIds) ? params.verifierIds.map((v) => String(v).trim()).filter(Boolean) : [];
-        if (verifierIds.length === 0) {
-          throw new ValidationError("lookup requires verifierIds (non-empty array)");
-        }
-        const targetWalletAddress = (params.targetWalletAddress || "").toString().trim();
-        if (!targetWalletAddress || !/^0x[a-fA-F0-9]{40}$/i.test(targetWalletAddress)) {
-          throw new ValidationError("lookup requires a valid targetWalletAddress (0x...)");
-        }
-        const body = {
-          verifierIds,
-          targetWalletAddress,
-          data: params.data && typeof params.data === "object" ? params.data : {}
-        };
-        const response = await this._makeRequest("POST", "/api/v1/verification/lookup", body, {
-          Authorization: `Bearer ${apiKey}`
-        });
-        if (!response.success) {
-          throw new ApiError(`Lookup failed: ${response.error?.message || "Unknown error"}`, response.error);
-        }
-        return response;
-      }
       /**
        * GATE CHECK (API) - Minimal eligibility check
        *
@@ -1821,7 +1885,6 @@ ${bytes.length}`;
        * @param {number} [params.sinceDays] - Optional time window in days
        * @param {number} [params.since] - Optional unix timestamp in ms (lower bound)
        * @param {number} [params.limit] - Max rows to scan (server may clamp)
-       * @param {string} [params.select] - Comma-separated projections (handle,provider,profileUrl,traits.<key>)
        * @returns {Promise<Object>} API response ({ success, data })
        */
       async gateCheck(params = {}) {
@@ -1861,7 +1924,6 @@ ${bytes.length}`;
         setIfPresent("sinceDays", params.sinceDays);
         setIfPresent("since", params.since);
         setIfPresent("limit", params.limit);
-        setCsvIfPresent("select", params.select);
         setIfPresent("referenceType", params.referenceType);
         setIfPresent("referenceId", params.referenceId);
         setIfPresent("tag", params.tag);
@@ -1875,7 +1937,6 @@ ${bytes.length}`;
         setIfPresent("domain", params.domain);
         setIfPresent("minBalance", params.minBalance);
         setIfPresent("provider", params.provider);
-        setIfPresent("handle", params.handle);
         setIfPresent("ownerAddress", params.ownerAddress);
         setIfPresent("riskLevel", params.riskLevel);
         setBoolIfPresent("sanctioned", params.sanctioned);
@@ -1883,8 +1944,6 @@ ${bytes.length}`;
         setIfPresent("primaryWalletAddress", params.primaryWalletAddress);
         setIfPresent("secondaryWalletAddress", params.secondaryWalletAddress);
         setIfPresent("verificationMethod", params.verificationMethod);
-        setIfPresent("traitPath", params.traitPath);
-        setIfPresent("traitGte", params.traitGte);
         const response = await this._makeRequest("GET", `/api/v1/proofs/gate/check?${qs.toString()}`);
         if (!response.success) {
           throw new ApiError(`Gate check failed: ${response.error?.message || "Unknown error"}`, response.error);

package/cjs/utils.cjs

@@ -75,6 +75,49 @@ var SDKError = class _SDKError extends Error {
     };
   }
 };
+var ApiError = class _ApiError extends SDKError {
+  constructor(message, statusCode = 500, code = "API_ERROR", response = null) {
+    super(message, code);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+    this.response = response;
+    this.isClientError = statusCode >= 400 && statusCode < 500;
+    this.isServerError = statusCode >= 500;
+    this.isRetryable = this.isServerError || statusCode === 429;
+  }
+  static fromResponse(response, responseData) {
+    const statusCode = response.status;
+    const message = responseData?.error?.message || responseData?.message || `API request failed with status ${statusCode}`;
+    const code = responseData?.error?.code || "API_ERROR";
+    return new _ApiError(message, statusCode, code, responseData);
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      statusCode: this.statusCode,
+      isClientError: this.isClientError,
+      isServerError: this.isServerError,
+      isRetryable: this.isRetryable
+    };
+  }
+};
+var ValidationError = class extends SDKError {
+  constructor(message, field = null, value = null) {
+    super(message, "VALIDATION_ERROR");
+    this.name = "ValidationError";
+    this.field = field;
+    this.value = value;
+    this.isRetryable = false;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      field: this.field,
+      value: this.value,
+      isRetryable: this.isRetryable
+    };
+  }
+};
 
 // utils.js
 function deterministicStringify(obj) {
@@ -108,7 +151,7 @@ function constructVerificationMessage({ walletAddress, signedTimestamp, data, ve
   }
   const chainContext = typeof chain === "string" && chain.length > 0 ? chain : chainId;
   if (!chainContext) {
-    throw new SDKError("chainId is required (or provide chain for preview mode)", "INVALID_CHAIN_CONTEXT");
+    throw new SDKError("chainId is required (or provide chain for universal mode)", "INVALID_CHAIN_CONTEXT");
   }
   if (chainContext === chainId && typeof chainId !== "number") {
     throw new SDKError("chainId must be a number when provided", "INVALID_CHAIN_ID");
@@ -384,10 +427,24 @@ var StatusPoller = class {
           }
           setTimeout(pollAttempt, this.currentInterval);
         } catch (error) {
-          reject(new SDKError(
-            `Polling failed: ${error.message}`,
-            "POLLING_ERROR"
-          ));
+          if (error instanceof ValidationError) {
+            reject(error);
+            return;
+          }
+          if (error instanceof ApiError && error.statusCode === 429 || error?.isRetryable === true) {
+            if (this.options.exponentialBackoff) {
+              const next = Math.min(this.currentInterval * 2, this.options.maxInterval);
+              const jitter = next * (0.5 + Math.random() * 0.5);
+              this.currentInterval = Math.max(250, Math.floor(jitter));
+            }
+            if (this.attempt >= this.options.maxAttempts) {
+              reject(new SDKError("Verification polling timeout", "POLLING_TIMEOUT"));
+              return;
+            }
+            setTimeout(pollAttempt, this.currentInterval);
+            return;
+          }
+          reject(new SDKError(`Polling failed: ${error.message}`, "POLLING_ERROR"));
         }
       };
       pollAttempt();
@@ -464,10 +521,14 @@ function validateVerifierPayload(verifierId, data) {
       result.warnings.push("ownerAddress omitted (most deployments default to the signed walletAddress)");
     }
   } else if (id === "ownership-basic") {
-    ["content"].forEach((key) => {
-      if (!(key in data))
-        result.missing.push(key);
-    });
+    if (!("owner" in data))
+      result.missing.push("owner");
+    const hasContent = typeof data.content === "string" && data.content.length > 0;
+    const hasContentHash = typeof data.contentHash === "string" && data.contentHash.length > 0;
+    const hasRefId = typeof data.reference?.id === "string" && data.reference.id.length > 0;
+    if (!hasContent && !hasContentHash && !hasRefId) {
+      result.missing.push("content (or contentHash or reference.id)");
+    }
   }
   if (result.missing.length > 0) {
     result.valid = false;