@fairmint/captable-ai 0.1.40 → 0.1.41

package/README.md

@@ -94,6 +94,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 |
+| `agreements list\|download` | Signed investment and grant agreements, one-hour download links |
 | `objects list\|get\|dump\|update\|patch\|revert\|versions\|delete` | Work with extracted OCF objects (`list` supports `--document`, `--stakeholder`, `--all`, `--max-confidence`; `dump` writes engine-shaped `ocf.json`) |
 | `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) |
@@ -111,6 +112,26 @@ automated, but a few habits make extraction faster and more accurate:
 Run `captable-ai <command> --help` for full usage, or `captable-ai commands --json` for the
 authoritative machine-readable list.
 
+## Signed agreements
+
+`documents list` holds what the extraction pipeline ingested. Signed agreements are
+listed separately, whether or not they were ingested:
+
+```bash
+captable-ai agreements list                      # investments and grants, newest signed first
+captable-ai agreements list --type grant --json
+captable-ai agreements download grant:<awardId>  # one-hour download link
+```
+
+- **Investments** — the signed file of a SAFE (Send One SAFE, Community SAFE), custom
+  document, or legacy investment, once signed, whether or not payment is marked.
+- **Grants** — Send One Grants both parties signed. The download is the agreement,
+  supporting documents, and both signature certificates. The grantee's tax form and
+  83(b) election are never included; download those from Studio.
+
+Legacy grant agreements imported through the extraction pipeline stay under
+`documents list` / `documents download`.
+
 ## Instrument registers
 
 `captable-ai export` with no register is the full legal cap table: a multi-sheet Excel

package/dist/index.js

@@ -17013,6 +17013,37 @@ var securityholderFileResultSchema = external_exports.object({
   s3Key: external_exports.string().describe("S3 object key.")
 });
 
+// ../captable-ai-core/dist/signed-agreements.js
+var SIGNED_AGREEMENT_TYPES = ["investment", "grant"];
+var UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+function isSignedAgreementType(value) {
+  return value === "investment" || value === "grant";
+}
+var SIGNED_AGREEMENT_REF_PATTERN = new RegExp(`^(investment|grant):(${UUID})$`, "i");
+function parseSignedAgreementRef(ref) {
+  const match = SIGNED_AGREEMENT_REF_PATTERN.exec(ref.trim());
+  const type = match?.[1]?.toLowerCase();
+  const id = match?.[2]?.toLowerCase();
+  if (!type || !id || !isSignedAgreementType(type))
+    return null;
+  return { type, id };
+}
+var signedAgreementSchema = external_exports.object({
+  ref: external_exports.string().describe("Pass to `agreements download`: investment:<s3AssetId> or grant:<awardId>."),
+  type: external_exports.enum(SIGNED_AGREEMENT_TYPES).describe("investment or grant."),
+  name: external_exports.string().describe("File name."),
+  holder_name: external_exports.string().nullable().describe("Investor or grantee."),
+  holder_email: external_exports.string().nullable().describe("Investor or grantee email."),
+  offering: external_exports.string().nullable().describe("Series or fundraising title (investments); instrument (grants)."),
+  status: external_exports.string().describe("Investment or award workflow status."),
+  signed_on: external_exports.string().nullable().describe("Date the agreement was fully signed (YYYY-MM-DD)."),
+  investment_id: external_exports.string().nullable().describe("investment.id, for investment agreements."),
+  equity_award_id: external_exports.string().nullable().describe("equity_award.id, for grants.")
+});
+var signedAgreementListResultSchema = external_exports.object({
+  items: external_exports.array(signedAgreementSchema).describe("Newest signed first.")
+});
+
 // ../captable-ai-core/dist/snapshot.js
 var statusErrorSchema = external_exports.object({ message: external_exports.string() });
 var statusWarningSchema = external_exports.object({
@@ -17738,6 +17769,223 @@ async function handleResponse(res, softFail = false) {
   return parsed;
 }
 
+// src/flags.ts
+function looksLikeFlag(value) {
+  if (!value.startsWith("-")) return false;
+  if (value === "-" || /^-\d+(?:\.\d+)?$/.test(value)) return false;
+  return true;
+}
+function parseArgs(argv) {
+  const positional = [];
+  const positionalIndexes = [];
+  const flags = {};
+  const flagValueSources = {};
+  const flagValueIndexes = {};
+  const boolean4 = /* @__PURE__ */ new Set();
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx !== -1) {
+        const key = arg.slice(2, eqIdx);
+        flags[key] = arg.slice(eqIdx + 1);
+        flagValueSources[key] = "equals";
+        flagValueIndexes[key] = i;
+      } else {
+        const key = arg.slice(2);
+        const next = argv[i + 1];
+        if (next !== void 0 && !looksLikeFlag(next)) {
+          flags[key] = next;
+          flagValueSources[key] = "next";
+          flagValueIndexes[key] = i + 1;
+          i++;
+        } else {
+          boolean4.add(key);
+        }
+      }
+    } else {
+      positional.push(arg);
+      positionalIndexes.push(i);
+    }
+    i++;
+  }
+  return { positional, positionalIndexes, flags, flagValueSources, flagValueIndexes, boolean: boolean4 };
+}
+function hasFlag(args, name) {
+  return args.boolean.has(name) || name in args.flags;
+}
+function getFlagValue(args, name) {
+  return args.flags[name];
+}
+function argvRequestsHelp(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) return true;
+  return argv[0] === "help";
+}
+
+// src/validate-flags.ts
+function restorePositional(args, value, originalIndex) {
+  const insertAt = args.positionalIndexes.findIndex((index) => index > originalIndex);
+  if (insertAt === -1) {
+    args.positional.push(value);
+    args.positionalIndexes.push(originalIndex);
+    return;
+  }
+  args.positional.splice(insertAt, 0, value);
+  args.positionalIndexes.splice(insertAt, 0, originalIndex);
+}
+function validateFlags(args, allowed) {
+  const valueFlags = new Set(allowed.flags ?? []);
+  const booleanFlags = new Set(allowed.booleans ?? []);
+  const allAllowed = /* @__PURE__ */ new Set([...valueFlags, ...booleanFlags]);
+  const allList = [...allAllowed].map((f) => `--${f}`).join(", ");
+  for (const key of Object.keys(args.flags)) {
+    if (!allAllowed.has(key)) {
+      exitWithError(
+        `Unknown flag: --${key}. Allowed flags: ${allList || "(none)"}`,
+        "UNKNOWN_FLAG",
+        void 0,
+        EXIT.USAGE
+      );
+    }
+    if (booleanFlags.has(key) && !valueFlags.has(key) && args.flagValueSources[key] === "next") {
+      args.boolean.add(key);
+      restorePositional(args, args.flags[key], args.flagValueIndexes[key]);
+      delete args.flags[key];
+      delete args.flagValueSources[key];
+      delete args.flagValueIndexes[key];
+      continue;
+    }
+    if (booleanFlags.has(key) && !valueFlags.has(key)) {
+      exitWithError(
+        `Flag --${key} does not take a value.`,
+        "UNEXPECTED_FLAG_VALUE",
+        void 0,
+        EXIT.USAGE
+      );
+    }
+  }
+  for (const key of args.boolean) {
+    if (valueFlags.has(key)) {
+      exitWithError(`Flag --${key} requires a value.`, "MISSING_FLAG_VALUE", void 0, EXIT.USAGE);
+    }
+    if (!booleanFlags.has(key)) {
+      exitWithError(
+        `Unknown flag: --${key}. Allowed flags: ${allList || "(none)"}`,
+        "UNKNOWN_FLAG",
+        void 0,
+        EXIT.USAGE
+      );
+    }
+  }
+}
+
+// src/commands/agreements.ts
+var LIST_USAGE = "Usage: captable-ai agreements list [--type investment|grant] [--json]";
+var DOWNLOAD_USAGE = "Usage: captable-ai agreements download <ref> [--json]";
+async function runAgreementsList(args, rawArgv) {
+  if (argvRequestsHelp(rawArgv)) {
+    process.stdout.write(
+      `agreements list \u2014 List signed investment and grant agreements
+
+${LIST_USAGE}
+
+Investment agreements (SAFE, custom document, legacy) are listed once signed, paid or not.
+Grants are Send One Grants both parties signed. Pass a row's ref to \`agreements download\`.
+`
+    );
+    process.exit(0);
+  }
+  validateFlags(args, { flags: ["type"], booleans: [] });
+  const type = getFlagValue(args, "type");
+  if (type && !isSignedAgreementType(type)) {
+    exitWithError(
+      `--type must be one of: ${SIGNED_AGREEMENT_TYPES.join(", ")} (got: "${type}")`,
+      "VALIDATION_FAILED",
+      void 0,
+      EXIT.VALIDATION
+    );
+  }
+  const portalId = await getActivePortalId();
+  const res = await apiRequest(`/${portalId}/agreements`);
+  const items = (res.data?.items ?? []).filter((item) => !type || item.type === type);
+  if (isJsonMode()) {
+    printJson({ data: { items } });
+    return;
+  }
+  if (items.length === 0) {
+    printLine("No signed agreements found.");
+    return;
+  }
+  printLine(`
+${items.length} signed agreement(s):
+`);
+  printTable(
+    items.map((item) => ({
+      holder: item.holder_name ?? "\u2014",
+      type: item.type,
+      offering: item.offering ?? "\u2014",
+      status: item.status,
+      signed: item.signed_on ?? "\u2014",
+      ref: item.ref
+    })),
+    [
+      { key: "holder", label: "Holder", width: 26 },
+      { key: "type", label: "Type", width: 10 },
+      { key: "offering", label: "Offering", width: 22 },
+      { key: "status", label: "Status", width: 14 },
+      { key: "signed", label: "Signed", width: 12 },
+      { key: "ref", label: "Ref" }
+    ]
+  );
+  printLine("\n  Download one: captable-ai agreements download <ref>\n");
+}
+async function runAgreementsDownload(args, rawArgv) {
+  if (argvRequestsHelp(rawArgv)) {
+    process.stdout.write(
+      `agreements download \u2014 Get a one-hour download URL for a signed agreement
+
+${DOWNLOAD_USAGE}
+
+ref is from \`agreements list\`: investment:<s3AssetId> or grant:<awardId>.
+A grant downloads as the agreement plus signature certificates; tax forms and
+83(b) elections are not included (download those from Studio).
+`
+    );
+    process.exit(0);
+  }
+  validateFlags(args, { flags: [], booleans: [] });
+  if (args.positional.length !== 1) {
+    exitWithUsage("Expected exactly one agreement ref.", DOWNLOAD_USAGE);
+  }
+  const ref = args.positional[0].trim();
+  if (!parseSignedAgreementRef(ref)) {
+    exitWithUsage(
+      `Invalid ref "${ref}". Expected investment:<s3AssetId> or grant:<awardId> from \`agreements list\`.`,
+      DOWNLOAD_USAGE
+    );
+  }
+  const portalId = await getActivePortalId();
+  const res = await apiRequest(
+    `/${portalId}/agreements/${encodeURIComponent(ref)}/download`
+  );
+  if (isJsonMode()) {
+    printJson({ data: res.data });
+    return;
+  }
+  const d = res.data;
+  if (!d?.downloadUrl || !d.filename || !d.expiresAt) {
+    exitWithError("Download URL generation failed.", "ERROR", void 0, EXIT.SERVER_ERROR);
+  }
+  printLine("\n  Agreement download URL generated.\n");
+  printKeyValue([
+    ["Download URL", d.downloadUrl],
+    ["Filename", d.filename],
+    ["Expires at", d.expiresAt]
+  ]);
+  printLine();
+}
+
 // src/auth/refresh-portals.ts
 var PORTALS_TTL_MS = 3e5;
 var REQUEST_TIMEOUT_MS2 = 1e4;
@@ -17809,63 +18057,6 @@ async function refreshCachedPortalNames() {
   }
 }
 
-// src/validate-flags.ts
-function restorePositional(args, value, originalIndex) {
-  const insertAt = args.positionalIndexes.findIndex((index) => index > originalIndex);
-  if (insertAt === -1) {
-    args.positional.push(value);
-    args.positionalIndexes.push(originalIndex);
-    return;
-  }
-  args.positional.splice(insertAt, 0, value);
-  args.positionalIndexes.splice(insertAt, 0, originalIndex);
-}
-function validateFlags(args, allowed) {
-  const valueFlags = new Set(allowed.flags ?? []);
-  const booleanFlags = new Set(allowed.booleans ?? []);
-  const allAllowed = /* @__PURE__ */ new Set([...valueFlags, ...booleanFlags]);
-  const allList = [...allAllowed].map((f) => `--${f}`).join(", ");
-  for (const key of Object.keys(args.flags)) {
-    if (!allAllowed.has(key)) {
-      exitWithError(
-        `Unknown flag: --${key}. Allowed flags: ${allList || "(none)"}`,
-        "UNKNOWN_FLAG",
-        void 0,
-        EXIT.USAGE
-      );
-    }
-    if (booleanFlags.has(key) && !valueFlags.has(key) && args.flagValueSources[key] === "next") {
-      args.boolean.add(key);
-      restorePositional(args, args.flags[key], args.flagValueIndexes[key]);
-      delete args.flags[key];
-      delete args.flagValueSources[key];
-      delete args.flagValueIndexes[key];
-      continue;
-    }
-    if (booleanFlags.has(key) && !valueFlags.has(key)) {
-      exitWithError(
-        `Flag --${key} does not take a value.`,
-        "UNEXPECTED_FLAG_VALUE",
-        void 0,
-        EXIT.USAGE
-      );
-    }
-  }
-  for (const key of args.boolean) {
-    if (valueFlags.has(key)) {
-      exitWithError(`Flag --${key} requires a value.`, "MISSING_FLAG_VALUE", void 0, EXIT.USAGE);
-    }
-    if (!booleanFlags.has(key)) {
-      exitWithError(
-        `Unknown flag: --${key}. Allowed flags: ${allList || "(none)"}`,
-        "UNKNOWN_FLAG",
-        void 0,
-        EXIT.USAGE
-      );
-    }
-  }
-}
-
 // src/commands/auth-status.ts
 async function runAuthStatus(args) {
   validateFlags(args, { flags: [], booleans: [] });
@@ -17913,62 +18104,6 @@ async function runAuthStatus(args) {
 
 // src/commands/export.ts
 import { renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
-
-// src/flags.ts
-function looksLikeFlag(value) {
-  if (!value.startsWith("-")) return false;
-  if (value === "-" || /^-\d+(?:\.\d+)?$/.test(value)) return false;
-  return true;
-}
-function parseArgs(argv) {
-  const positional = [];
-  const positionalIndexes = [];
-  const flags = {};
-  const flagValueSources = {};
-  const flagValueIndexes = {};
-  const boolean4 = /* @__PURE__ */ new Set();
-  let i = 0;
-  while (i < argv.length) {
-    const arg = argv[i];
-    if (arg.startsWith("--")) {
-      const eqIdx = arg.indexOf("=");
-      if (eqIdx !== -1) {
-        const key = arg.slice(2, eqIdx);
-        flags[key] = arg.slice(eqIdx + 1);
-        flagValueSources[key] = "equals";
-        flagValueIndexes[key] = i;
-      } else {
-        const key = arg.slice(2);
-        const next = argv[i + 1];
-        if (next !== void 0 && !looksLikeFlag(next)) {
-          flags[key] = next;
-          flagValueSources[key] = "next";
-          flagValueIndexes[key] = i + 1;
-          i++;
-        } else {
-          boolean4.add(key);
-        }
-      }
-    } else {
-      positional.push(arg);
-      positionalIndexes.push(i);
-    }
-    i++;
-  }
-  return { positional, positionalIndexes, flags, flagValueSources, flagValueIndexes, boolean: boolean4 };
-}
-function hasFlag(args, name) {
-  return args.boolean.has(name) || name in args.flags;
-}
-function getFlagValue(args, name) {
-  return args.flags[name];
-}
-function argvRequestsHelp(argv) {
-  if (argv.includes("--help") || argv.includes("-h")) return true;
-  return argv[0] === "help";
-}
-
-// src/commands/export.ts
 var EXPORT_USAGE = "captable-ai export [--as-of YYYY-MM-DD] [--show-empty-fields] [--json]";
 var EXPORT_REGISTER_USAGE = "captable-ai export <stock|grants|warrants|convertibles> [--include-pending] [--as-of YYYY-MM-DD] [--csv | --json] [--output <path>]";
 var EXPORT_CONVERTIBLES_USAGE = "captable-ai export convertibles [--type SAFE|NOTE] [--include-pending] [--as-of YYYY-MM-DD] [--csv | --json] [--output <path>]";
@@ -18807,6 +18942,30 @@ var COMMAND_REGISTRY = [
     requiresAuth: true,
     requiresPortal: true
   },
+  {
+    name: "agreements list",
+    group: "captable",
+    description: "List signed agreements: investment agreements (SAFE, custom document, legacy) once signed, paid or not, and Send One Grants both parties signed. Each row has a ref for `agreements download`.",
+    usage: "captable-ai agreements list [--type investment|grant] [--json]",
+    requiresAuth: true,
+    requiresPortal: true,
+    flags: [
+      {
+        name: "type",
+        description: "Only investment or grant agreements.",
+        type: "string",
+        enum: ["investment", "grant"]
+      }
+    ]
+  },
+  {
+    name: "agreements download",
+    group: "captable",
+    description: "Get a one-hour download URL for a signed agreement by its ref (investment:<s3AssetId> or grant:<awardId>). A grant downloads as the agreement plus signature certificates, without tax forms or 83(b) elections.",
+    usage: "captable-ai agreements download <ref> [--json]",
+    requiresAuth: true,
+    requiresPortal: true
+  },
   {
     name: "documents trigger-extraction",
     group: "captable",
@@ -24281,6 +24440,7 @@ var VERSION = (() => {
   return "0.0.0";
 })();
 var PROFILE_AWARE_COMMANDS = /* @__PURE__ */ new Set([
+  "agreements",
   "commit",
   "company",
   "documents",
@@ -24372,6 +24532,12 @@ Documents:
   documents delete <id>     Delete an uploaded document and all associated artifacts
   documents download <id>   Get a presigned download URL for a document
 
+Signed Agreements:
+  agreements list           List signed investment and grant agreements
+                             Filter: --type investment|grant
+  agreements download <ref> Get a one-hour download URL for one agreement
+                             Grants: agreement + signature certificates, no tax forms
+
 Agent Logs (Fairmint super-admin only):
   logs list             List OCF agent log entries (expert/validator runs)
                          Options: --agent-type expert|validator, --limit N, --cursor C
@@ -24850,6 +25016,32 @@ async function main() {
             );
         }
         break;
+      case "agreements":
+        if (isHelpToken(sub)) {
+          process.stdout.write(
+            "agreements \u2014 List and download signed investment and grant agreements\n\nSubcommands: list, download\nRun: captable-ai agreements <subcommand> --help\n"
+          );
+          process.exit(0);
+        }
+        switch (sub) {
+          case "list":
+            await runAgreementsList(parseArgs(positionalArgs.slice(2)), positionalArgs.slice(2));
+            break;
+          case "download":
+            await runAgreementsDownload(
+              parseArgs(positionalArgs.slice(2)),
+              positionalArgs.slice(2)
+            );
+            break;
+          default:
+            exitWithError(
+              `Unknown agreements command: ${sub ?? "(none)"}. Try: agreements list | download`,
+              "UNKNOWN_COMMAND",
+              void 0,
+              EXIT.USAGE
+            );
+        }
+        break;
       case "logs":
         if (isHelpToken(sub)) {
           process.stdout.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairmint/captable-ai",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "description": "Agent-native CLI for Captable AI — manage companies, upload documents, run OCF extraction, and commit cap tables from the terminal.",
   "keywords": [
     "captable",
@@ -27,12 +27,10 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     }
   },
-  "types": "./dist/index.d.ts",
   "files": [
     "dist"
   ],
@@ -53,7 +51,6 @@
   "devDependencies": {
     "@captable-ai/core": "workspace:*",
     "@types/node": "25.5.2",
-    "tsup": "8.5.1",
-    "typescript": "6.0.2"
+    "tsup": "8.5.1"
   }
 }

package/dist/index.d.ts

@@ -1 +0,0 @@
-#!/usr/bin/env node