@fairmint/captable-ai 0.1.13 → 0.1.14

package/README.md

@@ -30,8 +30,12 @@ the login code back into the terminal. Credentials are stored in `~/.captable-ai
 
 ```bash
 captable-ai login
-captable-ai company use "Acme Inc"          # if you have more than one
+captable-ai onboarding status
+captable-ai onboarding setup ...            # only when you have no workspace
+captable-ai company use "Acme Inc"           # if you have more than one
+captable-ai import start
 captable-ai documents upload ./docs/*.pdf
+captable-ai import status <session-id>
 captable-ai documents trigger-extraction    # once all docs are CLASSIFIED
 captable-ai documents list                  # poll until PROCESSED
 captable-ai commit --dry-run                 # preview
@@ -84,6 +88,8 @@ automated, but a few habits make extraction faster and more accurate:
 |---------|-------------|
 | `login` / `logout` | Authenticate / clear stored credentials |
 | `auth status` | Show the current session |
+| `onboarding status\|setup` | Inspect onboarding or create the first workspace |
+| `import start\|status` | Start an import session and poll existing document processing |
 | `company list\|use\|current\|create\|delete` | Manage and select the active company |
 | `documents upload\|list\|download\|delete` | Manage source documents |
 | `documents trigger-extraction\|cancel-extraction\|restart-extraction\|reprocess` | Control the OCF extraction pipeline |

package/dist/index.js

@@ -170,8 +170,8 @@ function parsePortals(body) {
   if (!portals.every(isStoredPortal)) return null;
   return portals;
 }
-async function refreshPortalsIfStale(creds) {
-  if (creds.portalsLastFetchedAt && Date.now() - Date.parse(creds.portalsLastFetchedAt) < PORTALS_TTL_MS) {
+async function refreshPortalsIfStale(creds, force = false) {
+  if (!force && creds.portalsLastFetchedAt && Date.now() - Date.parse(creds.portalsLastFetchedAt) < PORTALS_TTL_MS) {
     return creds;
   }
   if (isTokenExpired(creds.accessToken)) {
@@ -508,6 +508,45 @@ var COMMAND_REGISTRY = [
     requiresPortal: false,
     flags: [{ name: "yes", description: "Skip the confirmation prompt.", type: "boolean" }]
   },
+  {
+    name: "onboarding status",
+    group: "onboarding",
+    description: "Show the next first-workspace or import action. Works for authenticated users with zero companies.",
+    usage: "captable-ai onboarding status [--session <import-session-id>] [--json]",
+    requiresAuth: true,
+    requiresPortal: false,
+    flags: [
+      {
+        name: "session",
+        description: "Inspect this import session instead of local workspace state.",
+        type: "string"
+      }
+    ]
+  },
+  {
+    name: "onboarding setup",
+    group: "onboarding",
+    description: "Idempotently create the authenticated user's first production workspace.",
+    usage: "captable-ai onboarding setup --legal-name <name> --company-type <type> --role <role> --cap-table-source <source> --stakeholder-count <bucket> --accept-terms [--country <code>] [--other-role <role>] [--other-cap-table-source <source>] [--json]",
+    requiresAuth: true,
+    requiresPortal: false
+  },
+  {
+    name: "import start",
+    group: "onboarding",
+    description: "Start or reuse a secure import session for existing document upload APIs.",
+    usage: "captable-ai import start [--json]",
+    requiresAuth: true,
+    requiresPortal: true
+  },
+  {
+    name: "import status",
+    group: "onboarding",
+    description: "Show import processing progress and the next existing-pipeline action.",
+    usage: "captable-ai import status <session-id> [--json]",
+    requiresAuth: true,
+    requiresPortal: false
+  },
   {
     name: "summary",
     group: "captable",
@@ -1184,7 +1223,7 @@ var COMMAND_REGISTRY = [
   }
 ];
 async function runCommands(_args) {
-  printJson({ schemaVersion: "9", version: "0.0.1", commands: COMMAND_REGISTRY });
+  printJson({ schemaVersion: "10", version: "0.0.1", commands: COMMAND_REGISTRY });
 }
 
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
@@ -16982,6 +17021,13 @@ async function refreshTokens(creds) {
   await writeCredentials(updated);
   return updated;
 }
+async function refreshSession() {
+  const credentials = await readCredentials();
+  if (!credentials) {
+    exitWithError("Not logged in. Run: captable-ai login", "AUTH_REQUIRED", void 0, EXIT.AUTH);
+  }
+  return refreshTokens(credentials);
+}
 async function getAuthHeaders(softFail = false) {
   let creds = await readCredentials();
   if (!creds) return {};
@@ -17194,6 +17240,36 @@ function argvRequestsHelp(argv) {
 }
 
 // src/help-text.ts
+var HELP_ONBOARDING = `onboarding \u2014 Create a first workspace and inspect next steps
+
+Usage:
+  captable-ai onboarding status [--session <import-session-id>] [--json]
+  captable-ai onboarding setup --legal-name <name> --company-type <type>
+    --role <role> --cap-table-source <source> --stakeholder-count <bucket>
+    --accept-terms [options] [--json]
+
+Setup values:
+  --company-type        us_c_corporation | us_llc | foreign_entity | not_incorporated
+  --country             ISO country code (required for foreign_entity)
+  --role                CEO | COO | CMO | CFO | CTO | CRO | Director | Founder |
+                        co-founder | co-CEO | other
+  --other-role          Required when --role other
+  --cap-table-source    none | spreadsheet | carta | pulley | angellist | other
+  --other-cap-table-source  Required when --cap-table-source other
+  --stakeholder-count   1_10 | 11_25 | 26_50 | 50_100 | 100_plus
+  --accept-terms        Confirm acceptance of Fairmint's Terms of Service`;
+var HELP_IMPORT = `import \u2014 Start and inspect a secure document-import session
+
+Usage:
+  captable-ai import start [--json]
+  captable-ai import status <session-id> [--json]
+
+For local files, the recommended data path remains:
+  captable-ai documents upload <file...>
+
+It performs prepare \u2192 direct presigned S3 PUT \u2192 confirm without routing file bytes
+through the CaptableAI API. After processing finishes, review drafts with
+\`objects list\` and commit with the existing \`commit --dry-run\` / \`commit --all\` commands.`;
 var HELP_AUTH = `auth \u2014 Session information
 
 Usage:
@@ -20767,6 +20843,355 @@ async function runObjectsVersions(args, rawArgv) {
   }
 }
 
+// src/commands/onboarding.ts
+function nextAction(id, label, command) {
+  return command ? { id, label, required: true, command } : { id, label, required: true };
+}
+async function runOnboardingStatus(args) {
+  validateFlags(args, { flags: ["session"], booleans: [] });
+  const sessionId = typeof args.flags.session === "string" ? args.flags.session : void 0;
+  if (sessionId) {
+    await runImportStatus(parseArgs([sessionId]));
+    return;
+  }
+  const credentials = await readCredentials();
+  if (!credentials) {
+    exitWithError("Not logged in. Run: captable-ai login", "AUTH_REQUIRED", void 0, EXIT.AUTH);
+  }
+  const active = resolveActiveCompany(await readConfig(), credentials.portals);
+  const data = credentials.portals.length === 0 ? {
+    state: ONBOARDING_STATES.NEEDS_COMPANY_SETUP,
+    nextActions: [
+      nextAction(
+        "setup_workspace",
+        "Create your first workspace",
+        "captable-ai onboarding setup"
+      )
+    ],
+    question: "What is your company's full legal name?"
+  } : !active ? {
+    state: ONBOARDING_STATES.NEEDS_COMPANY_SELECTION,
+    companies: credentials.portals,
+    nextActions: [
+      nextAction(
+        "select_company",
+        "Choose the company to import into",
+        "captable-ai company use <id-or-name>"
+      )
+    ],
+    question: "Which company should receive this cap table import?"
+  } : {
+    state: ONBOARDING_STATES.READY_TO_IMPORT,
+    company: active,
+    nextActions: [
+      nextAction(
+        "start_import",
+        "Start a secure import session",
+        "captable-ai import start"
+      ),
+      nextAction(
+        "upload_cli",
+        "Upload local documents directly to S3",
+        "captable-ai documents upload <file...>"
+      )
+    ],
+    question: `Should I start a secure import session for ${active.name ?? active.id}?`
+  };
+  if (isJsonMode()) {
+    printJson({ data });
+    return;
+  }
+  printKeyValue([
+    ["State", data.state],
+    ["Question", data.question]
+  ]);
+  for (const action of data.nextActions) {
+    printLine(`  Next: ${String(action.command)}`);
+  }
+}
+function setupInput(args) {
+  const flagMap = {
+    legalName: "legal-name",
+    companyType: "company-type",
+    country: "country",
+    role: "role",
+    otherRole: "other-role",
+    capTableSource: "cap-table-source",
+    otherCapTableSource: "other-cap-table-source",
+    stakeholderCount: "stakeholder-count"
+  };
+  const input = {
+    termsAccepted: hasFlag(args, "accept-terms")
+  };
+  for (const [field, flag] of Object.entries(flagMap)) {
+    const value = args.flags[flag];
+    if (typeof value === "string") input[field] = value;
+  }
+  return input;
+}
+function omitInapplicableOnboardingSetupFields(input) {
+  const next = { ...input };
+  if (next.companyType !== ONBOARDING_COMPANY_TYPES.FOREIGN_ENTITY) {
+    delete next.country;
+  }
+  if (next.role !== ONBOARDING_OTHER_ROLE) {
+    delete next.otherRole;
+  }
+  if (next.capTableSource !== ONBOARDING_CAP_TABLE_SOURCES.OTHER) {
+    delete next.otherCapTableSource;
+  }
+  return next;
+}
+async function runOnboardingSetup(args) {
+  validateFlags(args, {
+    flags: [
+      "legal-name",
+      "company-type",
+      "country",
+      "role",
+      "other-role",
+      "cap-table-source",
+      "other-cap-table-source",
+      "stakeholder-count"
+    ],
+    booleans: ["accept-terms"]
+  });
+  const parsed = onboardingWorkspaceSetupInputSchema.safeParse(
+    omitInapplicableOnboardingSetupFields(setupInput(args))
+  );
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((issue2) => ({
+      path: issue2.path.join("."),
+      message: issue2.message
+    }));
+    exitWithError(
+      "Company setup answers are incomplete or invalid. Run `captable-ai onboarding setup --help` for accepted values.",
+      "VALIDATION_FAILED",
+      details,
+      EXIT.VALIDATION
+    );
+  }
+  const input = parsed.data;
+  const response = await apiRequest("/onboarding/workspace", { method: "POST", body: input });
+  const result = onboardingWorkspaceSetupResultSchema.safeParse(response.data ?? response);
+  if (!result.success) {
+    exitWithError(
+      "Unexpected onboarding setup response from server.",
+      "SERVER_ERROR",
+      void 0,
+      EXIT.SERVER_ERROR
+    );
+  }
+  if (result.data.session.action === ONBOARDING_SESSION_ACTIONS.REFRESH) {
+    const refreshed = await refreshSession();
+    const withPortals = await refreshPortalsIfStale(refreshed, true);
+    const portal = withPortals.portals.find(({ id }) => id === result.data.portalId);
+    if (!portal) {
+      exitWithError(
+        "Workspace was created, but the refreshed session did not include it.",
+        "SESSION_REFRESH_FAILED",
+        void 0,
+        EXIT.SERVER_ERROR
+      );
+    }
+    await setActivePortal(portal);
+    const data2 = {
+      ...result.data,
+      state: ONBOARDING_STATES.READY_TO_IMPORT,
+      nextActions: [
+        nextAction("start_import", "Start the secure document import", "captable-ai import start")
+      ],
+      question: "Your workspace is ready. Start the document import now?"
+    };
+    if (isJsonMode()) {
+      printJson({ data: data2 });
+      return;
+    }
+    printSuccess(`Workspace ready: ${input.legalName} (${result.data.portalId})`);
+    printLine("Start the import: captable-ai import start");
+    return;
+  }
+  const data = {
+    ...result.data,
+    nextActions: [
+      nextAction("reconnect", "Reconnect to activate the workspace", "captable-ai login"),
+      nextAction("start_import", "Start an import after reconnecting", "captable-ai import start")
+    ],
+    question: "Your workspace is ready. Please run `captable-ai login` again, then start the import."
+  };
+  if (isJsonMode()) {
+    printJson({ data });
+    return;
+  }
+  printSuccess(`Workspace ready: ${input.legalName} (${result.data.portalId})`);
+  printLine("Reconnect so your session can access it: captable-ai login");
+}
+async function runImportStart(args) {
+  validateFlags(args, { flags: [], booleans: [] });
+  const portalId = await getActivePortalId();
+  const response = await apiRequest(
+    "/import-sessions",
+    {
+      method: "POST",
+      body: { portalId }
+    }
+  );
+  const session = response.data?.session;
+  if (!session?.id) {
+    exitWithError(
+      "Unexpected import session response from server.",
+      "SERVER_ERROR",
+      void 0,
+      EXIT.SERVER_ERROR
+    );
+  }
+  const data = {
+    ...response.data,
+    nextActions: [
+      nextAction(
+        "upload_cli",
+        "Upload local documents directly to S3",
+        "captable-ai documents upload <file...>"
+      ),
+      nextAction(
+        "check_status",
+        "Check import progress",
+        `captable-ai import status ${session.id}`
+      )
+    ],
+    question: "Which cap table documents should be uploaded with `documents upload`?"
+  };
+  if (isJsonMode()) {
+    printJson({ data });
+    return;
+  }
+  printSuccess(`Import session ${response.data?.reused ? "reused" : "started"}: ${session.id}`);
+  printLine("Upload documents: captable-ai documents upload <file...>");
+  printLine(`Check progress: captable-ai import status ${session.id}`);
+}
+var TERMINAL_DOCUMENT_STATUSES = /* @__PURE__ */ new Set(["PROCESSED", "COMMITTED", "FAILED", "CANCELLED"]);
+function documentsForImportSession(documents, sessionCreatedAt) {
+  if (typeof sessionCreatedAt !== "string" || sessionCreatedAt.length === 0) return [];
+  return documents.filter(
+    (document) => typeof document.lastActivityAt === "string" && document.lastActivityAt >= sessionCreatedAt
+  );
+}
+function summarizeImportDocuments(documents) {
+  const statuses = documents.map((document) => (document.status ?? "").toUpperCase());
+  const failed = statuses.filter((status) => ["FAILED", "CANCELLED"].includes(status)).length;
+  const classified = statuses.filter((status) => status === "CLASSIFIED").length;
+  const pendingUpload = statuses.filter((status) => status === "PENDING_UPLOAD").length;
+  const processing = statuses.filter(
+    (status) => status !== "" && !TERMINAL_DOCUMENT_STATUSES.has(status) && status !== "CLASSIFIED" && status !== "PENDING_UPLOAD"
+  ).length;
+  return {
+    total: documents.length,
+    processing,
+    classified,
+    pendingUpload,
+    failed,
+    complete: documents.length - failed - processing - classified - pendingUpload
+  };
+}
+async function runImportStatus(args) {
+  validateFlags(args, { flags: [], booleans: [] });
+  const sessionId = args.positional[0];
+  if (!sessionId) {
+    exitWithUsage(
+      "Import session ID is required.",
+      "Usage: captable-ai import status <session-id> [--json]"
+    );
+  }
+  const response = await apiRequest(
+    `/import-sessions/${encodeURIComponent(sessionId)}/status`
+  );
+  const documents = documentsForImportSession(
+    response.data?.processing?.documents ?? [],
+    response.data?.session?.createdAt
+  );
+  const summary = summarizeImportDocuments(documents);
+  const sessionState = response.data?.session?.state;
+  if (documents.length > 0 && summary.processing === 0 && summary.classified === 0 && summary.pendingUpload === 0 && summary.failed === 0 && sessionState !== "completed") {
+    const completed = await apiRequest(
+      `/import-sessions/${encodeURIComponent(sessionId)}/complete`,
+      {
+        method: "POST",
+        body: {}
+      }
+    );
+    if (response.data && completed.data?.session) {
+      response.data.session = { ...response.data.session, ...completed.data.session };
+    }
+  }
+  const state = documents.length === 0 ? ONBOARDING_STATES.READY_TO_IMPORT : summary.processing > 0 ? ONBOARDING_STATES.PROCESSING : summary.classified > 0 || summary.pendingUpload > 0 ? ONBOARDING_STATES.READY_TO_IMPORT : summary.failed > 0 ? ONBOARDING_STATES.BLOCKED : ONBOARDING_STATES.NEEDS_REVIEW;
+  const nextActions = documents.length === 0 || summary.pendingUpload > 0 ? [
+    nextAction(
+      "upload_cli",
+      "Upload local documents directly to S3",
+      "captable-ai documents upload <file...>"
+    ),
+    ...summary.classified > 0 ? [
+      nextAction(
+        "trigger_extraction",
+        "Start OCF extraction for classified documents",
+        "captable-ai documents trigger-extraction"
+      )
+    ] : []
+  ] : summary.classified > 0 ? [
+    nextAction(
+      "trigger_extraction",
+      "Start OCF extraction for classified documents",
+      "captable-ai documents trigger-extraction"
+    )
+  ] : summary.processing > 0 ? [
+    nextAction(
+      "check_status",
+      "Check import progress again",
+      `captable-ai import status ${sessionId}`
+    )
+  ] : summary.failed > 0 ? [
+    nextAction(
+      "review_failures",
+      "Review failed documents",
+      "captable-ai documents list --status FAILED"
+    )
+  ] : [
+    nextAction(
+      "review_drafts",
+      "Review extracted drafts",
+      "captable-ai objects list --status draft --all"
+    ),
+    nextAction(
+      "preview_commit",
+      "Preview the first commit",
+      "captable-ai commit --dry-run"
+    ),
+    nextAction("confirm_commit", "Commit reviewed drafts", "captable-ai commit --all")
+  ];
+  const data = {
+    ...response.data,
+    state,
+    summary,
+    nextActions
+  };
+  if (isJsonMode()) {
+    printJson({ data });
+    return;
+  }
+  printKeyValue([
+    ["Session", sessionId],
+    ["State", data.state],
+    ["Documents", summary.total],
+    ["Classified", summary.classified],
+    ["Processing", summary.processing],
+    ["Complete", summary.complete],
+    ["Failed", summary.failed]
+  ]);
+  for (const action of nextActions) {
+    printLine(`  Next: ${String(action.command)}`);
+  }
+}
+
 // src/commands/pro-forma.ts
 var SCENARIO_TYPES2 = ["financing", "convertible", "warrant", "option-pool"];
 function buildScenarioBody(type, args) {
@@ -21597,7 +22022,9 @@ var PROFILE_AWARE_COMMANDS = /* @__PURE__ */ new Set([
   "company",
   "documents",
   "export",
+  "import",
   "objects",
+  "onboarding",
   "pro-forma",
   "register",
   "logs",
@@ -21621,6 +22048,12 @@ Company:
   company create            Create a test portal (super admin)
   company delete <id>       Delete a test portal (dev only, super admin)
 
+Onboarding:
+  onboarding status         Show the next setup/import action (works with zero companies)
+  onboarding setup          Create the first production workspace
+  import start              Start or reuse a document import session
+  import status <id>        Check import processing via existing document APIs
+
 Cap Table (read):
   summary                   Full cap table snapshot (capitalization, stakeholders, metrics)
                              Options: --as-of, --include-pending, --skip-stakeholders, --page
@@ -21897,6 +22330,50 @@ async function main() {
       case "company":
         await routeCompany(positionalArgs);
         break;
+      case "onboarding":
+        if (isHelpToken(sub) || argvRequestsHelp(positionalArgs.slice(2))) {
+          process.stdout.write(`${HELP_ONBOARDING}
+`);
+          process.exit(0);
+        }
+        switch (sub) {
+          case "status":
+            await runOnboardingStatus(parseArgs(positionalArgs.slice(2)));
+            break;
+          case "setup":
+            await runOnboardingSetup(parseArgs(positionalArgs.slice(2)));
+            break;
+          default:
+            exitWithError(
+              `Unknown onboarding command: ${sub ?? "(none)"}. Try: onboarding status | setup`,
+              "UNKNOWN_COMMAND",
+              void 0,
+              EXIT.USAGE
+            );
+        }
+        break;
+      case "import":
+        if (isHelpToken(sub) || argvRequestsHelp(positionalArgs.slice(2))) {
+          process.stdout.write(`${HELP_IMPORT}
+`);
+          process.exit(0);
+        }
+        switch (sub) {
+          case "start":
+            await runImportStart(parseArgs(positionalArgs.slice(2)));
+            break;
+          case "status":
+            await runImportStatus(parseArgs(positionalArgs.slice(2)));
+            break;
+          default:
+            exitWithError(
+              `Unknown import command: ${sub ?? "(none)"}. Try: import start | status`,
+              "UNKNOWN_COMMAND",
+              void 0,
+              EXIT.USAGE
+            );
+        }
+        break;
       case "summary":
         if (argvRequestsHelp(positionalArgs.slice(1))) {
           process.stdout.write(`${HELP_SUMMARY}

package/package.json

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