footnote-data 0.1.0

package/README.md

@@ -0,0 +1,238 @@
+# footnote — the Footnote Data API from your terminal
+
+Employment-diligence data from primary public records: statutory WARN layoff
+notices, certified H-1B/LCA wage filings, USCIS petition outcomes, DOL Wage &
+Hour and OSHA enforcement, federal litigation posture, and severance terms
+parsed from SEC filings. Counts are measured, matches are exact-or-absent, and
+every response carries `data_gaps` — absence of evidence is always
+distinguished from evidence of absence.
+
+Zero runtime dependencies. Node 18+. Docs and pricing: <https://usefootnote.com/data>.
+
+## Install
+
+```bash
+# one-off
+npx footnote-data warn recent --state CA
+
+# global
+npm install -g footnote-data
+footnote warn recent --state CA
+```
+
+## Quickstart
+
+```bash
+# 1. Create a free account at https://usefootnote.com
+# 2. Issue your API key at https://usefootnote.com/account  (Data API section — shown once)
+# 3. Put it in your environment:
+export FOOTNOTE_API_KEY=fn_live_your_key_here
+
+# First call: layoff notices filed in California in the last 30 days
+footnote warn recent --state CA
+```
+
+No key yet? Any command tells you exactly how to get one:
+
+```text
+$ footnote warn recent
+Pass your API key as: Authorization: Bearer fn_live_…
+
+Get a free API key (50 calls/day) in three steps:
+  1. Create a free account at https://usefootnote.com
+  2. Issue your key at https://usefootnote.com/account (Data API section — the key is shown once)
+  3. export FOOTNOTE_API_KEY=fn_live_…   (or pass --key fn_live_…)
+```
+
+## Commands
+
+Sample outputs below are illustrative of the response shape — run the command
+for live data.
+
+### WARN layoff notices
+
+```bash
+# Recent notices, newest first (free tier: last 30 days)
+footnote warn recent --state CA --days 14 --limit 25
+
+# Search by employer across states with a date window and pagination
+footnote warn notices --employer "Boeing" --since 2026-06-01 --limit 50
+footnote warn notices --state TX --until 2026-07-01 --offset 100
+
+# Per-state summary: notice counts, workers affected, latest filing
+footnote warn states
+```
+
+```text
+$ footnote warn recent --state CA --limit 2
+employer_name_raw        state_code  notice_date  effective_date  workers_affected  city        layoff_type  source_url
+───────────────────────  ──────────  ───────────  ──────────────  ────────────────  ──────────  ───────────  ────────────────────────────
+Example Manufacturing    CA          2026-07-10   2026-09-08                   214  Fremont     Closure      https://edd.ca.gov/...
+Sample Logistics Co      CA          2026-07-09   —                            88   Ontario     Layoff       https://edd.ca.gov/...
+
+count: 2 · window_days: 30 · state: CA · tier: free
+source: Official state WARN publications, ingested daily by Footnote (usefootnote.com)
+license: CC BY 4.0 for display with attribution; no redistribution as a dataset/API
+```
+
+### H-1B sponsorship & wages
+
+```bash
+# Does this employer sponsor? (certified LCA corpus)
+footnote h1b employer "Databricks"
+
+# Top sponsors by certified filing volume (free tier: top 25)
+footnote h1b top-sponsors --limit 10
+
+# Petition OUTCOMES (USCIS) + current attestation INTENT (LCA), in one view
+footnote sponsorship "Meta Platforms"
+
+# Advertised (job posting) vs DOL-attested wages, same occupation and area
+footnote wage-comparison "Example Corp"
+```
+
+```text
+$ footnote sponsorship "Example Corp"
+employer                                example corp
+matched_as                              entity
+matched                                 true
+posture                                 growing
+latest_fiscal_year.fiscal_year          2023
+latest_fiscal_year.initial_petition_approvals  412
+current_attestation.matched             true
+current_attestation.fiscal_year         2026
+current_attestation.certified_filings   380
+data_gaps                               (none)
+
+tier: free
+▲ upgrade: Full fiscal-year series and denial rates are on Data Pro — usefootnote.com/data
+```
+
+### Employer enforcement & filings records
+
+```bash
+# DOL Wage & Hour enforcement posture (concluded cases, exact-name matched)
+footnote enforcement "Example Restaurants LLC"
+
+# OSHA inspections and citations
+footnote osha "Example Warehousing"
+
+# Federal litigation posture (CourtListener/RECAP; employer-level aggregates only)
+footnote litigation "Example Corp"
+
+# Executive severance / change-in-control terms from SEC Exhibit 10 filings
+footnote severance "Example Corp"
+```
+
+### Dataset provenance
+
+```bash
+# Row counts, coverage windows, and freshness — measured live at request time
+footnote datasets
+```
+
+Built for citations: the response includes a suggested footnote of the form
+`"Footnote Data API (usefootnote.com/data), retrieved <date>; dataset: <dataset>."`
+
+### `footnote get` — works with endpoints that don't exist yet
+
+The passthrough issues an authenticated GET against any path under the API, so
+when Footnote ships a new endpoint the CLI already supports it — no update
+required. This is the auto-upgrade property: the CLI grows with the API.
+
+```bash
+# Any endpoint, current or future
+footnote get /api/data/v1/warn/recent state=CA limit=5
+
+# Discover every endpoint from the live OpenAPI contract (public, no key needed)
+footnote get /api/data/v1/openapi.json
+
+# CSV export (Data Pro) — text bodies pass through untouched
+footnote get /api/data/v1/warn/export.csv > warn-24mo.csv
+
+# Full historical archive (one-time purchase)
+footnote get /api/data/v1/warn/historical.csv > warn-all.csv
+```
+
+## Output modes
+
+- **TTY**: aligned tables for lists, key/value views for lookups, meta printed
+  beneath.
+- **`--json` or piped**: the raw response body, exactly as the API returned it.
+
+```bash
+footnote warn states --json | jq '.data[0]'
+footnote h1b top-sponsors | jq '.data[].employer_name'   # piped ⇒ JSON automatically
+```
+
+Exit codes: `0` success · `1` API or network error · `2` usage error.
+
+## Rate limits
+
+| Tier | Calls/day | Burst | WARN window | Price |
+|---|---|---|---|---|
+| Free | 50 | 10/min | 30 days | $0 |
+| Data Pro | 10,000 | 120/min | 24 months | see [usefootnote.com/data](https://usefootnote.com/data) |
+| Enterprise | 100,000 | 600/min | full archive | contact |
+
+Hitting the free cap is the product working — the CLI shows you the way up:
+
+```text
+╭────────────────────────────────────────────────────────────────────────────╮
+│  Daily cap reached (50/day on the free tier).                              │
+│                                                                            │
+│  The free tier is enough to confirm Footnote works inside your product.    │
+│  For production volume, Data Pro is 10,000 calls/day with a 24-month WARN  │
+│  window — $79/mo.                                                          │
+│                                                                            │
+│  Your daily meter resets at 2026-07-17T00:00:00.000Z.                      │
+│                                                                            │
+│  https://usefootnote.com/data#pricing                                      │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Configuration
+
+| Setting | Env var | Flag | Default |
+|---|---|---|---|
+| API key | `FOOTNOTE_API_KEY` | `--key fn_live_…` | — |
+| API origin | `FOOTNOTE_API_URL` | `--api-url https://…` | `https://usefootnote.com` |
+| Colors | `NO_COLOR` | `--no-color` | on for TTY |
+
+## MCP / AI assistants
+
+An MCP server (`@footnote/mcp`) exposing these endpoints as tools is planned.
+Today, point any OpenAPI-capable agent or tool at the live machine-readable
+contract:
+
+```text
+https://usefootnote.com/api/data/v1/openapi.json
+```
+
+## License & attribution
+
+CLI code: MIT.
+
+Data returned on the **free tier** is licensed **CC BY 4.0 for display with
+attribution** — credit `Data: Footnote (usefootnote.com)` where you show it;
+redistribution as a dataset or API is not permitted. Paid tiers are governed by
+your Footnote Data agreement. Every response's `meta.license` states the terms
+that apply to that call.
+
+## Endpoint reference
+
+| Command | Endpoint |
+|---|---|
+| `warn recent` | `GET /api/data/v1/warn/recent` |
+| `warn notices` | `GET /api/data/v1/warn/notices` |
+| `warn states` | `GET /api/data/v1/warn/states` |
+| `h1b employer` | `GET /api/data/v1/h1b/employer` |
+| `h1b top-sponsors` | `GET /api/data/v1/h1b/top-sponsors` |
+| `sponsorship` | `GET /api/data/v1/sponsorship/employer` |
+| `enforcement` | `GET /api/data/v1/enforcement/employer` |
+| `litigation` | `GET /api/data/v1/litigation/employer` |
+| `osha` | `GET /api/data/v1/osha/employer` |
+| `severance` | `GET /api/data/v1/severance/employer` |
+| `wage-comparison` | `GET /api/data/v1/wage-comparison/employer` |
+| `datasets` | `GET /api/data/v1/datasets` |
+| `get <path>` | `GET <any /api/data/v1 path>` |

package/bin/footnote.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from "../footnote.mjs";
+
+run(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+});

package/footnote.mjs

@@ -0,0 +1,536 @@
+/**
+ * footnote — the Footnote Data API from your terminal (https://usefootnote.com/data).
+ *
+ * Zero runtime dependencies; Node >= 18 (global fetch). Every command spec below
+ * mirrors the server route file it names — params here are the route's REAL query
+ * params, read from the source, never guessed.
+ */
+
+export const VERSION = "0.1.0";
+export const DEFAULT_API_URL = "https://usefootnote.com";
+
+const UPGRADE_URL = "https://usefootnote.com/data";
+const KEYS_URL = "https://usefootnote.com/account";
+// Mirrors TIER_LIMITS in lib/data-api/authorize.ts (pro: 10k/day, 120/min, 730-day window).
+const DEFAULT_UPGRADE_TEXT = "Data Pro: 10,000 calls/day · 120 req/min · 24-month WARN window.";
+
+const CELL_MAX = 48;
+
+/* ---------------------------------- styling ---------------------------------- */
+
+const PLAIN = { bold: (s) => s, dim: (s) => s, cyan: (s) => s, yellow: (s) => s };
+
+function makeStyle(enabled) {
+  if (!enabled) return PLAIN;
+  const wrap = (open, close) => (s) => `\u001b[${open}m${s}\u001b[${close}m`;
+  return { bold: wrap(1, 22), dim: wrap(2, 22), cyan: wrap(36, 39), yellow: wrap(33, 39) };
+}
+
+/* ------------------------------ argument parsing ------------------------------ */
+
+const VALIDATORS = {
+  state: {
+    ok: (v) => /^[A-Za-z]{2}$/.test(v),
+    hint: "a two-letter U.S. state code (e.g. CA)",
+    map: (v) => v.toUpperCase(),
+  },
+  posInt: { ok: (v) => /^\d+$/.test(v) && Number(v) >= 1, hint: "a positive integer" },
+  nonNegInt: { ok: (v) => /^\d+$/.test(v), hint: "a non-negative integer" },
+  date: { ok: (v) => /^\d{4}-\d{2}-\d{2}$/.test(v), hint: "a date formatted YYYY-MM-DD" },
+  text3: { ok: (v) => v.trim().length >= 3, hint: "at least 3 characters" },
+};
+
+/**
+ * The command registry. `route` names the server file each spec was read from;
+ * `flags`/`positional` are that route's actual accepted params.
+ */
+export const COMMANDS = [
+  {
+    name: "warn recent",
+    path: "/api/data/v1/warn/recent",
+    route: "app/api/data/v1/warn/recent/route.ts",
+    summary: "Recent WARN layoff notices, newest first",
+    flags: { state: "state", days: "posInt", limit: "posInt" },
+  },
+  {
+    name: "warn notices",
+    path: "/api/data/v1/warn/notices",
+    route: "app/api/data/v1/warn/notices/route.ts",
+    summary: "Search WARN notices (employer, state, date window, pagination)",
+    flags: { state: "state", employer: "text3", since: "date", until: "date", limit: "posInt", offset: "nonNegInt" },
+  },
+  {
+    name: "warn states",
+    path: "/api/data/v1/warn/states",
+    route: "app/api/data/v1/warn/states/route.ts",
+    summary: "Per-state WARN summaries over your tier's window",
+    flags: {},
+  },
+  {
+    name: "h1b employer",
+    path: "/api/data/v1/h1b/employer",
+    route: "app/api/data/v1/h1b/employer/route.ts",
+    summary: "H-1B sponsorship lookup over certified LCA filings",
+    positional: { param: "name", label: "<company>", min: 3 },
+  },
+  {
+    name: "h1b top-sponsors",
+    path: "/api/data/v1/h1b/top-sponsors",
+    route: "app/api/data/v1/h1b/top-sponsors/route.ts",
+    summary: "Top H-1B sponsors by certified filing volume",
+    flags: { limit: "posInt" },
+  },
+  {
+    name: "sponsorship",
+    path: "/api/data/v1/sponsorship/employer",
+    route: "app/api/data/v1/sponsorship/employer/route.ts",
+    summary: "USCIS petition outcomes + current LCA attestation intent",
+    positional: { param: "name", label: "<employer>", min: 2, max: 160 },
+  },
+  {
+    name: "enforcement",
+    path: "/api/data/v1/enforcement/employer",
+    route: "app/api/data/v1/enforcement/employer/route.ts",
+    summary: "DOL Wage & Hour enforcement posture",
+    positional: { param: "name", label: "<employer>", min: 2 },
+  },
+  {
+    name: "litigation",
+    path: "/api/data/v1/litigation/employer",
+    route: "app/api/data/v1/litigation/employer/route.ts",
+    summary: "Federal litigation posture (CourtListener/RECAP)",
+    positional: { param: "name", label: "<employer>", min: 2 },
+  },
+  {
+    name: "osha",
+    path: "/api/data/v1/osha/employer",
+    route: "app/api/data/v1/osha/employer/route.ts",
+    summary: "OSHA inspections and citations",
+    positional: { param: "name", label: "<employer>", min: 2 },
+  },
+  {
+    name: "severance",
+    path: "/api/data/v1/severance/employer",
+    route: "app/api/data/v1/severance/employer/route.ts",
+    summary: "Executive severance terms parsed from SEC Exhibit 10 filings",
+    positional: { param: "name", label: "<employer>", min: 2 },
+  },
+  {
+    name: "wage-comparison",
+    path: "/api/data/v1/wage-comparison/employer",
+    route: "app/api/data/v1/wage-comparison/employer/route.ts",
+    summary: "Advertised (posting) vs DOL-attested (LCA) wages",
+    positional: { param: "name", label: "<employer>", min: 2 },
+  },
+  {
+    name: "datasets",
+    path: "/api/data/v1/datasets",
+    route: "app/api/data/v1/datasets/route.ts",
+    summary: "Live provenance index: row counts, coverage, freshness",
+    flags: {},
+  },
+];
+
+function findCommand(words) {
+  const two = words.slice(0, 2).join(" ");
+  const one = words[0];
+  return (
+    COMMANDS.find((c) => c.name === two) ??
+    COMMANDS.find((c) => c.name === one) ??
+    null
+  );
+}
+
+/**
+ * Splits global flags from command words. Returns { globals, words } or
+ * { usageError } when a flag is malformed.
+ */
+export function parseGlobals(argv) {
+  const globals = { json: false, key: null, apiUrl: null, noColor: false, help: false, version: false };
+  const words = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") globals.json = true;
+    else if (a === "--no-color") globals.noColor = true;
+    else if (a === "--help" || a === "-h") globals.help = true;
+    else if (a === "--version" || a === "-V") globals.version = true;
+    else if (a === "--key" || a === "--api-url") {
+      const v = argv[++i];
+      if (v === undefined) return { usageError: `${a} needs a value` };
+      if (a === "--key") globals.key = v;
+      else globals.apiUrl = v;
+    } else if (a.startsWith("--key=")) globals.key = a.slice("--key=".length);
+    else if (a.startsWith("--api-url=")) globals.apiUrl = a.slice("--api-url=".length);
+    else words.push(a);
+  }
+  return { globals, words };
+}
+
+/**
+ * Parses one command's tokens into query params. Returns
+ * { path, params: [k, v][] } or { usageError }.
+ */
+export function parseCommand(words) {
+  if (words[0] === "get") return parsePassthrough(words.slice(1));
+
+  const cmd = findCommand(words);
+  if (!cmd) return { usageError: `unknown command: ${words.join(" ")}` };
+
+  const rest = words.slice(cmd.name.split(" ").length);
+  const params = new Map();
+  const positionalWords = [];
+
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    if (token.startsWith("--")) {
+      const eq = token.indexOf("=");
+      const flag = eq === -1 ? token.slice(2) : token.slice(2, eq);
+      const spec = (cmd.flags ?? {})[flag];
+      if (!spec) return { usageError: `unknown flag --${flag} for "${cmd.name}"` };
+      const value = eq === -1 ? rest[++i] : token.slice(eq + 1);
+      if (value === undefined) return { usageError: `--${flag} needs a value` };
+      const validator = VALIDATORS[spec];
+      if (!validator.ok(value)) return { usageError: `--${flag} must be ${validator.hint} (got "${value}")` };
+      params.set(flag, validator.map ? validator.map(value) : value);
+    } else {
+      if (!cmd.positional) return { usageError: `unexpected argument "${token}" for "${cmd.name}"` };
+      positionalWords.push(token);
+    }
+  }
+
+  if (cmd.positional) {
+    const value = positionalWords.join(" ").trim();
+    const { param, label, min, max } = cmd.positional;
+    if (!value) return { usageError: `"${cmd.name}" needs ${label}, e.g. footnote ${cmd.name} "Acme Corp"` };
+    if (value.length < min) return { usageError: `${label} needs at least ${min} characters (got "${value}")` };
+    if (max && value.length > max) return { usageError: `${label} must be at most ${max} characters` };
+    params.set(param, value);
+  }
+
+  return { path: cmd.path, params: [...params.entries()] };
+}
+
+function parsePassthrough(tokens) {
+  const path = tokens[0];
+  if (!path) return { usageError: "get needs a path, e.g. footnote get /api/data/v1/warn/recent state=CA" };
+  if (!path.startsWith("/") || path.includes("://") || !/^\/[A-Za-z0-9/_.\-]*$/.test(path)) {
+    return { usageError: `get takes an absolute API path like /api/data/v1/..., not "${path}"` };
+  }
+  const params = [];
+  for (const token of tokens.slice(1)) {
+    const eq = token.indexOf("=");
+    if (eq <= 0) return { usageError: `get params are key=value pairs (got "${token}")` };
+    params.push([token.slice(0, eq), token.slice(eq + 1)]);
+  }
+  return { path, params };
+}
+
+/** Builds the request URL from an origin, a path, and [k, v] query pairs. */
+export function buildUrl(apiUrl, path, params) {
+  const base = apiUrl.replace(/\/+$/, "");
+  const url = new URL(base + path);
+  for (const [k, v] of params) url.searchParams.append(k, v);
+  return url;
+}
+
+/* -------------------------------- rendering -------------------------------- */
+
+function truncateCell(s) {
+  return s.length > CELL_MAX ? `${s.slice(0, CELL_MAX - 1)}…` : s;
+}
+
+function formatCell(v) {
+  if (v === null || v === undefined) return "—";
+  if (typeof v === "object") return truncateCell(JSON.stringify(v));
+  return truncateCell(String(v));
+}
+
+/** Aligned text table over an array of objects (columns in first-appearance order). */
+export function renderTable(rows, style = PLAIN) {
+  if (!rows.length) return "(no rows)";
+  const cols = [];
+  for (const row of rows) for (const k of Object.keys(row)) if (!cols.includes(k)) cols.push(k);
+  const cells = rows.map((row) => cols.map((c) => formatCell(row[c])));
+  const numeric = cols.map((c) => rows.every((r) => r[c] === null || r[c] === undefined || typeof r[c] === "number"));
+  const widths = cols.map((c, i) => Math.max(c.length, ...cells.map((row) => row[i].length)));
+  const pad = (s, i) => (numeric[i] ? s.padStart(widths[i]) : s.padEnd(widths[i]));
+  const lines = [
+    style.bold(cols.map((c, i) => pad(c, i)).join("  ").trimEnd()),
+    style.dim(widths.map((w) => "─".repeat(w)).join("  ")),
+    ...cells.map((row) => row.map((s, i) => pad(s, i)).join("  ").trimEnd()),
+  ];
+  return lines.join("\n");
+}
+
+/** Key/value view for object payloads; nested objects flatten one level, arrays of objects become sub-tables. */
+export function renderObject(obj, style = PLAIN) {
+  const scalars = [];
+  const tables = [];
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+      for (const [sub, sv] of Object.entries(v)) pushEntry(scalars, tables, `${k}.${sub}`, sv);
+    } else {
+      pushEntry(scalars, tables, k, v);
+    }
+  }
+  const width = scalars.reduce((w, [k]) => Math.max(w, k.length), 0);
+  const lines = scalars.map(([k, v]) => `${style.dim(k.padEnd(width))}  ${v}`);
+  for (const [label, rows] of tables) lines.push("", style.bold(label), renderTable(rows, style));
+  return lines.join("\n");
+}
+
+function pushEntry(scalars, tables, label, v) {
+  if (v === null || v === undefined) scalars.push([label, "—"]);
+  else if (Array.isArray(v)) {
+    if (v.length === 0) scalars.push([label, "(none)"]);
+    else if (typeof v[0] === "object" && v[0] !== null) tables.push([label, v]);
+    else scalars.push([label, v.join(", ")]);
+  } else if (typeof v === "object") scalars.push([label, truncateCell(JSON.stringify(v))]);
+  else scalars.push([label, String(v)]);
+}
+
+function renderMeta(meta, style) {
+  if (!meta || typeof meta !== "object") return [];
+  const inline = ["count", "offset", "window_days", "window_start", "state", "tier"]
+    .filter((k) => meta[k] !== undefined && meta[k] !== null)
+    .map((k) => `${k}: ${meta[k]}`);
+  const lines = [];
+  if (inline.length) lines.push(style.dim(inline.join(" · ")));
+  for (const k of ["match", "units", "interpretation", "privacy", "note", "source", "license", "citation"]) {
+    if (typeof meta[k] === "string") lines.push(style.dim(`${k}: ${meta[k]}`));
+  }
+  if (typeof meta.upgrade === "string") lines.push(style.yellow(`▲ upgrade: ${meta.upgrade}`));
+  return lines;
+}
+
+function wrapText(text, width) {
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(/\s+/)) {
+    if (line && line.length + 1 + word.length > width) {
+      lines.push(line);
+      line = word;
+    } else line = line ? `${line} ${word}` : word;
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+/** Box-drawn upgrade prompt; the URL always gets its own line. */
+export function renderUpgradeBox({ message, upgradeText, upgradeUrl, resetsAt }, style = PLAIN) {
+  const lines = [
+    ...wrapText(message ?? "", 72),
+    "",
+    ...wrapText(upgradeText ?? "", 72),
+    ...(resetsAt ? ["", `Your daily meter resets at ${resetsAt}.`] : []),
+    "",
+    upgradeUrl ?? "",
+  ];
+  const width = Math.max(...lines.map((l) => l.length));
+  return [
+    `╭${"─".repeat(width + 4)}╮`,
+    ...lines.map((l, i) => `│  ${(i === lines.length - 1 ? style.cyan(l.padEnd(width)) : l.padEnd(width))}  │`),
+    `╰${"─".repeat(width + 4)}╯`,
+  ].join("\n");
+}
+
+function upgradeFromBody(body) {
+  const raw = body?.upgrade ?? body?.error?.upgrade ?? body?.meta?.upgrade ?? null;
+  if (raw === null || raw === undefined) return null;
+  if (typeof raw === "string") {
+    const url = (raw.match(/https?:\/\/\S+/) ?? [])[0] ?? UPGRADE_URL;
+    return { upgradeText: raw, upgradeUrl: url };
+  }
+  if (typeof raw === "object") {
+    return {
+      upgradeText: String(raw.message ?? raw.text ?? DEFAULT_UPGRADE_TEXT),
+      upgradeUrl: String(raw.upgrade_url ?? raw.url ?? UPGRADE_URL),
+      resetsAt: typeof raw.resets_at === "string" ? raw.resets_at : null,
+    };
+  }
+  return null;
+}
+
+function renderApiError(status, body, headers, io, style) {
+  const code = body?.error?.code ?? "";
+  const message = body?.error?.message ?? `API error (HTTP ${status})`;
+  const upgrade = upgradeFromBody(body);
+
+  if (status === 401) {
+    if (code === "invalid_key") {
+      io.err(message);
+      io.err(`Check your keys at ${style.cyan(KEYS_URL)} — a revoked key stops working immediately.`);
+    } else {
+      io.err(message);
+      io.err("");
+      io.err("Get a free API key (50 calls/day) in three steps:");
+      io.err(`  1. Create a free account at ${style.cyan("https://usefootnote.com")}`);
+      io.err(`  2. Issue your key at ${style.cyan(KEYS_URL)} (Data API section — the key is shown once)`);
+      io.err("  3. export FOOTNOTE_API_KEY=fn_live_…   (or pass --key fn_live_…)");
+    }
+    return 1;
+  }
+
+  // Hitting a cap is the product working: render the upgrade path, prominently.
+  if ((status === 429 && (code === "daily_cap" || upgrade)) ||
+      (status === 403 && (code === "upgrade_required" || code === "purchase_required"))) {
+    io.err(renderUpgradeBox({
+      message,
+      upgradeText: upgrade?.upgradeText ?? DEFAULT_UPGRADE_TEXT,
+      upgradeUrl: upgrade?.upgradeUrl ?? UPGRADE_URL,
+      resetsAt: upgrade?.resetsAt ?? null,
+    }, style));
+    return 1;
+  }
+
+  if (status === 429) {
+    const retry = headers?.get?.("retry-after");
+    io.err(retry ? `${message} Retry in ${retry}s.` : message);
+    return 1;
+  }
+
+  io.err(`${message}${code ? ` [${code}]` : ""} (HTTP ${status})`);
+  return 1;
+}
+
+/* ---------------------------------- help ---------------------------------- */
+
+export function helpText() {
+  const rows = COMMANDS.map((c) => {
+    const flags = Object.entries(c.flags ?? {})
+      .map(([f, t]) => `[--${f} ${t === "date" ? "YYYY-MM-DD" : t === "state" ? "CA" : t === "text3" ? "TEXT" : "N"}]`)
+      .join(" ");
+    const pos = c.positional ? ` ${c.positional.label}` : "";
+    return [`  footnote ${c.name}${pos}${flags ? ` ${flags}` : ""}`, c.summary];
+  });
+  rows.push(["  footnote get <path> [k=v ...]", "Raw GET against any /api/data/v1 endpoint (current or future)"]);
+  const width = rows.reduce((w, [l]) => Math.max(w, l.length), 0);
+  return [
+    `footnote v${VERSION} — the Footnote Data API from your terminal (${UPGRADE_URL})`,
+    "",
+    "Usage",
+    ...rows.map(([l, s]) => `${l.padEnd(width)}  ${s}`),
+    "",
+    "Options",
+    "  --json           Raw JSON output (also the default when piped)",
+    "  --key <key>      API key (default: $FOOTNOTE_API_KEY)",
+    `  --api-url <url>  API origin (default: $FOOTNOTE_API_URL or ${DEFAULT_API_URL})`,
+    "  --no-color       Disable ANSI colors",
+    "  -h, --help       Show this help",
+    "  -V, --version    Show version",
+    "",
+    "Exit codes: 0 ok · 1 API/network error · 2 usage error",
+    "",
+    `Keys: create a free account at https://usefootnote.com, issue a key at ${KEYS_URL},`,
+    "then: export FOOTNOTE_API_KEY=fn_live_…",
+  ].join("\n");
+}
+
+/* ----------------------------------- run ----------------------------------- */
+
+/**
+ * Runs the CLI. `io` is injectable for tests: { env, isTTY, out, err }.
+ * Network goes through globalThis.fetch so tests can swap it.
+ */
+export async function run(argv, io = {}) {
+  const env = io.env ?? process.env;
+  const isTTY = io.isTTY ?? process.stdout.isTTY ?? false;
+  const out = io.out ?? ((s) => process.stdout.write(`${s}\n`));
+  const err = io.err ?? ((s) => process.stderr.write(`${s}\n`));
+  const ioPair = { out, err };
+
+  const parsed = parseGlobals(argv);
+  if (parsed.usageError) return usageFail(err, parsed.usageError);
+  const { globals, words } = parsed;
+  const style = makeStyle(isTTY && !globals.noColor && !env.NO_COLOR);
+
+  if (globals.version) {
+    out(VERSION);
+    return 0;
+  }
+  if (globals.help || words.length === 0) {
+    if (globals.help) {
+      out(helpText());
+      return 0;
+    }
+    err(helpText());
+    return 2;
+  }
+
+  const command = parseCommand(words);
+  if (command.usageError) return usageFail(err, command.usageError);
+
+  const apiUrl = globals.apiUrl ?? env.FOOTNOTE_API_URL ?? DEFAULT_API_URL;
+  let url;
+  try {
+    url = buildUrl(apiUrl, command.path, command.params);
+  } catch {
+    return usageFail(err, `invalid API url: ${apiUrl}`);
+  }
+
+  const key = globals.key ?? env.FOOTNOTE_API_KEY ?? null;
+  const headers = { accept: "application/json", "user-agent": `footnote-cli/${VERSION}` };
+  if (key) headers.authorization = `Bearer ${key}`;
+
+  let res;
+  try {
+    res = await globalThis.fetch(url, { headers });
+  } catch (cause) {
+    err(`Network error: ${cause?.message ?? cause}`);
+    return 1;
+  }
+
+  const jsonMode = globals.json || !isTTY;
+  const contentType = res.headers?.get?.("content-type") ?? "";
+
+  if (!contentType.includes("application/json")) {
+    // CSV exports and other text bodies pass through untouched.
+    const text = await res.text();
+    if (res.ok) {
+      out(text.endsWith("\n") ? text.slice(0, -1) : text);
+      return 0;
+    }
+    err(`API error (HTTP ${res.status})`);
+    if (text.trim()) err(text.trim());
+    return 1;
+  }
+
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    err(`API error: unparseable JSON body (HTTP ${res.status})`);
+    return 1;
+  }
+
+  if (!res.ok) {
+    if (jsonMode) {
+      out(JSON.stringify(body, null, 2));
+      return 1;
+    }
+    return renderApiError(res.status, body, res.headers, ioPair, style);
+  }
+
+  if (jsonMode) {
+    out(JSON.stringify(body, null, 2));
+    return 0;
+  }
+
+  const data = body?.data;
+  if (Array.isArray(data)) out(renderTable(data, style));
+  else if (data && typeof data === "object") out(renderObject(data, style));
+  else out(JSON.stringify(body, null, 2));
+
+  const metaLines = renderMeta(body?.meta, style);
+  if (metaLines.length) {
+    out("");
+    for (const line of metaLines) out(line);
+  }
+  return 0;
+}
+
+function usageFail(err, message) {
+  err(`Usage error: ${message}`);
+  err("Run `footnote --help` for commands and options.");
+  return 2;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "footnote-data",
+  "version": "0.1.0",
+  "description": "The Footnote Data API from your terminal \u2014 WARN layoff notices, H-1B sponsorship, DOL/OSHA enforcement, severance terms, and wage comparisons from primary public records.",
+  "keywords": [
+    "warn-act",
+    "layoffs",
+    "h1b",
+    "lca",
+    "dol",
+    "osha",
+    "employment-data",
+    "labor-data",
+    "cli",
+    "footnote"
+  ],
+  "homepage": "https://usefootnote.com/data",
+  "bugs": {
+    "email": "hello@usefootnote.com"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "footnote": "bin/footnote.mjs"
+  },
+  "files": [
+    "bin/",
+    "footnote.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}