@fairmint/captable-ai 0.1.6 → 0.1.8

package/dist/index.js

@@ -602,7 +602,7 @@ var COMMAND_REGISTRY = [
   {
     name: "objects get",
     group: "captable",
-    description: "Get a single OCF object with document and extraction details.",
+    description: "Get a single OCF object with document, extraction details, and a vesting summary when present.",
     usage: "captable-ai objects get <object-id> [--json]",
     requiresAuth: true,
     requiresPortal: true
@@ -1168,7 +1168,7 @@ var COMMAND_REGISTRY = [
   }
 ];
 async function runCommands(_args) {
-  printJson({ schemaVersion: "8", version: "0.0.1", commands: COMMAND_REGISTRY });
+  printJson({ schemaVersion: "9", version: "0.0.1", commands: COMMAND_REGISTRY });
 }
 
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
@@ -15260,7 +15260,10 @@ var LEGAL_DOCUMENTS_MAPPING = {
       "Founder Stock Purchase Agreement",
       "Notice of Stock Purchase Exercise",
       "Notice of RSA Exercise",
-      "Share Grant Exercise"
+      "Share Grant Exercise",
+      "Restricted Stock Award Agreement",
+      "Restricted Stock Award",
+      "RSA Agreement"
     ]
   },
   "Rolling SAFE": {
@@ -16064,6 +16067,176 @@ var exportResultSchema = external_exports.object({
   }).optional().describe("Present when pro-forma sheets were requested but engine refused.")
 });
 
+// ../captable-ai-core/dist/format-vesting-summary.js
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return null;
+  const out = {};
+  for (const [key, val] of Object.entries(value)) {
+    out[key] = val;
+  }
+  return out;
+}
+function gcd(a, b) {
+  let x = Math.abs(Math.trunc(a));
+  let y = Math.abs(Math.trunc(b));
+  while (y !== 0) {
+    const t = y;
+    y = x % y;
+    x = t;
+  }
+  return x || 1;
+}
+function reduceFraction(numerator, denominator) {
+  const divisor = gcd(numerator, denominator);
+  return { numerator: numerator / divisor, denominator: denominator / divisor };
+}
+function asConditions(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.filter((item) => asRecord(item) !== null);
+}
+function portionFraction(condition) {
+  const portion = asRecord(condition.portion);
+  if (!portion)
+    return null;
+  const numerator = Number(portion.numerator);
+  const denominator = Number(portion.denominator);
+  if (!Number.isFinite(numerator) || !Number.isFinite(denominator) || denominator <= 0)
+    return null;
+  if (numerator <= 0)
+    return null;
+  return { numerator, denominator };
+}
+function formatPercent(numerator, denominator) {
+  const reduced = reduceFraction(numerator, denominator);
+  const pct = reduced.numerator / reduced.denominator * 100;
+  if (Number.isInteger(pct) && pct >= 1 && pct <= 100)
+    return `${pct}%`;
+  return `${reduced.numerator}/${reduced.denominator}`;
+}
+function periodLabel(period) {
+  if (!period)
+    return null;
+  let occurrences = 1;
+  if (period.occurrences != null && period.occurrences !== "") {
+    occurrences = Number(period.occurrences);
+    if (!Number.isInteger(occurrences) || occurrences <= 0)
+      return null;
+  }
+  let length = 1;
+  if (period.length != null && period.length !== "") {
+    const suppliedLength = Number(period.length);
+    if (!Number.isFinite(suppliedLength) || suppliedLength < 0)
+      return null;
+    length = suppliedLength;
+  }
+  if (length === 0)
+    return { cadence: "immediately", occurrences };
+  const unit = String(period.type ?? "").toUpperCase();
+  if (unit === "MONTHS") {
+    return { cadence: length === 1 ? "monthly" : `every ${length} months`, occurrences };
+  }
+  if (unit === "DAYS") {
+    return { cadence: length === 1 ? "daily" : `every ${length} days`, occurrences };
+  }
+  if (unit === "WEEKS") {
+    return { cadence: length === 1 ? "weekly" : `every ${length} weeks`, occurrences };
+  }
+  if (unit === "YEARS") {
+    return { cadence: length === 1 ? "yearly" : `every ${length} years`, occurrences };
+  }
+  return null;
+}
+function quantityLabel(condition) {
+  const raw = condition.quantity;
+  if (raw == null || raw === "")
+    return null;
+  const quantity = Number(raw);
+  if (!Number.isFinite(quantity) || quantity <= 0)
+    return null;
+  return quantity === 1 ? "1 share" : `${quantity} shares`;
+}
+function trancheAmount(condition) {
+  const fraction = portionFraction(condition);
+  if (fraction)
+    return formatPercent(fraction.numerator, fraction.denominator);
+  return quantityLabel(condition);
+}
+function formatVestingSummary(ocf) {
+  const record2 = asRecord(ocf);
+  const conditions = asConditions(record2?.vesting_conditions);
+  if (conditions.length === 0)
+    return null;
+  const parts = [];
+  for (const condition of conditions) {
+    const trigger = asRecord(condition.trigger);
+    const triggerType = String(trigger?.type ?? "").toUpperCase();
+    if (triggerType === "VESTING_EVENT") {
+      const portion = asRecord(condition.portion);
+      const remainder = portion?.remainder === true || portion?.remainder === "true";
+      const hasAllocation = Boolean(trancheAmount(condition) || remainder);
+      if (portion && !hasAllocation)
+        continue;
+      parts.push("event-based (see conditions)");
+      continue;
+    }
+    const amount = trancheAmount(condition);
+    if (!amount)
+      continue;
+    if (triggerType === "VESTING_START_DATE") {
+      parts.push(`${amount} at grant`);
+      continue;
+    }
+    if (triggerType === "VESTING_SCHEDULE_ABSOLUTE") {
+      const date5 = typeof trigger?.date === "string" && trigger.date.length > 0 ? trigger.date : null;
+      parts.push(date5 ? `${amount} on ${date5}` : `${amount} on a fixed date`);
+      continue;
+    }
+    if (triggerType === "VESTING_SCHEDULE_RELATIVE") {
+      const period = periodLabel(asRecord(trigger?.period));
+      if (!period)
+        continue;
+      if (period.cadence === "immediately" && period.occurrences === 1) {
+        parts.push(`${amount} immediately`);
+        continue;
+      }
+      const fraction = portionFraction(condition);
+      if (fraction) {
+        const reduced = reduceFraction(fraction.numerator, fraction.denominator);
+        parts.push(`${reduced.numerator}/${reduced.denominator} ${period.cadence} \xD7 ${period.occurrences}`);
+        continue;
+      }
+      parts.push(`${amount} ${period.cadence} \xD7 ${period.occurrences}`);
+    }
+  }
+  if (parts.length === 0)
+    return null;
+  return `Vesting: ${parts.join(", then ")}`;
+}
+function unresolvedVestingTermsId(ocf) {
+  const record2 = asRecord(ocf);
+  if (!record2)
+    return null;
+  if (Array.isArray(record2.vesting_conditions) && record2.vesting_conditions.length > 0) {
+    return null;
+  }
+  return typeof record2.vesting_terms_id === "string" && record2.vesting_terms_id.length > 0 ? record2.vesting_terms_id : null;
+}
+async function resolveVestingSummary(ocf, fetchTermsOcf) {
+  const direct = formatVestingSummary(ocf);
+  if (direct)
+    return direct;
+  const termsId = unresolvedVestingTermsId(ocf);
+  if (!termsId)
+    return null;
+  try {
+    return formatVestingSummary(await fetchTermsOcf(termsId));
+  } catch {
+    return null;
+  }
+}
+
 // ../captable-ai-core/dist/objects-dump.js
 var DumpAssemblyError = class extends Error {
   constructor(message) {
@@ -16469,12 +16642,19 @@ function coerceDetails(raw) {
   return details.length > 0 ? details : void 0;
 }
 var REQUEST_TIMEOUT_MS2 = 3e4;
-function exitForRefreshFailure(err) {
+function exitForRefreshFailure(err, softFail = false) {
   if (err instanceof Error && err.name === "AuthError") {
-    exitWithError("Session expired. Run: captable-ai login", "AUTH_EXPIRED", void 0, EXIT.AUTH);
+    failRequest(
+      softFail,
+      "Session expired. Run: captable-ai login",
+      "AUTH_EXPIRED",
+      void 0,
+      EXIT.AUTH
+    );
   }
   if (err instanceof Error && (err.name === "NetworkError" || isTransportError(err))) {
-    exitWithError(
+    failRequest(
+      softFail,
       "Network error while refreshing session. Check your connection and try again.",
       "REFRESH_TRANSPORT",
       void 0,
@@ -16482,7 +16662,8 @@ function exitForRefreshFailure(err) {
     );
   }
   const detail = err instanceof Error ? err.message : String(err);
-  exitWithError(
+  failRequest(
+    softFail,
     `Token refresh failed: ${detail}. Run: captable-ai login`,
     "REFRESH_FAILED",
     void 0,
@@ -16496,6 +16677,22 @@ function isTransportError(err) {
   if (!(err instanceof Error)) return false;
   return err.name === "TimeoutError" || err.name === "AbortError" || err.name === "TypeError" || /network|timeout|fetch|ECONNRESET|ENOTFOUND|ETIMEDOUT/i.test(err.message);
 }
+var ApiRequestError = class extends Error {
+  code;
+  details;
+  constructor(message, code, details) {
+    super(message);
+    this.name = "ApiRequestError";
+    if (code !== void 0) this.code = code;
+    if (details !== void 0) this.details = details;
+  }
+};
+function failRequest(softFail, message, code, details, exitCode) {
+  if (softFail) {
+    throw new ApiRequestError(message, code, details);
+  }
+  exitWithError(message, code, details, exitCode);
+}
 async function refreshTokens(creds) {
   const baseUrl = getApiUrl();
   let res;
@@ -16539,20 +16736,20 @@ async function refreshTokens(creds) {
   await writeCredentials(updated);
   return updated;
 }
-async function getAuthHeaders() {
+async function getAuthHeaders(softFail = false) {
   let creds = await readCredentials();
   if (!creds) return {};
   if (isTokenExpired(creds.accessToken)) {
     try {
       creds = await refreshTokens(creds);
     } catch (err) {
-      exitForRefreshFailure(err);
+      exitForRefreshFailure(err, softFail);
     }
   }
   return { Authorization: `Bearer ${creds.accessToken}` };
 }
 async function apiRequest(path, opts = {}) {
-  const { method = "GET", body, query, skipAuth = false } = opts;
+  const { method = "GET", body, query, skipAuth = false, softFail = false } = opts;
   const baseUrl = getApiUrl();
   const url2 = new URL(`${baseUrl}${path}`);
   if (query) {
@@ -16562,7 +16759,7 @@ async function apiRequest(path, opts = {}) {
   }
   const headers = { "Content-Type": "application/json" };
   if (!skipAuth) {
-    Object.assign(headers, await getAuthHeaders());
+    Object.assign(headers, await getAuthHeaders(softFail));
   }
   const buildFetchOpts = () => ({
     method,
@@ -16575,14 +16772,16 @@ async function apiRequest(path, opts = {}) {
     res = await fetch(url2.toString(), buildFetchOpts());
   } catch (err) {
     if (err instanceof DOMException && err.name === "TimeoutError") {
-      exitWithError(
+      failRequest(
+        softFail,
         "Request timed out. Check your network connection and try again.",
         "TIMEOUT",
         void 0,
         EXIT.NETWORK
       );
     }
-    exitWithError(
+    failRequest(
+      softFail,
       `Network error: ${err instanceof Error ? err.message : "connection failed"}`,
       "NETWORK",
       void 0,
@@ -16596,23 +16795,25 @@ async function apiRequest(path, opts = {}) {
       try {
         refreshed = await refreshTokens(creds);
       } catch (refreshErr) {
-        exitForRefreshFailure(refreshErr);
+        exitForRefreshFailure(refreshErr, softFail);
       }
       if (refreshed) {
         headers.Authorization = `Bearer ${refreshed.accessToken}`;
         try {
           const retryRes = await fetch(url2.toString(), buildFetchOpts());
-          return handleResponse(retryRes);
+          return handleResponse(retryRes, softFail);
         } catch (retryErr) {
           if (retryErr instanceof DOMException && retryErr.name === "TimeoutError") {
-            exitWithError(
+            failRequest(
+              softFail,
               "Request timed out. Check your network connection and try again.",
               "TIMEOUT",
               void 0,
               EXIT.NETWORK
             );
           }
-          exitWithError(
+          failRequest(
+            softFail,
             `Network error: ${retryErr instanceof Error ? retryErr.message : "connection failed"}`,
             "NETWORK",
             void 0,
@@ -16622,7 +16823,7 @@ async function apiRequest(path, opts = {}) {
       }
     }
   }
-  return handleResponse(res);
+  return handleResponse(res, softFail);
 }
 function exitCodeForStatus(status) {
   if (status === 400) return EXIT.VALIDATION;
@@ -16633,14 +16834,26 @@ function exitCodeForStatus(status) {
   if (status >= 500) return EXIT.SERVER_ERROR;
   return EXIT.SERVER_ERROR;
 }
-async function handleResponse(res) {
-  const text = await res.text();
+async function handleResponse(res, softFail = false) {
+  let text;
+  try {
+    text = await res.text();
+  } catch (err) {
+    failRequest(
+      softFail,
+      `Network error: ${err instanceof Error ? err.message : "connection failed"}`,
+      "NETWORK",
+      void 0,
+      EXIT.NETWORK
+    );
+  }
   let parsed;
   try {
     parsed = JSON.parse(text);
   } catch {
     if (!res.ok) {
-      exitWithError(
+      failRequest(
+        softFail,
         `HTTP ${res.status}: ${text.slice(0, 200)}`,
         `HTTP_${res.status}`,
         void 0,
@@ -16656,14 +16869,26 @@ async function handleResponse(res) {
     if (isRecord2(nested)) {
       const code = typeof nested.code === "string" && nested.code.trim() ? nested.code : void 0;
       const details = coerceDetails(nested.details);
-      exitWithError(String(nested.message ?? `HTTP ${res.status}`), code, details, exitCode);
+      failRequest(
+        softFail,
+        String(nested.message ?? `HTTP ${res.status}`),
+        code,
+        details,
+        exitCode
+      );
     }
     if (typeof nested === "string") {
       const code = typeof obj.code === "string" && obj.code.trim() ? obj.code : `HTTP_${res.status}`;
       const details = coerceDetails(obj.details);
-      exitWithError(nested, code, details, exitCode);
+      failRequest(softFail, nested, code, details, exitCode);
     }
-    exitWithError(`HTTP ${res.status}: ${text.slice(0, 200)}`, void 0, void 0, exitCode);
+    failRequest(
+      softFail,
+      `HTTP ${res.status}: ${text.slice(0, 200)}`,
+      void 0,
+      void 0,
+      exitCode
+    );
   }
   return parsed;
 }
@@ -16779,6 +17004,10 @@ Global:
   --json                   Machine-readable JSON output (API order, not confidence-sorted)`;
 var HELP_OBJECTS_GET = `objects get \u2014 Show one OCF object
 
+After the OCF payload, prints a one-line vesting summary when the object (or
+its vesting_terms_id target) has a condition graph. --json adds vestingSummary
+as a sibling of data \u2014 not inside ocf.
+
 Usage:
   captable-ai objects get <object-id> [--json]`;
 var HELP_OBJECTS_DUMP = `objects dump \u2014 Engine-shaped ocf.json
@@ -19314,9 +19543,17 @@ async function runObjectsGet(args, rawArgv) {
   if (!obj) {
     exitWithError("Object not found", "OBJECT_NOT_FOUND", void 0, EXIT.NOT_FOUND);
   }
+  const vestingSummary = await resolveVestingSummary(obj.ocf, async (termsId) => {
+    const terms = await apiRequest(
+      `/${portalId}/objects/${encodeURIComponent(termsId)}`,
+      { softFail: true }
+    );
+    return terms.data?.ocf ?? null;
+  });
   if (isJsonMode()) {
     const out = { data: obj };
     if (res.meta !== void 0) out.meta = res.meta;
+    if (vestingSummary) out.vestingSummary = vestingSummary;
     printJson(out);
     return;
   }
@@ -19351,7 +19588,10 @@ Object: ${obj.id}
   }
   printLine("\nOCF data:\n");
   printJson(obj.ocf);
-  printLine();
+  if (vestingSummary) printLine(`
+${vestingSummary}
+`);
+  else printLine();
 }
 
 // src/validate.ts
@@ -20990,7 +21230,7 @@ Cap Table (read):
                              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
+  objects get <id>          Show a single OCF object (vesting summary when present)
   objects dump              Engine-shaped ocf.json (default --status committed; --output path)
   schemas list              List OCF object types
   schemas get <type>        Show schema for an OCF type

package/package.json

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