@readfetch/client 0.1.1 → 0.1.12

package/README.md

@@ -1,8 +1,8 @@
 # @readfetch/client
 
-x402 REST client for [readfetch.com](https://readfetch.com): **`probe`** (free) and **`readfetchText`** (paid `/v1/text`).
+x402 REST client for [readfetch.com](https://readfetch.com): every **published** catalog route plus **`/v1/feedback`** and **`/v1/claims`**.
 
-Source of truth in the private service checkout: `tools/client-js`. Published to GitHub with `./scripts/publish-client-js.sh`.
+Source: `tools/client-js`. GitHub: `./scripts/publish-client-js.sh`. Registry: `npm publish --access public` from this directory.
 
 ## Install
 
@@ -13,21 +13,84 @@ npm install @readfetch/client
 ## Use
 
 ```bash
-export EVM_PRIVATE_KEY=0x…   # not needed for probe()
+export EVM_PRIVATE_KEY=0x…   # not needed for probe / feedback / crawl_status
 ```
 
 ```javascript
-import { probe, probeWithMeta, readfetchText, submitFeedback } from "@readfetch/client";
+import {
+  call,
+  probeWithMeta,
+  readfetchText,
+  readfetchMap,
+  readfetchCrawlStatus,
+  submitFeedback,
+  submitClaim,
+} from "@readfetch/client";
 
 const { data: check, requestId } = await probeWithMeta("https://example.com");
-if (requestId) console.error(`X-Request-Id: ${requestId}`);
 if (!check.challenge) {
-  const page = await readfetchText("https://example.com");
+  await readfetchText("https://example.com");
+  // or: await call("text", { url: "https://example.com" });
 }
-// Integrator issues (not billing):
-// await submitFeedback(requestId, "integration", "402 confused my parser");
+
+await readfetchMap({ url: "https://example.com", max_urls: 20 });
+const job = await readfetchCrawl({ url: "https://example.com", max_pages: 3 });
+await readfetchCrawlStatus(job.id);
+
+await submitFeedback(requestId, "integration", "402 confused my parser");
+// await submitClaim({ receipt, reason, address, signature });
+```
+
+### Named helpers (same as `call(name, body)`)
+
+| Name | Function | Paid |
+|------|----------|------|
+| `text` | `readfetchText(url \| body)` | yes |
+| `map` | `readfetchMap(body)` | yes |
+| `scrape` | `readfetchScrape(body)` | yes |
+| `residential` | `readfetchResidential(body)` | yes |
+| `fetch` | `readfetchFetch(body)` | yes |
+| `batch` | `readfetchBatch(body)` | yes |
+| `pdf` | `readfetchPdf(body)` | yes |
+| `section` | `readfetchSection(body)` | yes |
+| `diff` | `readfetchDiff(body)` | yes |
+| `screenshot` | `readfetchScreenshot(body)` | yes |
+| `search` | `readfetchSearch(body)` | yes |
+| `crawl` | `readfetchCrawl(body)` | yes |
+| `crawl_status` | `readfetchCrawlStatus(jobId)` | no (GET) |
+| `probe` | `probe(url)` / `probeWithMeta(url)` | no |
+
+Integrator: `submitFeedback`, `submitClaim`. Generic: `call("search", { query: "…" })`, `callWithMeta` for `X-Request-Id` and settlement headers.
+
+## Payment (x402)
+
+Paid catalog routes use **`@x402/fetch`**: first request may return **402** with `PAYMENT-REQUIRED`; the client signs (EIP-3009) and retries automatically.
+
+```javascript
+import {
+  paymentConfig,
+  paidFetch,
+  quote,
+  callWithMeta,
+} from "@readfetch/client";
+
+// No network — is the wallet configured?
+console.log(paymentConfig()); // { baseUrl, network, maxPaymentUsd, buyerAddress, signingReady }
+
+// Quote without a key (402 body + PAYMENT-REQUIRED header)
+const q = await quote("text", { url: "https://example.com" });
+
+// Paid call — signing + retry handled for you
+const { data, requestId, payment } = await callWithMeta("text", { url: "https://example.com" });
+// payment.receipt, payment.paymentResponse, payment.creditApplied on 200
+
+// Custom fetch to readfetch URLs (same signer + spend cap)
+const http = paidFetch();
+await http("https://readfetch.com/v1/map", { method: "POST", body: "…" });
 ```
 
+`pay(name, body)` is an alias for `call()` on paid routes. Free routes (`probe`, `feedback`, `crawl_status`) use plain `fetch`.
+
 ## Environment
 
 | Variable | Default | Purpose |
@@ -37,8 +100,6 @@ if (!check.challenge) {
 | `READFETCH_MAX_PAYMENT_USD` | `1` | Per-payment spend cap |
 | `READFETCH_DEV=1` | off | Allow `localhost` / `127.0.0.1` + Sepolia (`eip155:84532`) |
 
-Framework wrappers (LangChain.js, OpenAI Agents SDK): see [readfetch/readfetch examples](https://github.com/readfetch/readfetch/tree/main/examples).
-
-MCP hosts: use [`@readfetch/mcp-x402-proxy`](https://github.com/readfetch/mcp-x402-proxy) instead — they cannot attach `PAYMENT-SIGNATURE` on `tools/call`.
+Framework examples: [readfetch/readfetch](https://github.com/readfetch/readfetch/tree/main/examples). MCP: [`@readfetch/mcp-x402-proxy@0.1.12`](https://github.com/readfetch/mcp-x402-proxy).
 
-**Feedback:** after a confusing call, `POST /v1/feedback` with the response's `X-Request-Id` (or MCP `readfetch_feedback`). Not for billing — use claims. See [readfetch.com/docs#feedback](https://readfetch.com/docs#feedback).
+Feedback vs claims: [readfetch.com/docs#feedback](https://readfetch.com/docs#feedback).

package/config.mjs

@@ -3,7 +3,26 @@
  */
 
 const PRODUCTION_HOSTS = new Set(["readfetch.com", "www.readfetch.com"]);
-const DEV_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+const DEV_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+
+/** @param {URL} url */
+function assertNoUserinfo(url) {
+  if (url.username || url.password) {
+    throw new Error("READFETCH_BASE_URL must not include userinfo");
+  }
+}
+
+/** @param {URL} url */
+function formatOrigin(url) {
+  if (!url.hostname) {
+    throw new Error("READFETCH_BASE_URL must include a hostname");
+  }
+  let origin = `${url.protocol}//${url.hostname}`;
+  if (url.port) {
+    origin += `:${url.port}`;
+  }
+  return origin;
+}
 
 export function normalizeHostname(hostname) {
   return hostname.replace(/\.+$/, "").toLowerCase();
@@ -26,20 +45,43 @@ export function readfetchBase(env = process.env) {
   } catch {
     throw new Error("READFETCH_BASE_URL is not a valid URL");
   }
+  assertNoUserinfo(url);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("READFETCH_BASE_URL must use http or https");
+  }
   if (isProductionHost(url.hostname)) {
     if (url.protocol !== "https:") {
       throw new Error("READFETCH_BASE_URL must use https for readfetch.com");
     }
-    return raw;
+    if (url.pathname !== "" && url.pathname !== "/") {
+      throw new Error("READFETCH_BASE_URL must not include a path on readfetch.com");
+    }
+    if (url.port && url.port !== "443") {
+      throw new Error("READFETCH_BASE_URL must use default https port for readfetch.com");
+    }
+    return formatOrigin(url);
   }
   if (env.READFETCH_DEV === "1" && isDevHost(url.hostname)) {
-    return raw;
+    return formatOrigin(url);
   }
   throw new Error(
     "READFETCH_BASE_URL must be https://readfetch.com (or localhost with READFETCH_DEV=1)",
   );
 }
 
+/** @param {string} path — must start with `/` (from `endpointPath`) */
+export function readfetchUrl(env = process.env, path) {
+  const base = readfetchBase(env);
+  if (!path.startsWith("/")) {
+    throw new Error("endpoint path must start with /");
+  }
+  const url = `${base}${path}`;
+  if (new URL(url).origin !== new URL(base).origin) {
+    throw new Error("request URL origin must match READFETCH_BASE_URL");
+  }
+  return url;
+}
+
 /** @param {NodeJS.ProcessEnv} [env] */
 export function parseMaxPaymentUsd(env = process.env) {
   const raw = env.READFETCH_MAX_PAYMENT_USD?.trim() || "1";
@@ -77,5 +119,5 @@ export function loadAccountFromEnv(env = process.env) {
   if (!/^0x[0-9a-fA-F]{64}$/.test(hex)) {
     throw new Error("EVM_PRIVATE_KEY must be 64 hex bytes (optional 0x prefix)");
   }
-  return hex;
+  return hex.toLowerCase();
 }

package/endpoints.mjs

@@ -0,0 +1,73 @@
+/** Published routes — keep in sync with `catalog.json` (published + integrator). */
+
+/** @typedef {{ name: string, method: string, path: string, free: boolean, accept?: number[] }} EndpointSpec */
+
+/** Max length for `{id}` and other path param substitutions. */
+export const MAX_PATH_PARAM_LEN = 512;
+
+/** @type {EndpointSpec[]} */
+export const CATALOG_ENDPOINTS = [
+  { name: "text", method: "POST", path: "/v1/text", free: false },
+  { name: "map", method: "POST", path: "/v1/map", free: false },
+  { name: "scrape", method: "POST", path: "/v1/scrape", free: false },
+  { name: "residential", method: "POST", path: "/v1/scrape/residential", free: false },
+  { name: "fetch", method: "POST", path: "/v1/fetch", free: false },
+  { name: "batch", method: "POST", path: "/v1/batch", free: false },
+  { name: "pdf", method: "POST", path: "/v1/pdf", free: false },
+  { name: "section", method: "POST", path: "/v1/section", free: false },
+  { name: "diff", method: "POST", path: "/v1/diff", free: false },
+  { name: "screenshot", method: "POST", path: "/v1/screenshot", free: false },
+  { name: "search", method: "POST", path: "/v1/search", free: false },
+  { name: "crawl", method: "POST", path: "/v1/crawl", free: false },
+  { name: "crawl_status", method: "GET", path: "/v1/crawl/{id}", free: true },
+  { name: "probe", method: "POST", path: "/v1/probe", free: true },
+];
+
+/** @type {EndpointSpec[]} */
+export const INTEGRATOR_ENDPOINTS = [
+  { name: "feedback", method: "POST", path: "/v1/feedback", free: true, accept: [202] },
+  { name: "claims", method: "POST", path: "/v1/claims", free: true },
+];
+
+/** @type {Map<string, EndpointSpec>} */
+export const BY_NAME = new Map(
+  [...CATALOG_ENDPOINTS, ...INTEGRATOR_ENDPOINTS].map((spec) => [spec.name, spec]),
+);
+
+/**
+ * @param {string} name
+ * @param {Record<string, string>} [pathParams]
+ */
+export function endpointPath(name, pathParams = {}) {
+  const spec = BY_NAME.get(name);
+  if (!spec) {
+    throw new Error(`unknown endpoint \`${name}\`; known: ${[...BY_NAME.keys()].join(", ")}`);
+  }
+  let path = spec.path.replace(/\{(\w+)\}/g, (_, key) => {
+    const value = pathParams[key];
+    if (value === undefined || value === null) {
+      throw new Error(`\`${name}\` requires pathParams.${key}`);
+    }
+    const trimmed = String(value).trim();
+    if (!trimmed) {
+      throw new Error(`\`${name}\` requires pathParams.${key}`);
+    }
+    if (trimmed.length > MAX_PATH_PARAM_LEN) {
+      throw new Error(`\`${name}\` pathParams.${key} exceeds ${MAX_PATH_PARAM_LEN} characters`);
+    }
+    return encodeURIComponent(trimmed);
+  });
+  if (/\{/.test(path)) {
+    throw new Error(`\`${name}\` has unresolved path template`);
+  }
+  return path;
+}
+
+/** camelCase export: readfetchText, readfetchCrawlStatus, … */
+export function exportName(name) {
+  const parts = name.split("_");
+  return (
+    "readfetch" +
+    parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("")
+  );
+}

package/index.mjs

@@ -1,12 +1,23 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
 import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
 import { ExactEvmScheme } from "@x402/evm";
 import { privateKeyToAccount } from "viem/accounts";
+import {
+  BY_NAME,
+  CATALOG_ENDPOINTS,
+  INTEGRATOR_ENDPOINTS,
+  endpointPath,
+  exportName,
+} from "./endpoints.mjs";
 import {
   loadAccountFromEnv,
   parseMaxPaymentUsd,
   readfetchBase,
+  readfetchUrl,
   x402Network,
 } from "./config.mjs";
+import { buyerAddress, paymentConfig, paymentFromResponse } from "./payment.mjs";
 
 export {
   isDevHost,
@@ -14,32 +25,209 @@ export {
   loadAccountFromEnv,
   parseMaxPaymentUsd,
   readfetchBase,
+  readfetchUrl,
   x402Network,
 } from "./config.mjs";
+export { buyerAddress, paymentConfig, paymentFromResponse } from "./payment.mjs";
+export {
+  BY_NAME,
+  CATALOG_ENDPOINTS,
+  INTEGRATOR_ENDPOINTS,
+  endpointPath,
+  exportName,
+} from "./endpoints.mjs";
 
 const TIMEOUT_MS = 120_000;
 
 const FEEDBACK_CATEGORIES = new Set(["integration", "docs", "site", "other"]);
+const MAX_FEEDBACK_REQUEST_ID_LEN = 256;
+
+/** Max JSON body size accepted from readfetch (16 MiB). */
+export const MAX_JSON_RESPONSE_BYTES = 16 * 1024 * 1024;
+
+/** @param {string} text @param {number} status */
+function parseJsonBody(text, status) {
+  if (!text) {
+    return {};
+  }
+  if (Buffer.byteLength(text, "utf8") > MAX_JSON_RESPONSE_BYTES) {
+    throw new Error(`${status}: response body exceeds ${MAX_JSON_RESPONSE_BYTES} bytes`);
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("expected JSON object");
+    }
+    return parsed;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${status}: ${text.slice(0, 400)} (invalid JSON: ${detail})`);
+  }
+}
+
+/** @param {string} privateKey @param {NodeJS.ProcessEnv} env */
+function paidFetchCacheKey(privateKey, env) {
+  const fingerprint = createHash("sha256").update(privateKey, "utf8").digest("hex");
+  return `${fingerprint}:${x402Network(env)}:${parseMaxPaymentUsd(env)}`;
+}
 
-let fetchWithPayment;
+/** @type {Map<string, ReturnType<typeof wrapFetchWithPaymentFromConfig>>} */
+const paidFetchByKey = new Map();
 
 /** @param {NodeJS.ProcessEnv} [env] */
 export function paidFetch(env = process.env) {
-  if (!fetchWithPayment) {
-    const account = privateKeyToAccount(loadAccountFromEnv(env));
-    fetchWithPayment = wrapFetchWithPaymentFromConfig(globalThis.fetch, {
+  let privateKey;
+  try {
+    privateKey = loadAccountFromEnv(env);
+  } catch (error) {
+    throw new Error(
+      `Paid calls need EVM_PRIVATE_KEY (Base USDC): ${error instanceof Error ? error.message : error}`,
+    );
+  }
+  const cacheKey = paidFetchCacheKey(privateKey, env);
+  let wrapped = paidFetchByKey.get(cacheKey);
+  if (!wrapped) {
+    const account = privateKeyToAccount(privateKey);
+    wrapped = wrapFetchWithPaymentFromConfig(globalThis.fetch, {
       schemes: [{ network: x402Network(env), client: new ExactEvmScheme(account) }],
       spendControls: { maxAmountPerPayment: `$${parseMaxPaymentUsd(env)}` },
     });
+    paidFetchByKey.set(cacheKey, wrapped);
   }
-  return fetchWithPayment;
+  return wrapped;
 }
 
+/** Alias — `@x402/fetch` wrapper that signs EIP-3009 and retries on 402. */
+export const createPaidFetch = paidFetch;
+
 /** `x-request-id` from any readfetch JSON response (for `submitFeedback`). */
 export function requestIdFromResponse(response) {
   return response.headers.get("x-request-id") ?? response.headers.get("X-Request-Id");
 }
 
+/** @param {string} text @param {number} status */
+function assertTextSize(text, status) {
+  if (Buffer.byteLength(text, "utf8") > MAX_JSON_RESPONSE_BYTES) {
+    throw new Error(`${status}: response body exceeds ${MAX_JSON_RESPONSE_BYTES} bytes`);
+  }
+}
+
+/** @param {Response} response */
+function assertResponseSize(response) {
+  const cl = response.headers.get("content-length");
+  if (cl === null || cl === "") {
+    return;
+  }
+  const n = Number(cl);
+  if (!Number.isFinite(n) || n < 0) {
+    return;
+  }
+  if (n > MAX_JSON_RESPONSE_BYTES) {
+    throw new Error(
+      `${response.status}: content-length ${n} exceeds ${MAX_JSON_RESPONSE_BYTES} bytes`,
+    );
+  }
+}
+
+/**
+ * @param {string} name — e.g. `text`, `map`, `probe`, `crawl_status`
+ * @param {object | null | undefined} body — JSON body (omit for GET `crawl_status`)
+ * @param {{ pathParams?: Record<string, string>, env?: NodeJS.ProcessEnv }} [options]
+ */
+export async function call(name, body, options = {}) {
+  const { data } = await callWithMeta(name, body, options);
+  return data;
+}
+
+/**
+ * @param {string} name
+ * @param {object | null | undefined} body
+ * @param {{ pathParams?: Record<string, string>, env?: NodeJS.ProcessEnv }} [options]
+ */
+export async function callWithMeta(name, body, options = {}) {
+  const spec = BY_NAME.get(name);
+  if (!spec) {
+    throw new Error(`unknown endpoint \`${name}\``);
+  }
+  const env = options.env ?? process.env;
+  const path = endpointPath(name, options.pathParams ?? {});
+  const url = readfetchUrl(env, path);
+  const method = spec.method;
+  /** @type {RequestInit} */
+  const init = { method, signal: AbortSignal.timeout(TIMEOUT_MS), headers: {} };
+  if (method !== "GET") {
+    init.headers["content-type"] = "application/json";
+    init.body = JSON.stringify(body ?? {});
+  }
+  const http = spec.free ? globalThis.fetch : paidFetch(env);
+  const response = await http(url, init);
+  assertResponseSize(response);
+  const text = await response.text();
+  assertTextSize(text, response.status);
+  const okStatuses = spec.accept?.length ? spec.accept : [200];
+  if (!okStatuses.includes(response.status)) {
+    throw new Error(`${response.status}: ${text.slice(0, 400)}`);
+  }
+  const data = parseJsonBody(text, response.status);
+  return {
+    data,
+    requestId: requestIdFromResponse(response),
+    payment: paymentFromResponse(response),
+    response,
+  };
+}
+
+/**
+ * Unpaid request — returns the 402 quote (`accepts`, `price_usd`, …). No wallet required.
+ * @param {string} name — paid catalog route only
+ */
+export async function quote(name, body, options = {}) {
+  const spec = BY_NAME.get(name);
+  if (!spec) {
+    throw new Error(`unknown endpoint \`${name}\``);
+  }
+  if (spec.free) {
+    throw new Error(`\`${name}\` is free — use call() instead of quote()`);
+  }
+  const env = options.env ?? process.env;
+  const path = endpointPath(name, options.pathParams ?? {});
+  const url = readfetchUrl(env, path);
+  const method = spec.method;
+  /** @type {RequestInit} */
+  const init = {
+    method,
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body ?? {}),
+  };
+  if (method === "GET") {
+    delete init.body;
+    delete init.headers["content-type"];
+  }
+  const response = await fetch(url, init);
+  assertResponseSize(response);
+  const text = await response.text();
+  assertTextSize(text, response.status);
+  if (response.status !== 402) {
+    throw new Error(`expected 402 quote, got ${response.status}: ${text.slice(0, 400)}`);
+  }
+  return {
+    status: 402,
+    body: parseJsonBody(text, 402),
+    paymentRequired:
+      response.headers.get("payment-required") ??
+      response.headers.get("PAYMENT-REQUIRED"),
+    requestId: requestIdFromResponse(response),
+  };
+}
+
+/**
+ * Paid route: sign via `@x402/fetch` and return JSON. Same as `call()` on paid endpoints.
+ */
+export async function pay(name, body, options = {}) {
+  return call(name, body, options);
+}
+
 /** Free route — call before paying for `/v1/text`. Returns body only. */
 export async function probe(url, env = process.env) {
   const { data } = await probeWithMeta(url, env);
@@ -48,17 +236,7 @@ export async function probe(url, env = process.env) {
 
 /** Like `probe`, but includes `requestId` from response headers. */
 export async function probeWithMeta(url, env = process.env) {
-  const response = await fetch(`${readfetchBase(env)}/v1/probe`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ url }),
-    signal: AbortSignal.timeout(TIMEOUT_MS),
-  });
-  if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`${response.status}: ${text.slice(0, 400)}`);
-  }
-  return { data: await response.json(), requestId: requestIdFromResponse(response) };
+  return callWithMeta("probe", { url }, { env });
 }
 
 /** POST /v1/feedback — free; bind with `requestId` from a prior call's `X-Request-Id`. */
@@ -67,38 +245,69 @@ export async function submitFeedback(requestId, category, message, env = process
   const cat = String(category ?? "").trim();
   const msg = String(message ?? "").trim();
   if (!id) throw new Error("request_id is required");
+  if (id.length > MAX_FEEDBACK_REQUEST_ID_LEN) {
+    throw new Error(`request_id exceeds ${MAX_FEEDBACK_REQUEST_ID_LEN} characters`);
+  }
   if (!FEEDBACK_CATEGORIES.has(cat)) {
     throw new Error("category must be integration, docs, site, or other");
   }
   if (!msg || msg.length > 500) {
     throw new Error("message is required (max 500 characters)");
   }
-  const response = await fetch(`${readfetchBase(env)}/v1/feedback`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ request_id: id, category: cat, message: msg }),
-    signal: AbortSignal.timeout(TIMEOUT_MS),
-  });
-  const text = await response.text();
-  if (response.status !== 202) {
-    throw new Error(`${response.status}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text);
+  return call(
+    "feedback",
+    { request_id: id, category: cat, message: msg },
+    { env },
+  );
+}
+
+/** POST /v1/claims — paid delivery dispute (receipt + signature). Not integrator feedback. */
+export async function submitClaim(claim, env = process.env) {
+  return call("claims", claim, { env });
 }
 
 /** POST /v1/text — x402 402 handling is automatic. */
 export async function readfetchText(url, env = process.env) {
-  const response = await paidFetch(env)(`${readfetchBase(env)}/v1/text`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ url }),
-    signal: AbortSignal.timeout(TIMEOUT_MS),
-  });
-  if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`${response.status}: ${text.slice(0, 400)}`);
-  }
-  return response.json();
+  const body = typeof url === "string" ? { url } : url;
+  return call("text", body, { env });
+}
+
+export function readfetchMap(body, env = process.env) {
+  return call("map", body, { env });
+}
+export function readfetchScrape(body, env = process.env) {
+  return call("scrape", body, { env });
+}
+export function readfetchResidential(body, env = process.env) {
+  return call("residential", body, { env });
+}
+export function readfetchFetch(body, env = process.env) {
+  return call("fetch", body, { env });
+}
+export function readfetchBatch(body, env = process.env) {
+  return call("batch", body, { env });
+}
+export function readfetchPdf(body, env = process.env) {
+  return call("pdf", body, { env });
+}
+export function readfetchSection(body, env = process.env) {
+  return call("section", body, { env });
+}
+export function readfetchDiff(body, env = process.env) {
+  return call("diff", body, { env });
+}
+export function readfetchScreenshot(body, env = process.env) {
+  return call("screenshot", body, { env });
+}
+export function readfetchSearch(body, env = process.env) {
+  return call("search", body, { env });
+}
+export function readfetchCrawl(body, env = process.env) {
+  return call("crawl", body, { env });
+}
+/** GET /v1/crawl/{id} — poll async crawl (free). */
+export function readfetchCrawlStatus(jobId, env = process.env) {
+  return call("crawl_status", null, { pathParams: { id: jobId }, env });
 }
 
 /** OpenAI Agents SDK — attach `execute` to your host's tool wrapper. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readfetch/client",
-  "version": "0.1.1",
+  "version": "0.1.12",
   "description": "x402 REST client for readfetch.com (probe, text, …)",
   "type": "module",
   "repository": {
@@ -10,15 +10,23 @@
   "exports": {
     ".": "./index.mjs"
   },
-  "files": ["index.mjs", "config.mjs", "README.md"],
+  "files": [
+    "index.mjs",
+    "config.mjs",
+    "endpoints.mjs",
+    "payment.mjs",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
-  "engines": { "node": ">=20" },
+  "engines": {
+    "node": ">=20"
+  },
   "license": "MIT",
   "scripts": {
-    "test": "node test-static.mjs",
-    "prepublishOnly": "node --check index.mjs && node --check config.mjs && node test-static.mjs"
+    "test": "node test-static.mjs && node test-endpoints.mjs && node test-catalog-sync.mjs",
+    "prepublishOnly": "node --check index.mjs && node --check config.mjs && node --check endpoints.mjs && node --check payment.mjs && node test-static.mjs && node test-endpoints.mjs && node test-catalog-sync.mjs"
   },
   "dependencies": {
     "@x402/evm": "2.29.0",

package/payment.mjs

@@ -0,0 +1,53 @@
+/** x402 payment helpers — quotes, receipts, wallet config. */
+
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  loadAccountFromEnv,
+  parseMaxPaymentUsd,
+  readfetchBase,
+  x402Network,
+} from "./config.mjs";
+
+/** Settlement / receipt headers on a paid 200. */
+export function paymentFromResponse(response) {
+  const receipt =
+    response.headers.get("receipt") ?? response.headers.get("RECEIPT");
+  const paymentResponse =
+    response.headers.get("payment-response") ??
+    response.headers.get("PAYMENT-RESPONSE") ??
+    response.headers.get("x-payment-response") ??
+    response.headers.get("X-PAYMENT-RESPONSE");
+  const creditApplied =
+    response.headers.get("x-credit-applied") ??
+    response.headers.get("X-CREDIT-APPLIED");
+  const paymentRequired =
+    response.headers.get("payment-required") ??
+    response.headers.get("PAYMENT-REQUIRED");
+  return {
+    receipt: receipt || null,
+    paymentResponse: paymentResponse || null,
+    paymentRequired: paymentRequired || null,
+    creditApplied: creditApplied || null,
+  };
+}
+
+/** Payer address when `EVM_PRIVATE_KEY` is set. */
+export function buyerAddress(env = process.env) {
+  try {
+    return privateKeyToAccount(loadAccountFromEnv(env)).address;
+  } catch {
+    return null;
+  }
+}
+
+/** Wallet + network + spend cap — no network I/O. */
+export function paymentConfig(env = process.env) {
+  const address = buyerAddress(env);
+  return {
+    baseUrl: readfetchBase(env),
+    network: x402Network(env),
+    maxPaymentUsd: parseMaxPaymentUsd(env),
+    buyerAddress: address,
+    signingReady: address !== null,
+  };
+}