@fairmint/captable-ai 0.1.3 → 0.1.5

package/README.md

@@ -88,7 +88,7 @@ automated, but a few habits make extraction faster and more accurate:
 | `documents upload\|list\|download\|delete` | Manage source documents |
 | `documents trigger-extraction\|cancel-extraction\|restart-extraction\|reprocess` | Control the OCF extraction pipeline |
 | `documents processing-status\|classification-types\|classification-update` | Inspect document status / classification |
-| `objects list\|get\|update\|patch\|revert\|versions\|delete` | Work with extracted OCF objects |
+| `objects list\|get\|update\|patch\|revert\|versions\|delete` | Work with extracted OCF objects (`list` supports `--document`, `--stakeholder`, `--all`, `--max-confidence`) |
 | `schemas list\|get` | Browse the OCF object-type registry |
 | `commit` | Commit drafts to the cap table — `--all` or `--objects id1,id2` (`--dry-run` to preview) |
 | `summary` | Full cap table snapshot |

package/dist/index.js

@@ -543,7 +543,7 @@ var COMMAND_REGISTRY = [
     name: "objects list",
     group: "captable",
     description: "List OCF objects with filtering and pagination.",
-    usage: "captable-ai objects list [--type TYPE] [--subtype SUBTYPE] [--status STATUS] [--limit N] [--cursor C] [--q QUERY] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--ids IDS] [--json]",
+    usage: "captable-ai objects list [--type TYPE] [--subtype SUBTYPE] [--status STATUS] [--limit N] [--cursor C] [--q QUERY] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--ids IDS] [--stakeholder ID] [--document ID] [--all] [--max-confidence N] [--json]",
     requiresAuth: true,
     requiresPortal: true,
     flags: [
@@ -576,7 +576,27 @@ var COMMAND_REGISTRY = [
         description: "Filter objects with date <= (YYYY-MM-DD, inclusive).",
         type: "string"
       },
-      { name: "ids", description: "Batch fetch by comma-separated IDs.", type: "string" }
+      { name: "ids", description: "Batch fetch by comma-separated IDs.", type: "string" },
+      {
+        name: "stakeholder",
+        description: "Filter by OCF stakeholder id.",
+        type: "string"
+      },
+      {
+        name: "document",
+        description: "Filter by source document s3 asset id.",
+        type: "string"
+      },
+      {
+        name: "all",
+        description: "Follow pagination cursors until every matching object is returned.",
+        type: "boolean"
+      },
+      {
+        name: "max-confidence",
+        description: "Keep objects with extraction confidence <= N. Requires --all.",
+        type: "number"
+      }
     ]
   },
   {
@@ -1127,7 +1147,7 @@ var COMMAND_REGISTRY = [
   }
 ];
 async function runCommands(_args) {
-  printJson({ schemaVersion: "6", version: "0.0.1", commands: COMMAND_REGISTRY });
+  printJson({ schemaVersion: "7", version: "0.0.1", commands: COMMAND_REGISTRY });
 }
 
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
@@ -16486,20 +16506,27 @@ Usage:
   captable-ai objects list [options]
 
 Filters:
-  --type TYPE       Top-level OCF types (comma-separated)
-  --subtype STYPE   TRANSACTION subtypes (comma-separated)
-  --status STATUS   draft | committed
-  --q QUERY         Full-text search
-  --from DATE       YYYY-MM-DD (inclusive lower bound on object date)
-  --to DATE         YYYY-MM-DD (inclusive upper bound on object date)
-  --ids ID,ID,...   Batch fetch by object IDs
+  --type TYPE              Top-level OCF types (comma-separated)
+  --subtype STYPE          TRANSACTION subtypes (comma-separated)
+  --status STATUS          draft | committed
+  --q QUERY                Full-text search
+  --from DATE              YYYY-MM-DD (inclusive lower bound on object date)
+  --to DATE                YYYY-MM-DD (inclusive upper bound on object date)
+  --ids ID,ID,...          Batch fetch by object IDs
+  --stakeholder ID         Filter by OCF stakeholder id
+  --document S3_ASSET_ID   Filter by source document
+  --max-confidence N       Keep objects with confidence <= N (requires --all)
 
 Pagination:
-  --limit N         Page size (1\u2013250; omit for server default, typically 100)
-  --cursor C        Opaque continuation cursor from prior response
+  --limit N                Page size (1\u2013250; omit for server default, typically 100)
+  --cursor C               Opaque continuation cursor from prior response
+  --all                    Follow cursors until every matching object is returned
+
+Human table sorts lowest extraction confidence first. Conf markers:
+  !N  red (<65)    ~N  amber (65\u201384)    N  green (\u226585)
 
 Global:
-  --json            Machine-readable JSON output`;
+  --json                   Machine-readable JSON output (API order, not confidence-sorted)`;
 var HELP_OBJECTS_GET = `objects get \u2014 Show one OCF object
 
 Usage:
@@ -18953,6 +18980,60 @@ Object: ${obj.id}
   printLine();
 }
 
+// src/objects-pages.ts
+var OBJECTS_LIST_MAX_PAGES = 100;
+async function fetchAllObjectPages(portalId, query) {
+  const objects = [];
+  const documentsById = /* @__PURE__ */ new Map();
+  let cursor = typeof query.cursor === "string" ? query.cursor : void 0;
+  let total = 0;
+  let pages = 0;
+  while (true) {
+    pages += 1;
+    if (pages > OBJECTS_LIST_MAX_PAGES) {
+      exitWithError(
+        `Exceeded max object-list pages (${OBJECTS_LIST_MAX_PAGES}). Narrow the query or raise the page size.`,
+        "ERROR",
+        void 0,
+        EXIT.SERVER_ERROR
+      );
+    }
+    const pageQuery = { ...query };
+    if (cursor !== void 0) pageQuery.cursor = cursor;
+    else delete pageQuery.cursor;
+    const res = await apiRequest(`/${portalId}/objects`, { query: pageQuery });
+    const pageObjects = res.data?.objects ?? [];
+    const pageDocs = res.data?.documents ?? [];
+    objects.push(...pageObjects);
+    for (const doc of pageDocs) {
+      documentsById.set(doc.id, doc);
+    }
+    if (res.meta?.total != null) total = res.meta.total;
+    if (!res.meta?.hasMore) break;
+    if (!res.meta.cursor) {
+      exitWithError(
+        "Pagination response has more results but no continuation cursor.",
+        "ERROR",
+        void 0,
+        EXIT.SERVER_ERROR
+      );
+    }
+    if (cursor !== void 0 && res.meta.cursor === cursor) {
+      exitWithError(
+        "Pagination cursor did not advance; stopped draining object pages.",
+        "ERROR",
+        void 0,
+        EXIT.SERVER_ERROR
+      );
+    }
+    cursor = res.meta.cursor;
+  }
+  return {
+    data: { objects, documents: Array.from(documentsById.values()) },
+    meta: { cursor: null, total: total || objects.length, hasMore: false }
+  };
+}
+
 // src/validate.ts
 var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
 function isValidCalendarIsoDate(s) {
@@ -19020,6 +19101,106 @@ function validateIsoDateRange(fromRaw, toRaw) {
 }
 
 // src/commands/objects-list.ts
+var CONFIDENCE_RED_MAX = 64;
+var CONFIDENCE_AMBER_MAX = 84;
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getValidatedMaxConfidence(raw) {
+  if (raw === void 0) return void 0;
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    exitWithError(
+      "--max-confidence must be an integer between 0 and 100",
+      "VALIDATION_FAILED",
+      void 0,
+      EXIT.VALIDATION
+    );
+  }
+  const n = Number.parseInt(trimmed, 10);
+  if (n < 0 || n > 100) {
+    exitWithError(
+      "--max-confidence must be an integer between 0 and 100",
+      "VALIDATION_FAILED",
+      void 0,
+      EXIT.VALIDATION
+    );
+  }
+  return n;
+}
+function objectConfidence(obj) {
+  const n = obj.extraction?.confidence;
+  return typeof n === "number" && Number.isFinite(n) ? n : void 0;
+}
+function formatConfidence(confidence) {
+  if (confidence === void 0) return "\u2014";
+  if (confidence <= CONFIDENCE_RED_MAX) return `!${confidence}`;
+  if (confidence <= CONFIDENCE_AMBER_MAX) return `~${confidence}`;
+  return String(confidence);
+}
+function stakeholderDisplayName(ocf) {
+  if (!ocf) return null;
+  if (typeof ocf.name === "string" && ocf.name.trim()) return ocf.name.trim();
+  if (typeof ocf.legal_name === "string" && ocf.legal_name.trim()) return ocf.legal_name.trim();
+  if (isRecord5(ocf.name)) {
+    const legal = ocf.name.legal_name;
+    if (typeof legal === "string" && legal.trim()) return legal.trim();
+    const parts = [ocf.name.first_name, ocf.name.last_name].filter(
+      (p) => typeof p === "string" && p.trim().length > 0
+    );
+    if (parts.length > 0) return parts.join(" ");
+  }
+  return null;
+}
+function stakeholderNamesById(objects) {
+  const names = /* @__PURE__ */ new Map();
+  for (const obj of objects) {
+    if (obj.type !== "STAKEHOLDER") continue;
+    const name = stakeholderDisplayName(obj.ocf);
+    if (name) names.set(obj.id, name);
+  }
+  return names;
+}
+function compareConfidenceAsc(a, b) {
+  const ca = objectConfidence(a);
+  const cb = objectConfidence(b);
+  if (ca === void 0 && cb === void 0) return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  if (ca === void 0) return 1;
+  if (cb === void 0) return -1;
+  if (ca !== cb) return ca - cb;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function shellQuote3(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function nextPageHint(query, cursor) {
+  const parts = ["captable-ai objects list"];
+  const flagNames = [
+    { queryKey: "type", flag: "type" },
+    { queryKey: "subtype", flag: "subtype" },
+    { queryKey: "status", flag: "status" },
+    { queryKey: "q", flag: "q" },
+    { queryKey: "from", flag: "from" },
+    { queryKey: "to", flag: "to" },
+    { queryKey: "ids", flag: "ids" },
+    { queryKey: "stakeholderId", flag: "stakeholder" },
+    { queryKey: "documentId", flag: "document" },
+    { queryKey: "limit", flag: "limit" }
+  ];
+  for (const { queryKey, flag } of flagNames) {
+    const value = query[queryKey];
+    if (value !== void 0) parts.push(`--${flag} ${shellQuote3(String(value))}`);
+  }
+  parts.push(`--cursor ${shellQuote3(cursor)}`);
+  return parts.join(" ");
+}
+function documentsReferencedBy(documents, objects) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const obj of objects) {
+    if (typeof obj.documentId === "string" && obj.documentId.length > 0) ids.add(obj.documentId);
+  }
+  return documents.filter((doc) => ids.has(doc.id));
+}
 async function runObjectsList(args, rawArgv) {
   if (argvRequestsHelp(rawArgv)) {
     process.stdout.write(`${HELP_OBJECTS_LIST}
@@ -19027,14 +19208,45 @@ async function runObjectsList(args, rawArgv) {
     process.exit(0);
   }
   validateFlags(args, {
-    flags: ["type", "subtype", "status", "limit", "cursor", "q", "from", "to", "ids"],
-    booleans: []
+    flags: [
+      "type",
+      "subtype",
+      "status",
+      "limit",
+      "cursor",
+      "q",
+      "from",
+      "to",
+      "ids",
+      "stakeholder",
+      "document",
+      "max-confidence"
+    ],
+    booleans: ["all"]
   });
+  if (args.positional.length > 0) {
+    exitWithError(
+      `Unexpected argument: ${args.positional[0]}. This command takes no positional arguments.`,
+      "UNEXPECTED_ARGUMENT",
+      void 0,
+      EXIT.USAGE
+    );
+  }
   const portalId = await getActivePortalId();
   const from = getFlagValue(args, "from");
   const to = getFlagValue(args, "to");
   validateIsoDateRange(from, to);
   const limit = getValidatedLimit(getFlagValue(args, "limit"));
+  const drainAll = hasFlag(args, "all");
+  const maxConfidence = getValidatedMaxConfidence(getFlagValue(args, "max-confidence"));
+  if (maxConfidence !== void 0 && !drainAll) {
+    exitWithError(
+      "--max-confidence requires --all so the review queue is not a single page.",
+      "VALIDATION_FAILED",
+      void 0,
+      EXIT.VALIDATION
+    );
+  }
   const type = getFlagValue(args, "type");
   const subtype = getFlagValue(args, "subtype");
   const status = getFlagValue(args, "status");
@@ -19049,6 +19261,8 @@ async function runObjectsList(args, rawArgv) {
   const q = getFlagValue(args, "q");
   const cursor = getFlagValue(args, "cursor");
   const ids = getFlagValue(args, "ids");
+  const stakeholderId = getFlagValue(args, "stakeholder");
+  const documentId = getFlagValue(args, "document");
   const query = {
     type,
     subtype,
@@ -19058,51 +19272,75 @@ async function runObjectsList(args, rawArgv) {
     cursor,
     from,
     to,
-    ids
+    ids,
+    stakeholderId,
+    documentId
   };
-  const res = await apiRequest(`/${portalId}/objects`, { query });
+  let page;
+  if (drainAll) {
+    page = await fetchAllObjectPages(portalId, query);
+  } else {
+    const res = await apiRequest(`/${portalId}/objects`, { query });
+    page = {
+      data: { objects: res.data?.objects ?? [], documents: res.data?.documents ?? [] },
+      meta: res.meta ?? {}
+    };
+  }
+  let objects = page.data.objects;
+  let documents = page.data.documents;
+  if (maxConfidence !== void 0) {
+    objects = objects.filter((obj) => {
+      const confidence = objectConfidence(obj);
+      return confidence !== void 0 && confidence <= maxConfidence;
+    });
+    documents = documentsReferencedBy(documents, objects);
+  }
   if (isJsonMode()) {
-    const out = { data: res.data };
-    if (res.meta !== void 0) out.meta = res.meta;
+    const out = {
+      data: { objects, documents }
+    };
+    if (page.meta !== void 0) {
+      out.meta = maxConfidence !== void 0 ? { ...page.meta, total: objects.length, hasMore: false, cursor: null } : page.meta;
+    }
     printJson(out);
     return;
   }
-  const objects = res.data?.objects ?? [];
-  const meta3 = res.meta;
+  const documentsById = new Map(documents.map((d) => [d.id, d.name]));
+  const namesByStakeholderId = stakeholderNamesById(page.data.objects);
+  const sorted = [...objects].sort(compareConfidenceAsc);
+  const meta3 = page.meta;
+  const totalLabel = maxConfidence !== void 0 ? ` (${objects.length} matching)` : meta3?.total != null && objects.length !== meta3.total ? ` (${objects.length} shown, ${meta3.total} total)` : meta3?.total != null ? ` (${meta3.total} total)` : "";
   printLine(`
-Objects${meta3?.total != null ? ` (${meta3.total} total)` : ""}:
+Objects${totalLabel}:
 `);
   printTable(
-    objects.map((o) => ({
-      id: o.id,
-      type: o.subtype ?? o.type,
-      status: o.status,
-      date: o.date ?? "",
-      version: o.version
-    })),
+    sorted.map((o) => {
+      const stakeholderIdValue = o.type === "STAKEHOLDER" ? o.id : o.stakeholderId ?? "";
+      const stakeholderName = stakeholderIdValue ? namesByStakeholderId.get(stakeholderIdValue) ?? stakeholderIdValue : "";
+      return {
+        id: o.id,
+        type: o.subtype ?? o.type,
+        status: o.status,
+        conf: formatConfidence(objectConfidence(o)),
+        document: o.documentId ? documentsById.get(o.documentId) ?? o.documentId : "",
+        stakeholder: stakeholderName,
+        date: o.date ?? ""
+      };
+    }),
     [
       { key: "id", label: "ID", width: 38 },
-      { key: "type", label: "Type", width: 30 },
+      { key: "type", label: "Type", width: 28 },
       { key: "status", label: "Status", width: 10 },
-      { key: "date", label: "Date", width: 12 },
-      { key: "version", label: "Version", width: 8 }
+      { key: "conf", label: "Conf", width: 6 },
+      { key: "document", label: "Document", width: 24 },
+      { key: "stakeholder", label: "Stakeholder", width: 22 },
+      { key: "date", label: "Date", width: 12 }
     ]
   );
-  if (meta3?.hasMore && meta3.cursor) {
-    const shQ = (v) => `'${v.replace(/'/g, `'\\''`)}'`;
-    const parts = ["captable-ai objects list"];
-    if (type !== void 0) parts.push(`--type ${shQ(type)}`);
-    if (subtype !== void 0) parts.push(`--subtype ${shQ(subtype)}`);
-    if (status !== void 0) parts.push(`--status ${shQ(status)}`);
-    if (q !== void 0) parts.push(`--q ${shQ(q)}`);
-    if (from !== void 0) parts.push(`--from ${shQ(from)}`);
-    if (to !== void 0) parts.push(`--to ${shQ(to)}`);
-    if (ids !== void 0) parts.push(`--ids ${shQ(ids)}`);
-    if (limit !== void 0) parts.push(`--limit ${shQ(String(limit))}`);
-    parts.push(`--cursor ${shQ(meta3.cursor)}`);
+  if (!drainAll && meta3?.hasMore && meta3.cursor) {
     printLine(`
 More results available. Next page:
-  ${parts.join(" ")}`);
+  ${nextPageHint(query, meta3.cursor)}`);
   }
   printLine();
 }
@@ -19116,7 +19354,7 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function parsePatchPayload(raw) {
@@ -19131,7 +19369,7 @@ function parsePatchPayload(raw) {
       EXIT.VALIDATION
     );
   }
-  if (!isRecord5(parsed)) {
+  if (!isRecord6(parsed)) {
     exitWithError(
       "OCF patch payload must be a JSON object.",
       "VALIDATION_FAILED",
@@ -19351,7 +19589,7 @@ async function readStdin2() {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
-function isRecord6(value) {
+function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function parseOcfPayload(raw) {
@@ -19366,7 +19604,7 @@ function parseOcfPayload(raw) {
       EXIT.VALIDATION
     );
   }
-  if (!isRecord6(parsed)) {
+  if (!isRecord7(parsed)) {
     exitWithError(
       "OCF payload must be a JSON object.",
       "VALIDATION_FAILED",
@@ -19376,7 +19614,7 @@ function parseOcfPayload(raw) {
   }
   return parsed;
 }
-function shellQuote3(value) {
+function shellQuote4(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 async function runObjectsUpdate(args, rawArgv) {
@@ -19501,7 +19739,7 @@ Updated object: ${obj.id}
     printKeyValue([["Key", obj.schemaKey]]);
     printLine(
       `
-  Run: captable-ai schemas get ${shellQuote3(obj.schemaKey)} to view the exact schema.`
+  Run: captable-ai schemas get ${shellQuote4(obj.schemaKey)} to view the exact schema.`
     );
   }
   printLine();
@@ -19735,20 +19973,20 @@ import { homedir as homedir4 } from "os";
 import { join as join4 } from "path";
 var CONFIG_DIR4 = join4(homedir4(), ".captable-ai");
 var PROFILES_FILE = join4(CONFIG_DIR4, "profiles.json");
-function isRecord7(value) {
+function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isErrno3(err, code) {
-  return isRecord7(err) && err.code === code;
+  return isRecord8(err) && err.code === code;
 }
 function parseProfiles(raw) {
   const parsed = JSON.parse(raw);
-  if (!isRecord7(parsed) || !isRecord7(parsed.profiles)) {
+  if (!isRecord8(parsed) || !isRecord8(parsed.profiles)) {
     throw new Error("profiles.json must contain a profiles object.");
   }
   const profiles = {};
   for (const [name, value] of Object.entries(parsed.profiles)) {
-    if (!isRecord7(value) || typeof value.company !== "string" || !value.company.trim()) {
+    if (!isRecord8(value) || typeof value.company !== "string" || !value.company.trim()) {
       throw new Error(`Profile "${name}" must include a non-empty company string.`);
     }
     const stage = typeof value.stage === "string" && value.stage.trim() ? value.stage : void 0;
@@ -20429,7 +20667,8 @@ Cap Table (read):
                              Options: --as-of, --include-pending, --skip-stakeholders, --page
   objects list              List OCF objects
                              Filters: --type, --subtype, --status, --q, --from, --to, --ids
-                             Pagination: --limit (1-250), --cursor
+                             Review: --stakeholder, --document, --max-confidence N (requires --all)
+                             Pagination: --limit (1-250), --cursor, --all
                              Dates: --from / --to as YYYY-MM-DD
   objects get <id>          Show a single OCF object
   schemas list              List OCF object types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairmint/captable-ai",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Agent-native CLI for Captable AI — manage companies, upload documents, run OCF extraction, and commit cap tables from the terminal.",
   "keywords": [
     "captable",