scvd-corpus-client 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# scvd-corpus-client — changelog
+
+Versions are immutable once published. Minor versions add functions and
+never change an existing function's result.
+
+## 0.1.0 — 2026-09-10
+
+Initial release preparation: `corpus`, `freshSet`, `hostHistory`, `month`,
+`feeds`, `diff`, `defects`, `withDenominator`, `CorpusHttpError`, and
+`corpusIndex` with `CorpusIndexOptions`. Zero dependencies.
+
+The original readers were implemented September 3 (roadmap C5). Compact
+discovery was added September 10: one metadata page per call, caller-controlled
+pagination, gaps and verification limits preserved. Existing readers keep
+their original responses. The package reads evidence; it does not verify it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Record
+
+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.

package/README.md

@@ -0,0 +1,91 @@
+# scvd-corpus-client
+
+Zero-dependency reader for [scvd.store](https://scvd.store)'s signed
+x402 corpus: the weekly census, the fresh set, one host's readiness
+history, the month, the feeds, the diff and the defect vocabulary, each
+as the store serves it. The `scvd` CLI's library half.
+
+## Install
+
+```sh
+npm install scvd-corpus-client
+```
+
+Node 18.17 or newer. To use a source checkout, import
+`./corpus-client/corpus-client.js` instead of the package name.
+
+## Use
+
+```js
+import { corpus, hostHistory, month, feeds } from "scvd-corpus-client";
+
+const census = await corpus();                 // the weekly signed census, whole
+const history = await hostHistory("door.example");
+const august = await month("2026-08");         // the state of x402 for one month
+const atom = await feeds();                    // the four Atom feeds, by address
+```
+
+Each reader makes at most one GET to a stable address and returns the store's
+JSON whole. Nothing is summarised, scored or re-derived here: the
+corpus is signed, with each digest submitted for Bitcoin anchoring.
+Pending submissions still need completed proofs and independent verification. A client that rewrote it
+would be a second source of truth. Check the signatures with
+[`x402-verify`](https://www.npmjs.com/package/x402-verify) or any
+ed25519 library against the key at `/.well-known/scvd-signing-key`.
+
+`withDenominator(count, of, noun)` prints a counted reading with its
+denominator beside it — "3 of 4 rounds" — and never a percentage: the
+store's rule is that counts travel with denominators and a share
+invites a ranking.
+
+## What it is not
+
+Not a ranking and not advice: a host's history is what the store
+observed on the rounds it probed, with the gaps counted against the
+observer. A host never met comes back as never met, a fact about
+coverage. The doors' own `what_this_is_not` fields ride in every answer.
+
+## Versioning
+
+Versions are immutable once published. Minor versions add functions
+and never change an existing function's result; the result shapes are
+the store's own documents, which carry their own versions. The dated
+record is `CHANGELOG.md`.
+
+### Compact discovery
+
+`corpusIndex({ limit?, cursor?, base?, fetch?, timeoutMs? })` returns one
+page from `/corpus/index.json`. Omit `limit` to use the server's default;
+the server enforces its maximum. It makes one GET and never follows `next`
+or fetches snapshot bodies. For example:
+
+```js
+import { corpusIndex } from "scvd-corpus-client";
+
+const page = await corpusIndex({ limit: 1 });
+console.log(page); // includes unreadable rows, counts and verification limits
+// When you decide to fetch another page:
+if (page.has_more === true && typeof page.next === "string") {
+  const cursor = new URL(page.next).searchParams.get("cursor");
+  if (!cursor) throw new Error("Incomplete pagination: next has no cursor");
+  const nextPage = await corpusIndex({ limit: 1, cursor });
+  console.log(nextPage);
+}
+```
+
+A page with `has_more: true` and no `next` is incomplete. Keep unreadable
+rows in the denominator, and preserve the server's `verification` and
+`completeness` fields. This is metadata discovery; the helper does not
+verify signatures, chain links or Bitcoin proofs. Pagination does not
+establish a point-in-time inventory. `corpus()` keeps its original whole
+`/corpus.json` response.
+
+Invalid option shapes throw `TypeError` without a request. HTTP refusals
+throw `CorpusHttpError` with the status and server body; timeouts and
+network failures reject. An unreadable successful page rejects instead
+of becoming an empty inventory. The existing `timeoutMs` option defaults
+to 30 seconds. Every read is free and needs no account, key or wallet.
+
+For bounded snapshot export and offline verification, use the published
+[x402-verify evidence CLI](https://github.com/seancrecord/scvd-general-store-repo/tree/main/verifier#portable-evidence),
+with explicit byte-limit settings for larger snapshots.

package/corpus-client.d.ts

@@ -0,0 +1,24 @@
+export const DEFAULT_BASE: string;
+export const DOORS: Readonly<{
+  corpus: string;
+  corpus_index: string;
+  fresh_set: string;
+  host: (host: string) => string;
+  month: (month?: string) => string;
+  feeds: string;
+  diff: string;
+  defects: string;
+}>;
+export interface ClientOptions { base?: string; fetch?: typeof fetch; timeoutMs?: number }
+export interface CorpusIndexOptions extends ClientOptions { limit?: number; cursor?: string }
+/** One metadata page, returned whole; does not follow next or verify evidence. */
+export function corpusIndex(options?: CorpusIndexOptions): Promise<Record<string, unknown>>;
+export class CorpusHttpError extends Error { status: number; body: unknown }
+export function corpus(options?: ClientOptions): Promise<Record<string, unknown>>;
+export function freshSet(options?: ClientOptions): Promise<Record<string, unknown>>;
+export function hostHistory(host: string, options?: ClientOptions): Promise<Record<string, unknown>>;
+export function month(which?: string, options?: ClientOptions): Promise<Record<string, unknown>>;
+export function feeds(options?: ClientOptions): Promise<Record<string, unknown>>;
+export function diff(options?: ClientOptions): Promise<Record<string, unknown>>;
+export function defects(options?: ClientOptions): Promise<Record<string, unknown>>;
+export function withDenominator(count: number, of: number, noun: string): string;

package/corpus-client.js

@@ -0,0 +1,135 @@
+/**
+ * scvd-corpus-client — the signed corpus, read as the store serves it.
+ *
+ * Every function is one GET to a public, stable address and returns
+ * the store's own JSON, whole. Nothing is summarised, scored or
+ * re-derived here: snapshots are signed with timestamp status, and a
+ * client that rewrote it would be a second source of truth. The
+ * signatures are checkable with the x402-verify package, or any
+ * ed25519 library, against the key at /.well-known/scvd-signing-key.
+ *
+ * Node builtins and global fetch only. Nothing installed.
+ */
+
+export const DEFAULT_BASE = "https://scvd.store";
+
+export const DOORS = Object.freeze({
+  corpus: "/corpus.json",
+  corpus_index: "/corpus/index.json",
+  fresh_set: "/fresh-set.json",
+  host: (host) => `/corpus/host/${encodeURIComponent(host)}.json`,
+  month: (month) => (month ? `/corpus/month/${month}` : "/corpus/month"),
+  feeds: "/feeds",
+  diff: "/corpus/diff.json",
+  defects: "/defects.json",
+});
+
+const UA = "scvd-corpus-client (+https://scvd.store/corpus)";
+/** Trailing slashes off an origin, without a regular expression over caller input. */
+function trimSlashes(value) {
+  let end = String(value).length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return String(value).slice(0, end);
+}
+
+
+export class CorpusHttpError extends Error {
+  constructor(path, status, body) {
+    super(`${path} answered ${status}${body && typeof body === "object" && body.error ? `: ${body.error}` : ""}`);
+    this.name = "CorpusHttpError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+async function getJson(base, path, fetchImpl, timeoutMs, requireObject = false) {
+  const response = await fetchImpl(`${trimSlashes(base)}${path}`, {
+    headers: { accept: "application/json", "user-agent": UA },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+  if (!response.ok) throw new CorpusHttpError(path, response.status, body);
+  if (requireObject && (body === null || typeof body !== "object" || Array.isArray(body))) {
+    throw new TypeError(`${path} did not return a JSON object.`);
+  }
+  return body;
+}
+
+function opts({ base = DEFAULT_BASE, fetch: fetchImpl = fetch, timeoutMs = 30_000 } = {}) {
+  return { base, fetchImpl, timeoutMs };
+}
+
+/** The weekly signed census, whole. */
+export function corpus(options) {
+  const o = opts(options);
+  return getJson(o.base, DOORS.corpus, o.fetchImpl, o.timeoutMs);
+}
+
+/** One discovery page, not signature verification. Never follows next or fetches snapshots. */
+export function corpusIndex(options = {}) {
+  const { limit, cursor } = options;
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1)) {
+    throw new TypeError("corpusIndex: limit must be a positive whole number; the server sets the maximum");
+  }
+  if (cursor !== undefined && (typeof cursor !== "string" || !cursor)) {
+    throw new TypeError("corpusIndex: cursor must be the nonempty string from the preceding page");
+  }
+  const o = opts(options);
+  const query = new URLSearchParams();
+  if (limit !== undefined) query.set("limit", String(limit));
+  if (cursor !== undefined) query.set("cursor", cursor);
+  const suffix = query.toString() ? `?${query}` : "";
+  return getJson(o.base, `${DOORS.corpus_index}${suffix}`, o.fetchImpl, o.timeoutMs, true);
+}
+
+/** This week's doors that answered a conformant challenge. */
+export function freshSet(options) {
+  const o = opts(options);
+  return getJson(o.base, DOORS.fresh_set, o.fetchImpl, o.timeoutMs);
+}
+
+/** One host's readiness history: rounds probed of rounds since first sighting, the tier with its fraction, the gaps counted against the observer. */
+export function hostHistory(host, options) {
+  const o = opts(options);
+  return getJson(o.base, DOORS.host(String(host).toLowerCase()), o.fetchImpl, o.timeoutMs);
+}
+
+/** The state of x402 for one month (YYYY-MM), or the latest month. */
+export function month(which, options) {
+  if (which !== undefined && !/^\d{4}-\d{2}$/.test(String(which))) throw new TypeError("month: pass YYYY-MM, or nothing for the latest");
+  const o = opts(options);
+  return getJson(o.base, DOORS.month(which), o.fetchImpl, o.timeoutMs);
+}
+
+/** The four Atom feeds, by address, from the store's own index. */
+export function feeds(options) {
+  const o = opts(options);
+  return getJson(o.base, DOORS.feeds, o.fetchImpl, o.timeoutMs);
+}
+
+/** What changed between the two latest signed snapshots. */
+export function diff(options) {
+  const o = opts(options);
+  return getJson(o.base, DOORS.diff, o.fetchImpl, o.timeoutMs);
+}
+
+/** The defect vocabulary, live. */
+export function defects(options) {
+  const o = opts(options);
+  return getJson(o.base, DOORS.defects, o.fetchImpl, o.timeoutMs);
+}
+
+/**
+ * A counted reading with its denominator beside it, as a string a
+ * report can print: "3 of 4 rounds". Never a percentage: the store's
+ * rule is that counts travel with denominators and a share invites a
+ * ranking.
+ */
+export function withDenominator(count, of, noun) {
+  return `${count} of ${of} ${noun}`;
+}

package/example.mjs

@@ -0,0 +1,9 @@
+// What the corpus holds about one host. Run: node example.mjs door.example
+import { hostHistory, withDenominator } from "./corpus-client.js";
+
+const host = process.argv[2] ?? "door.example";
+const history = await hostHistory(host);
+console.log(JSON.stringify(history, null, 2));
+if (typeof history.rounds_probed === "number" && typeof history.rounds_since_first_sighting === "number") {
+  console.log(withDenominator(history.rounds_probed, history.rounds_since_first_sighting, "rounds since first sighting"));
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "scvd-corpus-client",
+  "version": "0.1.0",
+  "description": "Zero-dependency reader for scvd.store's signed x402 corpus: the weekly census, the fresh set, one host's readiness history, the month, the feeds and the diff, as the store serves them. The scvd CLI's library half.",
+  "type": "module",
+  "main": "./corpus-client.js",
+  "types": "./corpus-client.d.ts",
+  "exports": { ".": { "types": "./corpus-client.d.ts", "default": "./corpus-client.js" } },
+  "files": ["corpus-client.js", "corpus-client.d.ts", "example.mjs", "CHANGELOG.md", "README.md", "LICENSE"],
+  "engines": { "node": ">=18.17.0" },
+  "keywords": ["x402", "corpus", "census", "dataset", "readiness", "agent-payments", "evidence", "atom"],
+  "license": "MIT",
+  "author": "scvd.store",
+  "homepage": "https://scvd.store/corpus",
+  "repository": { "type": "git", "url": "git+https://github.com/seancrecord/scvd-general-store-repo.git", "directory": "corpus-client" },
+  "bugs": { "url": "https://github.com/seancrecord/scvd-general-store-repo/issues" }
+}