@startanaicompany/crm 2.4.0 → 2.5.0

package/README.md

@@ -10,43 +10,56 @@ npm install -g @startanaicompany/crm
 
 ---
 
-## 🤖 AI Agent Quick Start (zero-auth, no human needed)
+## 🏢 Multi-Tenant Architecture
 
-Agents bootstrap themselves with a single command — **no credentials required**:
+This CRM is **multi-tenant**: each company gets its own isolated workspace. All data (leads, contacts, calls, contracts, etc.) is completely separated between workspaces.
+
+- One workspace slug per company (e.g. `mygardeningcompany`, `johnscarshop`)
+- All agents of a company share the same workspace — one key per "fleet" or one key per agent, your choice
+- Cross-workspace data access is impossible: a key from workspace `mygardeningcompany` can never see data from `johnscarshop`
+
+---
+
+## 🤖 AI Agent Quick Start (zero-auth)
+
+Agents bootstrap themselves in two steps:
 
 ```bash
-# Step 1: create your own API key (no auth needed)
-saac_crm config set --url https://your-crm.example.com
-saac_crm keys create --name my-agent
-# → returns crm_xxxxxxxxxxxx — store this as your API key
+# Step 1: Point at the CRM deployment
+saac_crm config set --url https://crm.startanaicompany.com
+
+# Step 2: Bootstrap your workspace + get an API key (no auth needed, no human required)
+saac_crm workspace init --workspace mygardeningcompany --name my-agent
+# → Returns crm_xxxx API key + saves key + workspace to ~/.saac_crm/config.json
 
-# Step 2: set the key and start managing leads
-export SAAC_CRM_API_KEY=crm_xxxxxxxxxxxx
+# Step 3: Start working (workspace is automatically used from config)
 saac_crm leads create --name "Jane Smith" --email "jane@example.com"
 saac_crm leads list
+
+# Optional: attribute actions to a named agent for audit trail
+saac_crm leads create --name "Bob Jones" --email "bob@example.com" --from-agent-name "discovery-agent-v2"
 ```
 
 > **Auth priority**: `--api-key` flag > `SAAC_CRM_API_KEY` env var > config file (`~/.saac_crm/config.json`)
+> **Workspace priority**: `--workspace` flag > `SAAC_CRM_WORKSPACE` env var > config file `workspace` field
 
-> ⚠️ **Agents: never call `saac_crm register`** — that command is for one-time operator setup only (requires deployment password). Your entry point is always `keys create --name`.
+> ⚠️ **Agents: `workspace init` is idempotent** — if the workspace already exists, it just creates a new key for it. Safe to call from any agent on first run.
 
 ---
 
 ## 👤 Operator Setup (one-time, human)
 
-This is done once per deployment — **not by agents**:
+For the initial admin setup or to create admin-scope keys:
 
 ```bash
 # 1. Point at your deployment
-saac_crm config set --url https://your-crm.example.com
+saac_crm config set --url https://crm.startanaicompany.com
 
-# 2. Register workspace + create admin key (prompts for workspace slug and password)
-saac_crm register --name "main-admin-key"
-# → prompts: Workspace slug (e.g. mycompany):
-# → prompts: Deployment admin password:
-# → returns crm_xxx admin key — store securely
+# 2. Create admin-scope key for your workspace (requires deployment admin password)
+saac_crm keys create --name "admin-key" --workspace mycompany --scope admin
+# → Prompts for admin password
 
-# 3. Save admin key and create first human user account
+# 3. Save admin key to config and create the first human user account
 saac_crm config set --api-key crm_xxx_admin_key
 saac_crm users create --email admin@example.com --name "Admin" --role admin
 ```
@@ -55,17 +68,27 @@ saac_crm users create --email admin@example.com --name "Admin" --role admin
 
 ## Commands
 
+### Workspace
+
+```bash
+# Bootstrap workspace + create API key in one step (recommended for agent auto-init)
+saac_crm workspace init --workspace mycompany --name "my-agent"
+saac_crm workspace init --workspace mycompany --name "admin-key" --scope admin
+
+# Via REST: POST /api/v1/workspaces/register
+# Body: { workspace, key_name, scope?, admin_password? }
+```
+
 ### API Keys
 
 ```bash
-# Create agent key — ZERO AUTH, no prior setup needed
-saac_crm keys create --name "my-agent"
+# Create agent key — workspace required (auto-creates workspace if it doesn't exist yet)
+saac_crm keys create --name "my-agent" --workspace mycompany
 
-# Create admin scope key (operator only — requires deployment password + workspace slug)
-saac_crm keys create --name "admin-key" --scope admin \
-  --workspace mycompany --admin-password <deployment-password>
+# Create admin scope key (requires deployment password)
+saac_crm keys create --name "admin-key" --workspace mycompany --scope admin
 
-# List all keys (metadata only — full key never shown again)
+# List all keys in current workspace
 saac_crm keys list
 
 # Show current key info
@@ -78,11 +101,11 @@ saac_crm keys revoke <id>
 ### Leads
 
 ```bash
-# Create a lead
-saac_crm leads create --name "Jane Smith" --email "jane@example.com" --company "Acme"
+# Create a lead (optional: --from-agent-name for audit trail)
+saac_crm leads create --name "Jane Smith" --email "jane@example.com" --company "Acme" --from-agent-name "lead-gen-agent"
 
 # List leads (with filters)
-saac_crm leads list --status new --tag vip --tag enterprise
+saac_crm leads list --status new --tag vip
 
 # Get single lead
 saac_crm leads get <id>
@@ -95,22 +118,76 @@ saac_crm leads delete <id>
 
 # Status change history
 saac_crm leads history <id>
+
+# Move lead to pipeline stage
+saac_crm leads stage <id> --stage discovery
+```
+
+### Contacts
+
+```bash
+saac_crm contacts create --email contact@example.com --first-name "Jane" --from-agent-name "enrichment-agent"
+saac_crm contacts list
+saac_crm contacts get <id>
+saac_crm contacts update <id> --company "Acme"
+saac_crm contacts delete <id>
+```
+
+### Calls
+
+```bash
+saac_crm calls create --lead-id <id> --direction outbound --outcome connected --from-agent-name "call-agent"
+saac_crm calls list [--lead-id <id>]
+saac_crm calls get <id>
+```
+
+### Meetings
+
+```bash
+saac_crm meetings create --lead-id <id> --title "Demo call" --from-agent-name "scheduler-agent"
+saac_crm meetings list
+saac_crm meetings get <id>
+```
+
+### Emails
+
+```bash
+saac_crm emails create --lead-id <id> --subject "Follow-up" --direction sent --from-agent-name "outreach-agent"
+saac_crm emails list [--lead-id <id>]
+saac_crm emails get <id>
+```
+
+### Quotes
+
+```bash
+saac_crm quotes create --lead-id <id> --title "Q-2026-001" --value 5000 --from-agent-name "quote-agent"
+saac_crm quotes list
+saac_crm quotes get <id>
+saac_crm quotes status <id> --status accepted
+saac_crm quotes add-line <id> --description "License" --quantity 1 --unit-price 5000
+```
+
+### Contracts
+
+```bash
+saac_crm contracts create --lead-id <id> --title "Service Agreement" --from-agent-name "contract-agent"
+saac_crm contracts list
+saac_crm contracts get <id>
+saac_crm contracts status <id> --status sent
+saac_crm contracts signatories <id>
+saac_crm contracts add-signatory <id> --contact-id <cid> --party customer --role signer
+saac_crm contracts sign <id> --contact-id <cid>
+saac_crm contracts decline-signature <id> --contact-id <cid>
+saac_crm contracts remind-signatory <id> --contact-id <cid>
+saac_crm contracts remind-all-pending <id>
 ```
 
 ### Users (requires admin scope key)
 
 ```bash
-# Create a human user account (both commands are equivalent)
 saac_crm users create --email admin@example.com --name "Admin User" --role admin
-saac_crm users register --email admin@example.com --name "Admin User" --role admin
-
-# List users
 saac_crm users list
-
-# Update user
 saac_crm users update <id> --role viewer
-
-# Deactivate user
 saac_crm users deactivate <id>
 ```
 
@@ -119,23 +196,16 @@ saac_crm users deactivate <id>
 ```bash
 # Log in as admin/viewer — saves JWT to config for dashboard access
 saac_crm login --workspace mycompany --email admin@example.com
-# → prompts for password, saves JWT to ~/.saac_crm/config.json
-```
-
-### Workspace Registration (operator only)
-
-```bash
-# First-time setup — registers workspace slug + creates admin key
-# Prompts for --workspace and --admin-password if not provided
-saac_crm register --name "main-admin-key"
-saac_crm register --name "main-admin-key" --workspace mycompany --admin-password <pw>
+# → Prompts for password, saves JWT to ~/.saac_crm/config.json
 ```
 
 ### Configuration
 
 ```bash
-saac_crm config set --url https://your-crm.example.com
+saac_crm config set --url https://crm.startanaicompany.com
 saac_crm config set --api-key crm_xxxxxxxxxxxx
+saac_crm config set --workspace mycompany
+saac_crm config set --agent-name "my-agent-v2"   # default --from-agent-name for all commands
 saac_crm config get
 ```
 
@@ -146,10 +216,21 @@ saac_crm config get
 --url <url>       Override API base URL for this command
 ```
 
+## `--from-agent-name` Attribution
+
+Pass `--from-agent-name <name>` (or set `SAAC_CRM_AGENT_NAME` env / `config.defaultAgentName`) on any create command to attribute the action to a named agent. This is for **audit trail only** — it does NOT affect authentication or authorization. The same workspace key is shared across all agents of that workspace.
+
+```bash
+export SAAC_CRM_AGENT_NAME=discovery-agent-v2
+saac_crm leads create --name "Alice" --email "alice@example.com"
+# → lead.from_agent_name = "discovery-agent-v2"
+```
+
 ## Architecture
 
-This is a **single-tenant** system: one workspace slug per deployment, registered once by an operator.
+This is a **multi-tenant** system: multiple workspace slugs per deployment, each fully isolated.
 
-- **Agents** → self-service `keys create` → manage leads
-- **Operators** → `register` once → `users create` → human accounts
-- **Humans** → `login` → web dashboard at your deployment URL
+- **Agents** → `workspace init` once → `leads create` → manage leads with workspace isolation
+- **Operators** → `keys create --scope admin` → `users create` → human accounts
+- **Humans** → `login` → web dashboard (only shows their workspace's data)
+- **Audit** → `--from-agent-name` for per-agent attribution within a workspace

package/index.js

@@ -43,7 +43,21 @@ function resolveApiUrl(cliUrl) {
   return cfg.apiUrl || null;
 }
 
-function getClient(options = {}) {
+function resolveWorkspace(cliWorkspace) {
+  if (cliWorkspace) return cliWorkspace;
+  if (process.env.SAAC_CRM_WORKSPACE) return process.env.SAAC_CRM_WORKSPACE;
+  const cfg = loadConfig();
+  return cfg.workspace || null;
+}
+
+function resolveAgentName(cliAgentName) {
+  if (cliAgentName) return cliAgentName;
+  if (process.env.SAAC_CRM_AGENT_NAME) return process.env.SAAC_CRM_AGENT_NAME;
+  const cfg = loadConfig();
+  return cfg.defaultAgentName || null;
+}
+
+function getClient(options = {}, agentName = null) {
   const apiKey = resolveApiKey(options.apiKey);
   const apiUrl = resolveApiUrl(options.url);
 
@@ -56,12 +70,15 @@ function getClient(options = {}) {
     process.exit(1);
   }
 
+  const headers = {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json'
+  };
+  if (agentName) headers['X-Agent-Name'] = agentName;
+
   return axios.create({
     baseURL: `${apiUrl.replace(/\/$/, '')}/api/v1`,
-    headers: {
-      'Authorization': `Bearer ${apiKey}`,
-      'Content-Type': 'application/json'
-    }
+    headers
   });
 }
 
@@ -116,6 +133,8 @@ configCmd
   .description('Set configuration values')
   .option('--url <url>', 'CRM API base URL (e.g. https://yourapp.example.com)')
   .option('--api-key <key>', 'Default API key to use')
+  .option('--workspace <slug>', 'Default workspace slug')
+  .option('--agent-name <name>', 'Default agent name for attribution (stored as defaultAgentName)')
   .action((opts) => {
     // NOTE: commander.js may consume --url and --api-key at the parent program level
     // if they share the same option names. Always fall back to program.opts().
@@ -125,6 +144,8 @@ configCmd
     const apiKeyValue = opts.apiKey || globalOpts.apiKey;
     if (urlValue) cfg.apiUrl = urlValue;
     if (apiKeyValue) cfg.apiKey = apiKeyValue;
+    if (opts.workspace) cfg.workspace = opts.workspace;
+    if (opts.agentName) cfg.defaultAgentName = opts.agentName;
     saveConfig(cfg);
     console.log('Configuration saved to', CONFIG_FILE);
     printJSON(cfg);
@@ -151,7 +172,7 @@ keysCmd
   .description('Create a new API key')
   .requiredOption('--name <name>', 'Name/label for the key')
   .option('--scope <scope>', 'Key scope: agent (default) or admin', 'agent')
-  .option('--workspace <slug>', 'Workspace slug (required for scope=admin, e.g. goldenrecruit101)')
+  .option('--workspace <slug>', 'Workspace slug (falls back to config workspace)')
   .option('--admin-password <password>', 'Admin password (required for scope=admin)')
   .action(async (opts) => {
     const globalOpts = program.opts();
@@ -161,15 +182,15 @@ keysCmd
       process.exit(1);
     }
 
-    const body = { name: opts.name, scope: opts.scope };
+    const workspace = resolveWorkspace(opts.workspace);
+    if (!workspace) {
+      console.error('Error: --workspace <slug> is required (or set in config via: saac_crm config set --workspace <slug>)');
+      process.exit(1);
+    }
 
-    if (opts.scope === 'admin') {
-      if (!opts.workspace) {
-        console.error('Error: --workspace <slug> is required for scope=admin');
-        process.exit(1);
-      }
-      body.workspace = opts.workspace;
+    const body = { name: opts.name, scope: opts.scope, workspace };
 
+    if (opts.scope === 'admin') {
       let adminPw = opts.adminPassword;
       if (!adminPw) {
         adminPw = await promptSecret('Admin password: ');
@@ -242,6 +263,64 @@ program
     }
   });
 
+// ============================================================
+// WORKSPACE COMMANDS
+// ============================================================
+
+const workspaceCmd = program.command('workspace').description('Manage CRM workspaces');
+
+workspaceCmd
+  .command('init')
+  .description('Bootstrap a new workspace: register slug + create API key, save to config')
+  .requiredOption('--workspace <slug>', 'Workspace slug (3-50 chars, a-z0-9/dash/underscore)')
+  .requiredOption('--name <keyname>', 'Name/label for the initial API key')
+  .option('--scope <scope>', 'Key scope: agent (default) or admin', 'agent')
+  .option('--admin-password <password>', 'Admin password (required for scope=admin; will prompt if not provided)')
+  .option('--save-key', 'Save the returned key to CLI config (default: true)', true)
+  .action(async (opts) => {
+    const globalOpts = program.opts();
+    const apiUrl = resolveApiUrl(globalOpts.url);
+    if (!apiUrl) {
+      console.error('Error: API URL not configured. Run: saac_crm config set --url <api-url>');
+      process.exit(1);
+    }
+
+    const body = {
+      workspace: opts.workspace.trim().toLowerCase(),
+      key_name: opts.name,
+      scope: opts.scope
+    };
+
+    if (opts.scope === 'admin') {
+      let adminPw = opts.adminPassword;
+      if (!adminPw) {
+        adminPw = await promptSecret('Admin password: ');
+      }
+      body.admin_password = adminPw;
+    }
+
+    try {
+      const res = await axios.post(
+        `${apiUrl.replace(/\/$/, '')}/api/v1/workspaces/register`,
+        body,
+        { headers: { 'Content-Type': 'application/json' } }
+      );
+      const data = res.data.data;
+      console.log(`Workspace '${data.workspace}' initialized. API key created.`);
+      console.log('Store the key — it will not be shown again.');
+      printJSON(data);
+
+      // Auto-save to config
+      const cfg = loadConfig();
+      cfg.apiKey = data.key;
+      cfg.workspace = data.workspace;
+      saveConfig(cfg);
+      console.log(`\nKey and workspace saved to config: ${CONFIG_FILE}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
 keysCmd
   .command('list')
   .description('List all API keys (metadata only)')
@@ -307,9 +386,11 @@ leadsCmd
   .option('--tag <tag>', 'Tag (repeatable)', (v, prev) => prev.concat([v]), [])
   .option('--external-id <externalId>', 'External ID')
   .option('--idempotency-key <key>', 'Idempotency key for deduplication')
+  .option('--from-agent-name <name>', 'Agent name for attribution (falls back to config defaultAgentName)')
   .action(async (opts) => {
     const globalOpts = program.opts();
-    const client = getClient(globalOpts);
+    const agentName = resolveAgentName(opts.fromAgentName);
+    const client = getClient(globalOpts, agentName);
     const headers = {};
     if (opts.idempotencyKey) headers['Idempotency-Key'] = opts.idempotencyKey;
     const body = {
@@ -624,9 +705,11 @@ contactsCmd
   .option('--tags <tags>', 'Comma-separated tags')
   .option('--do-not-contact', 'Mark as do not contact')
   .option('--notes <notes>', 'Notes')
+  .option('--from-agent-name <name>', 'Agent name for attribution (falls back to config defaultAgentName)')
   .action(async (opts) => {
     const globalOpts = program.opts();
-    const client = getClient(globalOpts);
+    const agentName = resolveAgentName(opts.fromAgentName);
+    const client = getClient(globalOpts, agentName);
     try {
       const body = {
         first_name: opts.firstName,
@@ -780,9 +863,11 @@ callsCmd
   .option('--duration <seconds>', 'Duration in seconds')
   .option('--notes <notes>', 'Call notes')
   .option('--call-time <iso>', 'Call time (ISO8601, defaults to now)')
+  .option('--from-agent-name <name>', 'Agent name for attribution (falls back to config defaultAgentName)')
   .action(async (opts) => {
     const globalOpts = program.opts();
-    const client = getClient(globalOpts);
+    const agentName = resolveAgentName(opts.fromAgentName);
+    const client = getClient(globalOpts, agentName);
     try {
       const body = { direction: opts.direction };
       if (opts.leadId) body.lead_id = opts.leadId;
@@ -948,9 +1033,11 @@ meetingsCmd
   .option('--notes <notes>', 'Meeting notes or agenda')
   .option('--outcome <outcome>', 'scheduled | completed | cancelled | no_show')
   .option('--sentiment <sentiment>', 'positive | neutral | negative | unknown')
+  .option('--from-agent-name <name>', 'Agent name for attribution (falls back to config defaultAgentName)')
   .action(async (opts) => {
     const globalOpts = program.opts();
-    const client = getClient(globalOpts);
+    const agentName = resolveAgentName(opts.fromAgentName);
+    const client = getClient(globalOpts, agentName);
     try {
       const body = {
         title: opts.title,
@@ -1078,9 +1165,11 @@ emailsCmd
   .option('--body-summary <summary>', 'Body summary (max 1000 chars)')
   .option('--thread-id <id>', 'Thread ID for grouping related emails')
   .option('--email-timestamp <iso>', 'When the email was sent/received (ISO8601, defaults to now)')
+  .option('--from-agent-name <name>', 'Agent name for attribution (falls back to config defaultAgentName)')
   .action(async (opts) => {
     const globalOpts = program.opts();
-    const client = getClient(globalOpts);
+    const agentName = resolveAgentName(opts.fromAgentName);
+    const client = getClient(globalOpts, agentName);
     try {
       const body = {
         direction: opts.direction,
@@ -1171,9 +1260,11 @@ quotesCmd
   .option('--currency <code>', 'Currency code (default: USD)')
   .option('--validity-date <date>', 'Validity date (YYYY-MM-DD)')
   .option('--notes <notes>', 'Notes')
+  .option('--from-agent-name <name>', 'Agent name for attribution (falls back to config defaultAgentName)')
   .action(async (opts) => {
     const globalOpts = program.opts();
-    const client = getClient(globalOpts);
+    const agentName = resolveAgentName(opts.fromAgentName);
+    const client = getClient(globalOpts, agentName);
     try {
 
       const res = await client.post('/quotes', {
@@ -1185,7 +1276,7 @@ quotesCmd
         notes: opts.notes
       });
       printJSON(res.data);
-  
+
     } catch (err) {
       handleError(err);
     }
@@ -1396,9 +1487,11 @@ contractsCmd
   .option('--end-date <date>', 'End date (YYYY-MM-DD)')
   .option('--document-url <url>', 'Document URL reference')
   .option('--notes <notes>', 'Notes')
+  .option('--from-agent-name <name>', 'Agent name for attribution (falls back to config defaultAgentName)')
   .action(async (opts) => {
     const globalOpts = program.opts();
-    const client = getClient(globalOpts);
+    const agentName = resolveAgentName(opts.fromAgentName);
+    const client = getClient(globalOpts, agentName);
     try {
 
       const res = await client.post('/contracts', {
@@ -1414,7 +1507,7 @@ contractsCmd
         notes: opts.notes
       });
       printJSON(res.data);
-  
+
     } catch (err) {
       handleError(err);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startanaicompany/crm",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "AI-first CRM CLI \u2014 manage leads and API keys from the terminal",
   "main": "index.js",
   "bin": {