footnote-data 0.1.1 → 0.2.0

package/README.md

@@ -2,10 +2,16 @@
 
 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.
+Hour and OSHA enforcement, DOL debarment, H-2 seasonal-labor and PERM green-card
+certifications, ICE SEVP OPT/STEM-OPT top employers, federal litigation posture,
+and severance terms parsed from SEC filings. Counts are measured, matches are
+exact-or-absent, and absence of evidence is always distinguished from evidence
+of absence.
+
+Free keys get trust/posture answers (WARN, H-1B, debarment). The
+volume/series datasets — H-2, PERM, OPT — are **Data Pro**; a free key hitting
+them gets a `403 upgrade_required` that names the dataset and the way up, never
+a silent 404. `footnote datasets` lists every holding with its `access` tier.
 
 Zero runtime dependencies. Node 18+. Docs and pricing: <https://usefootnote.com/data>.
 
@@ -124,6 +130,52 @@ footnote litigation "Example Corp"
 footnote severance "Example Corp"
 ```
 
+### Work authorization & debarment
+
+```bash
+# DOL debarment status — free tier: current / lapsed / none + program labels
+footnote debarment "Example Staffing LLC"
+
+# H-2A/H-2B seasonal-labor certifications for an employer (Data Pro)
+footnote h2 "Example Farms" --program h2a --fy 2026
+
+# National H-2 KPIs + the USCIS approved-worker trend (Data Pro)
+footnote h2 summary
+
+# PERM green-card certification decision counts (Data Pro)
+footnote perm "Example Corp" --fy 2026
+
+# ICE SEVP Top-200 OPT / STEM-OPT employers, ranked (Data Pro)
+footnote opt-top --fy 2024 --limit 25
+```
+
+```text
+$ footnote debarment "Example Staffing LLC"
+employer_query   example staffing
+matched          true
+status           current
+programs         OFLC H-2A
+
+tier: free
+match: exact normalized legal name + registered spelling variants (never fuzzy); …
+interpretation: status is derived at read time — 'current' = a debarment in force today …
+▲ upgrade: Full debarment history — dates, entity spelling, willful flag, and violation text — is on Data Pro
+```
+
+Honesty rails these commands keep, straight from the record:
+
+- **debarment** — a no-match is *not* a clean bill (it means no exact-legal-name
+  entry on the DOL list); `status` is derived at read time, never stored.
+- **h2** — wages are RAW rates with their unit, **never annualized** (seasonal
+  work); worker counts are OFLC application workers, not visas issued.
+- **h2 summary** — OFLC certification (intent) and USCIS approvals (outcome) are
+  different pipeline stages and are **never** divided into a conversion rate.
+- **perm** — a PERM certification is DOL's *step one* of green-card sponsorship,
+  not a green card; there is **no prevailing-wage field**.
+- **opt-top** — `opt_or_stem_opt_students` is the source's own combined count and
+  is **not** `opt_students + stem_opt_students` (a student in both programs is
+  counted once per program); these are students, not employees.
+
 ### Dataset provenance
 
 ```bash
@@ -234,5 +286,10 @@ that apply to that call.
 | `osha` | `GET /api/data/v1/osha/employer` |
 | `severance` | `GET /api/data/v1/severance/employer` |
 | `wage-comparison` | `GET /api/data/v1/wage-comparison/employer` |
+| `debarment` | `GET /api/data/v1/debarment` |
+| `h2` | `GET /api/data/v1/h2/employers` |
+| `h2 summary` | `GET /api/data/v1/h2/summary` |
+| `perm` | `GET /api/data/v1/perm/employers` |
+| `opt-top` | `GET /api/data/v1/opt/top-employers` |
 | `datasets` | `GET /api/data/v1/datasets` |
 | `get <path>` | `GET <any /api/data/v1 path>` |

package/footnote.mjs

@@ -6,7 +6,7 @@
  * params, read from the source, never guessed.
  */
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";
 export const DEFAULT_API_URL = "https://usefootnote.com";
 
 const UPGRADE_URL = "https://usefootnote.com/data";
@@ -38,6 +38,8 @@ const VALIDATORS = {
   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" },
+  program: { ok: (v) => /^h2[ab]$/i.test(v), hint: "h2a or h2b", map: (v) => v.toLowerCase() },
+  year: { ok: (v) => /^\d{4}$/.test(v), hint: "a 4-digit year (e.g. 2024)" },
 };
 
 /**
@@ -122,6 +124,45 @@ export const COMMANDS = [
     summary: "Advertised (posting) vs DOL-attested (LCA) wages",
     positional: { param: "name", label: "<employer>", min: 2 },
   },
+  {
+    name: "debarment",
+    path: "/api/data/v1/debarment",
+    route: "app/api/data/v1/debarment/route.ts",
+    summary: "DOL debarment status: current / lapsed / none (free tier)",
+    positional: { param: "employer", label: "<employer>", min: 2 },
+  },
+  {
+    // Two-word "h2 summary" is matched before the one-word "h2" employer lookup
+    // (findCommand tries the 2-word join first), so both resolve unambiguously.
+    name: "h2 summary",
+    path: "/api/data/v1/h2/summary",
+    route: "app/api/data/v1/h2/summary/route.ts",
+    summary: "National H-2A/H-2B KPIs + USCIS worker trend (Data Pro)",
+    flags: {},
+  },
+  {
+    name: "h2",
+    path: "/api/data/v1/h2/employers",
+    route: "app/api/data/v1/h2/employers/route.ts",
+    summary: "H-2A/H-2B certifications for an employer (Data Pro)",
+    positional: { param: "name", label: "<employer>", min: 2 },
+    flags: { program: "program", fy: "year" },
+  },
+  {
+    name: "perm",
+    path: "/api/data/v1/perm/employers",
+    route: "app/api/data/v1/perm/employers/route.ts",
+    summary: "PERM green-card decision counts for an employer (Data Pro)",
+    positional: { param: "name", label: "<employer>", min: 2 },
+    flags: { fy: "year" },
+  },
+  {
+    name: "opt-top",
+    path: "/api/data/v1/opt/top-employers",
+    route: "app/api/data/v1/opt/top-employers/route.ts",
+    summary: "SEVP Top-200 OPT/STEM-OPT employers, ranked (Data Pro)",
+    flags: { fy: "year", limit: "posInt" },
+  },
   {
     name: "datasets",
     path: "/api/data/v1/datasets",
@@ -397,8 +438,10 @@ function renderApiError(status, body, headers, io, style) {
 
 export function helpText() {
   const rows = COMMANDS.map((c) => {
+    const flagLabel = (t) =>
+      t === "date" ? "YYYY-MM-DD" : t === "state" ? "CA" : t === "text3" ? "TEXT" : t === "program" ? "h2a|h2b" : t === "year" ? "YYYY" : "N";
     const flags = Object.entries(c.flags ?? {})
-      .map(([f, t]) => `[--${f} ${t === "date" ? "YYYY-MM-DD" : t === "state" ? "CA" : t === "text3" ? "TEXT" : "N"}]`)
+      .map(([f, t]) => `[--${f} ${flagLabel(t)}]`)
       .join(" ");
     const pos = c.positional ? ` ${c.positional.label}` : "";
     return [`  footnote ${c.name}${pos}${flags ? ` ${flags}` : ""}`, c.summary];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "footnote-data",
-  "version": "0.1.1",
-  "description": "The official Footnote CLI \u2014 career intelligence from the public record: WARN layoffs, H-1B & green-card sponsorship, certified wages, and federal enforcement, straight from usefootnote.com's Data API.",
+  "version": "0.2.0",
+  "description": "The official Footnote CLI \u2014 career intelligence from the public record: WARN layoffs, H-1B & green-card sponsorship, H-2 seasonal labor, PERM, OPT, DOL debarment, certified wages, and federal enforcement, straight from usefootnote.com's Data API.",
   "keywords": [
     "layoffs",
     "warn-act",