@readfetch/client 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,44 @@
-# 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): **`probe`** (free) and **`readfetchText`** (paid `/v1/text`).
+
+Source of truth in the private service checkout: `tools/client-js`. Published to GitHub with `./scripts/publish-client-js.sh`.
+
+## Install
+
+```bash
+npm install @readfetch/client
+```
+
+## Use
+
+```bash
+export EVM_PRIVATE_KEY=0x…   # not needed for probe()
+```
+
+```javascript
+import { probe, probeWithMeta, readfetchText, submitFeedback } 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");
+}
+// Integrator issues (not billing):
+// await submitFeedback(requestId, "integration", "402 confused my parser");
+```
+
+## 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 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`.
+
+**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).

package/config.mjs

@@ -0,0 +1,81 @@
+/**
+ * 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]"]);
+
+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");
+  }
+  if (isProductionHost(url.hostname)) {
+    if (url.protocol !== "https:") {
+      throw new Error("READFETCH_BASE_URL must use https for readfetch.com");
+    }
+    return raw;
+  }
+  if (env.READFETCH_DEV === "1" && isDevHost(url.hostname)) {
+    return raw;
+  }
+  throw new Error(
+    "READFETCH_BASE_URL must be https://readfetch.com (or localhost with READFETCH_DEV=1)",
+  );
+}
+
+/** @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;
+}

package/index.mjs

@@ -0,0 +1,116 @@
+import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  loadAccountFromEnv,
+  parseMaxPaymentUsd,
+  readfetchBase,
+  x402Network,
+} from "./config.mjs";
+
+export {
+  isDevHost,
+  isProductionHost,
+  loadAccountFromEnv,
+  parseMaxPaymentUsd,
+  readfetchBase,
+  x402Network,
+} from "./config.mjs";
+
+const TIMEOUT_MS = 120_000;
+
+const FEEDBACK_CATEGORIES = new Set(["integration", "docs", "site", "other"]);
+
+let fetchWithPayment;
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function paidFetch(env = process.env) {
+  if (!fetchWithPayment) {
+    const account = privateKeyToAccount(loadAccountFromEnv(env));
+    fetchWithPayment = wrapFetchWithPaymentFromConfig(globalThis.fetch, {
+      schemes: [{ network: x402Network(env), client: new ExactEvmScheme(account) }],
+      spendControls: { maxAmountPerPayment: `$${parseMaxPaymentUsd(env)}` },
+    });
+  }
+  return fetchWithPayment;
+}
+
+/** `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");
+}
+
+/** 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) {
+  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) };
+}
+
+/** 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 (!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);
+}
+
+/** 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();
+}
+
+/** 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.1",
+  "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", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "scripts": {
+    "test": "node test-static.mjs",
+    "prepublishOnly": "node --check index.mjs && node --check config.mjs && node test-static.mjs"
+  },
+  "dependencies": {
+    "@x402/evm": "2.29.0",
+    "@x402/fetch": "2.29.0",
+    "viem": "2.57.13"
+  }
+}