@readfetch/client 0.0.0-stage → 0.1.11

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @readfetch/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+x402 REST client for [readfetch.com](https://readfetch.com): every **published** catalog route plus **`/v1/feedback`** and **`/v1/claims`**.
+
+Source: `tools/client-js`. GitHub: `./scripts/publish-client-js.sh`. Registry: `npm publish --access public` from this directory.
+
+## Install
+
+```bash
+npm install @readfetch/client
+```
+
+## Use
+
+```bash
+export EVM_PRIVATE_KEY=0x…   # not needed for probe / feedback / crawl_status
+```
+
+```javascript
+import {
+  call,
+  probeWithMeta,
+  readfetchText,
+  readfetchMap,
+  readfetchCrawlStatus,
+  submitFeedback,
+  submitClaim,
+} from "@readfetch/client";
+
+const { data: check, requestId } = await probeWithMeta("https://example.com");
+if (!check.challenge) {
+  await readfetchText("https://example.com");
+  // or: await call("text", { url: "https://example.com" });
+}
+
+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 |
+|----------|---------|---------|
+| `EVM_PRIVATE_KEY` / `X402_BUYER_KEY` | — | Required before paid calls |
+| `READFETCH_BASE_URL` | `https://readfetch.com` | Production host only unless dev |
+| `READFETCH_MAX_PAYMENT_USD` | `1` | Per-payment spend cap |
+| `READFETCH_DEV=1` | off | Allow `localhost` / `127.0.0.1` + Sepolia (`eip155:84532`) |
+
+Framework examples: [readfetch/readfetch](https://github.com/readfetch/readfetch/tree/main/examples). MCP: [`@readfetch/mcp-x402-proxy`](https://github.com/readfetch/mcp-x402-proxy).
+
+Feedback vs claims: [readfetch.com/docs#feedback](https://readfetch.com/docs#feedback).

package/config.mjs

@@ -0,0 +1,123 @@
+/**
+ * Base URL and env validation for readfetch REST clients.
+ */
+
+const PRODUCTION_HOSTS = new Set(["readfetch.com", "www.readfetch.com"]);
+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();
+}
+
+export function isProductionHost(hostname) {
+  return PRODUCTION_HOSTS.has(normalizeHostname(hostname));
+}
+
+export function isDevHost(hostname) {
+  return DEV_HOSTS.has(normalizeHostname(hostname));
+}
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function readfetchBase(env = process.env) {
+  const raw = (env.READFETCH_BASE_URL || "https://readfetch.com").replace(/\/$/, "");
+  let url;
+  try {
+    url = new URL(raw);
+  } 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");
+    }
+    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 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";
+  if (!/^\d+(\.\d{1,6})?$/.test(raw)) {
+    throw new Error("READFETCH_MAX_PAYMENT_USD must be a decimal amount");
+  }
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0 || n > 100) {
+    throw new Error("READFETCH_MAX_PAYMENT_USD must be between 0 and 100");
+  }
+  return raw;
+}
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function x402Network(env = process.env) {
+  const base = readfetchBase(env);
+  try {
+    const host = new URL(base).hostname;
+    if (env.READFETCH_DEV === "1" && isDevHost(host)) {
+      return "eip155:84532";
+    }
+  } catch {
+    /* readfetchBase already validated */
+  }
+  return "eip155:8453";
+}
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function loadAccountFromEnv(env = process.env) {
+  const raw = env.EVM_PRIVATE_KEY?.trim() || env.X402_BUYER_KEY?.trim();
+  if (!raw) {
+    throw new Error("Set EVM_PRIVATE_KEY (Base wallet with USDC)");
+  }
+  const hex = raw.startsWith("0x") ? raw : `0x${raw}`;
+  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.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

@@ -0,0 +1,325 @@
+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,
+  isProductionHost,
+  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)}`;
+}
+
+/** @type {Map<string, ReturnType<typeof wrapFetchWithPaymentFromConfig>>} */
+const paidFetchByKey = new Map();
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function paidFetch(env = process.env) {
+  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 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);
+  return data;
+}
+
+/** Like `probe`, but includes `requestId` from response headers. */
+export async function probeWithMeta(url, env = process.env) {
+  return callWithMeta("probe", { url }, { env });
+}
+
+/** POST /v1/feedback — free; bind with `requestId` from a prior call's `X-Request-Id`. */
+export async function submitFeedback(requestId, category, message, env = process.env) {
+  const id = String(requestId ?? "").trim();
+  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)");
+  }
+  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 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. */
+export const readfetchTextToolDefinition = {
+  type: "function",
+  name: "readfetch_text",
+  description:
+    "Read a public URL and return main article text as Markdown with metadata (readfetch.com).",
+  parameters: {
+    type: "object",
+    required: ["url"],
+    properties: { url: { type: "string", format: "uri" } },
+  },
+  execute: async ({ url }) => readfetchText(url),
+};

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@readfetch/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.11",
+  "description": "x402 REST client for readfetch.com (probe, text, …)",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/readfetch/client-js.git"
+  },
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": ["index.mjs", "config.mjs", "endpoints.mjs", "payment.mjs", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "scripts": {
+    "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",
+    "@x402/fetch": "2.29.0",
+    "viem": "2.57.13"
+  }
+}

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,
+  };
+}