insumer-verify 1.2.1 → 1.3.1

package/README.md

@@ -105,6 +105,41 @@ The attestation response you're verifying looks like this:
 
 No balances. No amounts. Just a signed true/false per condition.
 
+### Handling `rpc_failure` errors
+
+If the API cannot reach one or more data sources (RPC nodes, Helius, XRPL, Covalent) after retries, it returns `ok: false` with error code `rpc_failure` instead of issuing an attestation. **No signature, no JWT, no credits charged.** This is a retryable error — retry the same request after a short delay (2-5 seconds).
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "rpc_failure",
+    "message": "Unable to verify all conditions — data source unavailable after retries",
+    "failedConditions": [
+      { "source": "rpcBalanceOf", "chainId": "43114", "message": "Timeout" }
+    ]
+  },
+  "meta": { "version": "1.0", "timestamp": "..." }
+}
+```
+
+**Important:** `rpc_failure` is NOT a verification failure. It means the API could not check the condition at all. Do not treat it as `pass: false`. Check for `ok: false` with `error.code === "rpc_failure"` and retry:
+
+```typescript
+const res = await fetch("https://api.insumermodel.com/v1/attest", { ... });
+const data = await res.json();
+
+if (!data.ok && data.error?.code === "rpc_failure") {
+  // Retryable — data source temporarily unavailable
+  // Wait 2-5 seconds and retry the same request
+  console.log("RPC failure, retrying...", data.error.failedConditions);
+  return;
+}
+
+// Only verify if we got an actual attestation
+const result = await verifyAttestation(data, { maxAge: 120 });
+```
+
 ### Browser
 
 ```html
@@ -148,7 +183,9 @@ When `jwksUrl` is set, the library fetches the JWKS, matches the key by `kid` fr
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `response` | `unknown` | Full InsumerAPI response (must contain `data.attestation` and `data.sig`) |
+| `response` | `unknown` | Full InsumerAPI response envelope (must contain `data.attestation` and `data.sig`) |
+
+> **Common mistake:** Pass the **full API response** (`await res.json()`), not `response.data` or `response.data.attestation`. The function expects the outer envelope `{ok, data: {attestation, sig, kid}, meta}`. Passing the inner `data` object will throw `"Invalid response: missing data object"`.
 | `options.maxAge` | `number` | Optional max age in seconds for block freshness check |
 | `options.jwksUrl` | `string` | Optional JWKS URL for dynamic key discovery (e.g. `https://insumermodel.com/.well-known/jwks.json`) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insumer-verify",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Client-side verifier for InsumerAPI attestations. ECDSA P-256 signatures, condition hashes, block freshness, expiry. Zero dependencies. Used by DJD Agent Score (Coinbase x402).",
   "type": "module",
   "main": "build/index.js",