feat: initialize agent-fetch with L402 client and token cache

Author: andrerfneves

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[\*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint --if-present
+
+      - name: Test
+        run: npm test --if-present
+
+      - name: Build
+        run: npm run build --if-present

.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
+        run: npx semantic-release

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+coverage/
+*.log
+.DS_Store

.npmrc

@@ -0,0 +1,2 @@
+engine-strict=true
+package-lock=true

.nvmrc

@@ -0,0 +1 @@
+22

.releaserc.cjs

@@ -0,0 +1,32 @@
+const isDryRun = process.env.SEMANTIC_RELEASE_DRY_RUN === "true";
+const repositoryUrl = process.env.SEMANTIC_RELEASE_REPOSITORY_URL || (process.env.GITHUB_REPOSITORY
+  ? `${process.env.GITHUB_SERVER_URL || "https://github.com"}/${process.env.GITHUB_REPOSITORY}.git`
+  : `file://${process.cwd()}`);
+
+const plugins = [
+  ["@semantic-release/commit-analyzer", { preset: "conventionalcommits" }],
+  ["@semantic-release/release-notes-generator", { preset: "conventionalcommits" }],
+  "@semantic-release/changelog",
+];
+
+if (!isDryRun) {
+  plugins.push(
+    ["@semantic-release/npm", { npmPublish: true, tarballDir: "dist-release" }],
+    "@semantic-release/github",
+    [
+      "@semantic-release/git",
+      {
+        assets: ["CHANGELOG.md", "package.json", "package-lock.json"],
+        message:
+          "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}",
+      },
+    ],
+  );
+}
+
+module.exports = {
+  branches: ["main"],
+  repositoryUrl,
+  tagFormat: "${version}",
+  plugins,
+};

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZBD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,113 @@
+# @zbdpay/agent-fetch
+
+L402-aware fetch client for paid HTTP resources.
+
+This package handles the full payment challenge flow:
+- parse `402 Payment Required` responses
+- support both `L402` and `LSAT` schemes
+- pay using caller-provided hooks
+- retry with `Authorization` proof
+- cache proofs locally to avoid duplicate payments
+
+## Requirements
+
+- Node.js `>=22`
+- npm
+
+## Install
+
+```bash
+npm install @zbdpay/agent-fetch
+```
+
+## Quick Start
+
+```ts
+import { agentFetch, FileTokenCache } from "@zbdpay/agent-fetch";
+
+const tokenCache = new FileTokenCache(`${process.env.HOME}/.zbd-wallet/token-cache.json`);
+
+const response = await agentFetch("https://example.com/protected", {
+  tokenCache,
+  maxPaymentSats: 100,
+  pay: async (challenge) => {
+    // Pay challenge.invoice with your wallet implementation.
+    // Return preimage, plus optional paymentId/amountPaidSats.
+    return {
+      preimage: "<payment-preimage>",
+      paymentId: "<payment-id>",
+      amountPaidSats: challenge.amountSats,
+    };
+  },
+  waitForPayment: async (paymentId) => {
+    // Optional poller for async settlement.
+    // Return pending/completed/failed.
+    return {
+      status: "completed",
+      paymentId,
+      preimage: "<payment-preimage>",
+      amountPaidSats: 21,
+    };
+  },
+});
+
+const body = await response.json();
+console.log(response.status, body);
+```
+
+## Behavior
+
+- If cached auth exists and is not expired, request is sent immediately with proof.
+- If response is not `402`, original response is returned untouched.
+- If response is `402`, challenge is parsed from `WWW-Authenticate` and/or JSON body.
+- If payment succeeds, proof is generated as `<SCHEME> <macaroon-or-token>:<preimage>` and request is retried.
+- If `maxPaymentSats` is set and challenge exceeds it, call fails before payment.
+- If async settlement is used and times out, call fails with a timeout error.
+
+## Public API
+
+Exports from `src/index.ts`:
+
+- `agentFetch`
+- `requestChallenge`
+- `payChallenge`
+- `fetchWithProof`
+- `FileTokenCache`
+- types: `AgentFetchOptions`, `PaymentChallenge`, `PaidChallenge`, `PaymentSettlement`, `TokenCache`, `TokenRecord`, `ChallengeScheme`
+
+## Options (`AgentFetchOptions`)
+
+- `pay` (required): function to pay a parsed challenge
+- `waitForPayment` (optional): poller for async settlement
+- `tokenCache` (optional): token cache backend
+- `requestInit` (optional): forwarded fetch options
+- `fetchImpl` (optional): custom fetch implementation
+- `maxPaymentSats` (optional): payment guardrail
+- `paymentTimeoutMs` (optional, default `30000`)
+- `paymentPollIntervalMs` (optional, default `300`)
+- `now`, `sleep` (optional testability hooks)
+
+## Token Cache
+
+`FileTokenCache` stores per-URL tokens as JSON and writes atomically.
+
+- no `expiresAt`: token is reused until overwritten/deleted
+- with `expiresAt`: expired token is evicted on read
+
+Default cache location is chosen by the caller. In this suite, `agent-wallet` uses `~/.zbd-wallet/token-cache.json`.
+
+## Scripts
+
+```bash
+npm run build
+npm run test
+npm run lint
+npm run typecheck
+npm run smoke:imports
+npm run release:dry-run
+```
+
+## Related Packages
+
+- `@zbdpay/agent-wallet` uses this package for `zbdw fetch`
+- `@zbdpay/agent-pay` provides middleware that emits L402 challenges this client can consume