countersignatory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Countersignatory Ltd
+
+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,66 @@
+# countersignatory
+
+The going rate for a human minute. A JavaScript and TypeScript client for the Countersignatory quote API and Spot Index. No dependencies, global `fetch`, Node 18 and later, ESM with types.
+
+**Nothing is fulfilled yet.** Every price is an indicative quote, not a binding offer. No task is taken, no work is done and no money moves.
+
+## Quickstart
+
+```ts
+import { quote, interest, index, market } from "countersignatory";
+
+const q = await quote({ task: "approval", tier: "check", sla: 900, maxPrice: 1.5 });
+console.log(q.unit_price, q.band, q.would_clear, q.quote_id);
+
+await interest({ quote: q, wouldPay: true, note: "labelling 200 eval rows a week" }); // this price would clear
+await index();                                                                      // the Spot Index
+await market("countersign.certified_translation");                                  // one market from it
+await interest({ market: "countersign.certified_translation", wouldPay: true });   // vote to open a market
+```
+
+Arguments map one-to-one onto `POST /v1/quotes`: `task` is `task_type`, `sla` is `sla_seconds`, `n` is `consensus_n`, `maxPrice` is `max_price`, `market` is `market_id`, and `jurisdiction`, `unassisted` and `criteria` keep their names. The quote comes back exactly as the API sent it, with `derived` carrying what is derived rather than measured. Nothing is rounded.
+
+## Keys
+
+A key is free, instant and needs no approval. The client looks for one in this order:
+
+1. `key` on the call.
+2. `COUNTERSIGNATORY_KEY` in the environment.
+3. The cached file `~/.config/countersignatory/key` (`%APPDATA%\countersignatory\key` on Windows), mode 0600.
+4. In CI (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI` or `JENKINS_URL` set), it throws `KeyRequired`. It never issues a key in CI, because every ephemeral runner would mint a new one. Set `COUNTERSIGNATORY_KEY` in your CI secrets.
+5. Otherwise it takes a key with `POST /v1/keys`, caches it and prints one line to stderr saying where.
+
+`index()` and `market()` need no key.
+
+## Errors
+
+Nothing is retried and nothing is substituted. An error from the API is thrown as `CountersignatoryError` with `code`, `message`, `status` and `body`. Quoting a market that is listed but not open throws `MarketNotOpen`, whose message carries the one line that registers interest in it. A key that is not in the shape the API issues throws `InvalidKey`.
+
+## What it sends
+
+Each request carries `x-countersignatory-client: js/0.1.0`, so calls from this client can be counted as a channel. That header is the only telemetry. Nothing is sent on import.
+
+Set `COUNTERSIGNATORY_BASE_URL` to point the client somewhere other than `https://countersignatory.com`.
+
+## Markets
+
+<!-- prices:start -->
+Indicative prices from the Spot Index, index version `seed-2026-09-23b`, read when this package was built. They are seeded from third-party comparables, not live clears, and do not update with the package. Call `index()` for the current figures and `/methodology` for how each one is derived.
+
+| Market | Tier | State | Indicative base (USD) | Band | Unit |
+|---|---|---|---|---|---|
+| `check.general` | check | open | $0.80 | $0.50 to $1.50 | per task |
+| `consensus.3.general` | consensus | open | $3.50 | $2.60 to $5.00 | per task |
+| `consensus.5.general` | consensus | open | $5.60 | $4.20 to $8.00 | per task |
+| `countersign.domain_expert` | countersign | open | $18.00 | $12.00 to $30.00 | per attestation |
+| `countersign.uk_professional` | countersign | open | $25.00 | $15.00 to $40.00 | per attestation |
+| `countersign.accessibility_statement` | countersign | opening | $21.00 | $14.00 to $28.00 | per criterion (MED shown) |
+| `countersign.certified_translation` | countersign | opening | $16.00 | $12.00 to $24.00 | per page (250 words) |
+| `seal.notarisation_us` | seal | open | $45.00 | $38.00 to $60.00 | per seal |
+
+A market in the `opening` state is listed with a reference rate but takes no quotes yet. Quoting it raises `market_not_open`; registering interest is the vote that opens it.
+<!-- prices:end -->
+
+Methodology: https://countersignatory.com/methodology
+
+MIT licence. Countersignatory Ltd.

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+export declare const VERSION = "0.1.0";
+export declare const DEFAULT_BASE_URL = "https://countersignatory.com";
+/** An error from the API, or from this client refusing to guess. */
+export declare class CountersignatoryError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    readonly body?: unknown | undefined;
+    constructor(code: string, message: string, status?: number | undefined, body?: unknown | undefined);
+}
+/** The market is listed but has no supply yet, so it cannot be quoted. */
+export declare class MarketNotOpen extends CountersignatoryError {
+    readonly marketId: string | null;
+    readonly registerInterest: string | null;
+    constructor(message: string, marketId: string | null, status?: number, body?: unknown);
+}
+/** No key was found, and this client will not issue one here. */
+export declare class KeyRequired extends CountersignatoryError {
+    constructor(message: string);
+}
+/** A key is not in the shape the API issues, or the API never issued it. */
+export declare class InvalidKey extends CountersignatoryError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+export type TaskType = "judgment" | "verification" | "approval" | "physical" | "signature";
+export type Tier = "check" | "consensus" | "countersign" | "seal";
+export interface Criterion {
+    id: string;
+    status?: "automated-fail" | "automated-review" | "not-flagged" | "not-run" | "manual-only" | "agent-verified";
+    measured?: boolean;
+}
+export interface QuoteArgs {
+    /** task_type */
+    task: TaskType;
+    /** sla_seconds */
+    sla: number;
+    tier?: Tier;
+    /** consensus_n */
+    n?: number;
+    /** max_price */
+    maxPrice?: number;
+    /** market_id */
+    market?: string;
+    jurisdiction?: string;
+    unassisted?: boolean;
+    criteria?: Criterion[];
+    key?: string;
+}
+/** The quote exactly as the API returned it. Values are passed through unrounded. */
+export interface Quote {
+    quote_id: string;
+    market: Record<string, unknown> & {
+        id: string;
+        tier: Tier;
+        state: string;
+    };
+    currency: string;
+    unit_price: number;
+    band: [number, number];
+    multipliers_applied: Record<string, number>;
+    compound_factor: number;
+    derived: {
+        implied_price_per_human_minute: number;
+        implied_responder_hourly: number;
+        responder_take_home: number;
+        effort_minutes?: number;
+        clears_wage_floor: boolean;
+        note: string;
+    };
+    lines?: unknown[];
+    class_table?: string;
+    would_clear: boolean | null;
+    alternatives: Array<{
+        change: string;
+        unit_price: number;
+        would_clear: boolean;
+    }>;
+    next: {
+        register_interest: string;
+    };
+    sla_seconds: number;
+    method: string;
+    price_inputs_ignored: string[];
+    backstop: {
+        available: boolean;
+        note: string;
+    };
+    expires_at: string;
+    disclaimer: string;
+    [field: string]: unknown;
+}
+export interface InterestArgs {
+    /** A quote you were shown, or its quote_id. Exactly one of this or market. */
+    quote?: Quote | string;
+    /** A market that is not open yet. Exactly one of this or quote. */
+    market?: string;
+    wouldPay?: boolean;
+    note?: string;
+    key?: string;
+}
+export interface IndexMarket {
+    id: string;
+    title: string;
+    tier: Tier;
+    state: string;
+    base: number;
+    band: [number, number];
+    unit: string;
+    [field: string]: unknown;
+}
+export interface SpotIndex {
+    version: string;
+    currency: string;
+    markets: IndexMarket[];
+    [field: string]: unknown;
+}
+/**
+ * Price one task. Arguments map one-to-one onto the POST /v1/quotes body: task
+ * is task_type, sla is sla_seconds, n is consensus_n, maxPrice is max_price and
+ * market is market_id. A market that is listed but not open throws MarketNotOpen.
+ */
+export declare function quote(args: QuoteArgs): Promise<Quote>;
+/**
+ * Record that a quoted price would clear (pass the quote or its quote_id), or
+ * that a market that is not open yet is wanted (pass market). Exactly one.
+ */
+export declare function interest(args: InterestArgs): Promise<{
+    ok: boolean;
+    message: string;
+}>;
+/** The Spot Index, as published. Needs no key. */
+export declare function index(): Promise<SpotIndex>;
+/** One market from the Spot Index. An id that is not listed is an error. */
+export declare function market(marketId: string): Promise<IndexMarket>;

package/dist/index.js

@@ -0,0 +1,244 @@
+/**
+ * Countersignatory: the going rate for a human minute.
+ *
+ * A thin client for the Countersignatory quote API. No dependencies: global
+ * fetch, Node 18 or later.
+ *
+ *   import { quote } from "countersignatory";
+ *   const q = await quote({ task: "approval", tier: "check", sla: 900, maxPrice: 1.5 });
+ *
+ * Quotes are indicative. Nothing is fulfilled yet.
+ *
+ * - Every request carries one header, x-countersignatory-client: js/<version>.
+ *   There is no other telemetry, and nothing is sent on import.
+ * - Errors are thrown as they come back. Nothing is retried, and no
+ *   neighbouring tier or market is ever substituted for the one asked for.
+ * - The quote is returned as the server sent it. Nothing is rounded.
+ * - A free key is issued on first use and cached, except in CI, where you must
+ *   set COUNTERSIGNATORY_KEY yourself.
+ */
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const VERSION = "0.1.0";
+export const DEFAULT_BASE_URL = "https://countersignatory.com";
+const CLIENT = `js/${VERSION}`;
+const TIMEOUT_MS = 30_000;
+const KEY_FORMAT = /^csk_live_[0-9a-f]{32}$/;
+const CI_VARS = ["CI", "GITHUB_ACTIONS", "GITLAB_CI", "BUILDKITE", "CIRCLECI", "JENKINS_URL"];
+/** Keys resolved in this process, by base URL, so the cache file is read once. */
+const resolved = new Map();
+/* ------------------------------------------------------------------ errors */
+/** An error from the API, or from this client refusing to guess. */
+export class CountersignatoryError extends Error {
+    code;
+    status;
+    body;
+    constructor(code, message, status, body) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.status = status;
+        this.body = body;
+        this.name = "CountersignatoryError";
+    }
+}
+/** The market is listed but has no supply yet, so it cannot be quoted. */
+export class MarketNotOpen extends CountersignatoryError {
+    marketId;
+    registerInterest;
+    constructor(message, marketId, status, body) {
+        const line = marketId ? `await interest({ market: "${marketId}", wouldPay: true })` : null;
+        super("market_not_open", line ? `${message}\n\nRegistering interest is the vote that opens it:\n\n    ${line}` : message, status, body);
+        this.marketId = marketId;
+        this.name = "MarketNotOpen";
+        this.registerInterest = line;
+    }
+}
+/** No key was found, and this client will not issue one here. */
+export class KeyRequired extends CountersignatoryError {
+    constructor(message) {
+        super("key_required", message);
+        this.name = "KeyRequired";
+    }
+}
+/** A key is not in the shape the API issues, or the API never issued it. */
+export class InvalidKey extends CountersignatoryError {
+    constructor(message, status, body) {
+        super("invalid_key", message, status, body);
+        this.name = "InvalidKey";
+    }
+}
+/* --------------------------------------------------------------- transport */
+function baseUrl() {
+    return (process.env.COUNTERSIGNATORY_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+/** @internal Exported for tests. */
+export async function request(method, path, body, key) {
+    const headers = { accept: "application/json", "x-countersignatory-client": CLIENT };
+    if (body !== undefined)
+        headers["content-type"] = "application/json";
+    if (key)
+        headers.authorization = `Bearer ${key}`;
+    const res = await fetch(baseUrl() + path, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    const text = await res.text();
+    let payload = text;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        // Not JSON: surfaced as-is below.
+    }
+    if (!res.ok) {
+        const error = payload && typeof payload === "object" ? payload.error ?? {} : {};
+        const message = error.message ?? (error.issues ? JSON.stringify(error.issues) : `HTTP ${res.status} from ${path}`);
+        if (error.code === "invalid_key")
+            throw new InvalidKey(message, res.status, payload);
+        throw new CountersignatoryError(error.code ?? `http_${res.status}`, message, res.status, payload);
+    }
+    return payload;
+}
+/* -------------------------------------------------------------------- keys */
+function configDir() {
+    if (process.platform === "win32" && process.env.APPDATA)
+        return join(process.env.APPDATA, "countersignatory");
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "countersignatory");
+}
+/**
+ * The default server uses the documented path. Any other server gets its own
+ * file, so a key issued by a local test server is never sent to production,
+ * where it would be silently unrecognised.
+ */
+function cachePath(base) {
+    if (base === DEFAULT_BASE_URL)
+        return join(configDir(), "key");
+    let host = "unknown";
+    try {
+        host = new URL(base).host.replace(/[^A-Za-z0-9.-]/g, "_") || "unknown";
+    }
+    catch {
+        // Left as unknown.
+    }
+    return join(configDir(), `key@${host}`);
+}
+function inCI() {
+    return CI_VARS.some((name) => {
+        const v = (process.env[name] ?? "").trim().toLowerCase();
+        return v !== "" && v !== "0" && v !== "false" && v !== "no";
+    });
+}
+function checked(key, source) {
+    const k = key.trim();
+    if (!KEY_FORMAT.test(k)) {
+        throw new InvalidKey(`The key from ${source} is not a Countersignatory key. Keys look like csk_live_ followed by 32 hex characters.`);
+    }
+    return k;
+}
+async function resolveKey(explicit) {
+    if (explicit !== undefined)
+        return checked(explicit, "the key argument");
+    const env = process.env.COUNTERSIGNATORY_KEY;
+    if (env)
+        return checked(env, "COUNTERSIGNATORY_KEY");
+    const base = baseUrl();
+    const memo = resolved.get(base);
+    if (memo)
+        return memo;
+    const path = cachePath(base);
+    let cached = null;
+    try {
+        cached = await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT")
+            throw err;
+    }
+    if (cached !== null) {
+        const key = checked(cached, path);
+        resolved.set(base, key);
+        return key;
+    }
+    if (inCI()) {
+        throw new KeyRequired("CI detected, so no key is issued automatically: every ephemeral runner would mint a new one. " +
+            "Take a free key once with POST /v1/keys and set it as COUNTERSIGNATORY_KEY in your CI secrets.");
+    }
+    const issued = await request("POST", "/v1/keys", {});
+    const key = checked(issued.key, "POST /v1/keys");
+    resolved.set(base, key);
+    try {
+        await mkdir(configDir(), { recursive: true, mode: 0o700 });
+        await writeFile(path, key + "\n", { mode: 0o600 });
+        await chmod(path, 0o600);
+    }
+    catch (err) {
+        process.stderr.write(`countersignatory: issued a free key but could not save it to ${path} (${err?.code ?? err}). ` +
+            "It is used for this process only. Set COUNTERSIGNATORY_KEY to use your own.\n");
+        return key;
+    }
+    process.stderr.write(`countersignatory: issued a free key, saved to ${path}. Set COUNTERSIGNATORY_KEY to use your own.\n`);
+    return key;
+}
+/* ----------------------------------------------------------------- surface */
+/**
+ * Price one task. Arguments map one-to-one onto the POST /v1/quotes body: task
+ * is task_type, sla is sla_seconds, n is consensus_n, maxPrice is max_price and
+ * market is market_id. A market that is listed but not open throws MarketNotOpen.
+ */
+export async function quote(args) {
+    const fields = {
+        task_type: args.task,
+        sla_seconds: args.sla,
+        tier: args.tier,
+        consensus_n: args.n,
+        max_price: args.maxPrice,
+        market_id: args.market,
+        jurisdiction: args.jurisdiction,
+        unassisted: args.unassisted,
+        criteria: args.criteria,
+    };
+    const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+    const key = await resolveKey(args.key);
+    try {
+        return await request("POST", "/v1/quotes", body, key);
+    }
+    catch (err) {
+        if (err instanceof CountersignatoryError && err.code === "market_not_open") {
+            const message = err.body?.error?.message ?? err.message;
+            throw new MarketNotOpen(message, args.market ?? null, err.status, err.body);
+        }
+        throw err;
+    }
+}
+/**
+ * Record that a quoted price would clear (pass the quote or its quote_id), or
+ * that a market that is not open yet is wanted (pass market). Exactly one.
+ */
+export async function interest(args) {
+    if ((args.quote === undefined) === (args.market === undefined)) {
+        throw new CountersignatoryError("invalid_request", "Pass exactly one of quote (or its quote_id), for a price you were shown, or market, for a market that is not open yet.");
+    }
+    const body = args.quote !== undefined
+        ? { quote_id: typeof args.quote === "string" ? args.quote : args.quote.quote_id }
+        : { market_id: args.market };
+    if (args.wouldPay !== undefined)
+        body.would_pay = args.wouldPay;
+    if (args.note !== undefined)
+        body.note = args.note;
+    return request("POST", "/v1/interest", body, await resolveKey(args.key));
+}
+/** The Spot Index, as published. Needs no key. */
+export async function index() {
+    return request("GET", "/v1/index");
+}
+/** One market from the Spot Index. An id that is not listed is an error. */
+export async function market(marketId) {
+    const found = (await index()).markets.find((m) => m.id === marketId);
+    if (!found) {
+        throw new CountersignatoryError("unknown_market", `No market '${marketId}' is listed on the Spot Index. Call index() for the list.`);
+    }
+    return found;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "countersignatory",
+  "version": "0.1.0",
+  "description": "The going rate for a human minute. A dependency-free client for the Countersignatory quote API and Spot Index.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/sdk.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Countersignatory Ltd <douglas@countersignatory.com>",
+  "license": "MIT",
+  "homepage": "https://countersignatory.com",
+  "bugs": {
+    "email": "douglas@countersignatory.com"
+  },
+  "keywords": [
+    "countersignatory",
+    "human-in-the-loop",
+    "ai-agents",
+    "pricing",
+    "verification",
+    "spot-index"
+  ],
+  "countersignatory": {
+    "methodology": "https://countersignatory.com/methodology"
+  }
+}