{"_id":"@1xmint/soma-check","name":"@1xmint/soma-check","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@1xmint/soma-check","version":"0.1.0","description":"Drop-in fetch wrapper for Soma Check / x402 ETag — automatic 304 caching skips payment when data is unchanged","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"node build.mjs","prepublishOnly":"npm run build"},"keywords":["soma","soma-check","x402","x402-etag","clawnet","conditional-payment","etag","http-caching","agents","ai"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/1xmint/claw-net.git","directory":"packages/soma-check"},"homepage":"https://claw-net.org","engines":{"node":">=18"},"devDependencies":{"esbuild":"^0.20.0","typescript":"^5.4.0"},"gitHead":"6061fdb58017d58f000a51c928e75725c990aed7","_id":"@1xmint/soma-check@0.1.0","bugs":{"url":"https://github.com/1xmint/claw-net/issues"},"_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-9FhDEpVoXi9WUKxCRZdqpcOkMMzIhq/gdaCSSsF9aZWewucC4dtUwMoq/tWlXgJ5tr9SozvvZDM/ZojHLC1RNg==","shasum":"fcd03d060b17e973a9e91e1dae97f8acda047c20","tarball":"https://registry.npmjs.org/@1xmint/soma-check/-/soma-check-0.1.0.tgz","fileCount":7,"unpackedSize":49704,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC3HTQ93XdjYdtS3l7daXbc4cc3w6IH/j+sXbeyTHPhhAiBqKTTDn6QTqvT7hE82VGTlc7v0sFQEyZ3UKjhKaeMlVg=="}]},"_npmUser":{"name":"1xmint","email":"jfair1028@gmail.com"},"directories":{},"maintainers":[{"name":"1xmint","email":"jfair1028@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/soma-check_0.1.0_1775441634929_0.2913742241413"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-06T02:13:54.827Z","0.1.0":"2026-04-06T02:13:55.117Z","modified":"2026-04-06T02:13:55.326Z"},"maintainers":[{"name":"1xmint","email":"jfair1028@gmail.com"}],"description":"Drop-in fetch wrapper for Soma Check / x402 ETag — automatic 304 caching skips payment when data is unchanged","homepage":"https://claw-net.org","keywords":["soma","soma-check","x402","x402-etag","clawnet","conditional-payment","etag","http-caching","agents","ai"],"repository":{"type":"git","url":"git+https://github.com/1xmint/claw-net.git","directory":"packages/soma-check"},"bugs":{"url":"https://github.com/1xmint/claw-net/issues"},"license":"MIT","readme":"# @clawnet/soma-check\n\nDrop-in `fetch` wrapper for **Soma Check** (aka x402 ETag) — automatic HTTP conditional requests that skip payment when data hasn't changed.\n\n## Why\n\nAgents polling x402-gated APIs pay for every byte — even when the data is identical to last call. Soma Check / x402 ETag lets origins return `304 Not Modified` instead of re-billing. This SDK makes that free for agents: just use `client.fetch` and it handles `ETag` + `If-None-Match` automatically.\n\n- **Zero config.** Works with any origin that emits standard HTTP `ETag` headers.\n- **Zero deps.** Native `fetch` only.\n- **Works everywhere.** Node 18+, Deno, Bun, browsers, Cloudflare Workers.\n\n## Install\n\n```bash\nnpm install @clawnet/soma-check\n```\n\n## Usage\n\n```typescript\nimport { SomaCheckClient } from '@clawnet/soma-check';\n\nconst client = new SomaCheckClient();\n\n// First call: full fetch, stores ETag\nconst r1 = await client.fetch('https://api.claw-net.org/v1/soma/demo/btc-price');\nconsole.log(r1.somaCached); // false\n\n// Second call: sends If-None-Match, gets 304, serves from cache — no payment\nconst r2 = await client.fetch('https://api.claw-net.org/v1/soma/demo/btc-price');\nconsole.log(r2.somaCached); // true\nconsole.log(await r2.json()); // same data, zero network cost\n\nconsole.log(client.stats());\n// { hits: 1, misses: 1, hitRate: 0.5, bytesSaved: 812, cacheEntries: 1, ... }\n```\n\nOne-liner with the default singleton:\n\n```typescript\nimport { somaFetch } from '@clawnet/soma-check';\n\nconst res = await somaFetch('https://api.claw-net.org/v1/soma/demo/btc-price');\n```\n\n## Options\n\n```typescript\nnew SomaCheckClient({\n  maxEntries: 1000,           // LRU cap (default 1000)\n  maxAgeMs: 24 * 3600 * 1000, // evict after 24h (default)\n  sendSomaHashHeader: true,   // also send legacy If-Soma-Hash alias (default true)\n  cacheKey: (url, init) => `${init.method} ${url}`, // custom key derivation\n  fetchImpl: customFetch,     // bring your own fetch\n});\n```\n\n## Persisting cache across restarts\n\n```typescript\n// Save\nconst snapshot = client.dump();\nfs.writeFileSync('cache.json', JSON.stringify(snapshot));\n\n// Restore\nclient.restore(JSON.parse(fs.readFileSync('cache.json', 'utf8')));\n```\n\n## How it works\n\n1. First request to a URL → you get the full response, SDK stores `ETag` + body.\n2. Next request → SDK adds `If-None-Match: <etag>` header.\n3. If origin data is unchanged → origin returns `304 Not Modified` (empty body, no billing on Soma-aware providers).\n4. SDK serves the cached body. Your code sees a normal `Response`.\n\nOn Soma Check origins, the 304 path skips payment settlement entirely. Provider still gets a smaller fee for the freshness guarantee (90/10 split on cache hits — see [Soma Check billing](https://claw-net.org/soma-check.html)).\n\n## Compat\n\n- Works with **any** HTTP server that emits standard ETag headers (RFC 9111) — not Soma-specific.\n- Soma-aware origins additionally honor `X-Soma-Hash` / `If-Soma-Hash` aliases.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-0c658332fcce811b78eef780adace53e"}