salesprompter-cli 0.1.2 → 0.1.4

package/README.md

@@ -12,6 +12,80 @@
 - Analyze upstream lead-list and domain-enrichment bottlenecks
 - Replace opaque Pipedream logic with deterministic CLI workflows
 
+It is built for two users at the same time:
+
+- humans working in a terminal
+- coding agents such as Codex, Claude Code, and other LLM-driven shell workflows
+
+## Start Here
+
+If someone discovers Salesprompter from a vague prompt, the first thing they need is the shortest working path.
+
+```bash
+npx salesprompter-cli@latest --help
+```
+
+Or install it globally:
+
+```bash
+npm install -g salesprompter-cli
+salesprompter --help
+```
+
+## Prompt To Command
+
+If the user says something like "I need to determine the ICP of deel.com", there are two different meanings.
+
+### 1. They want leads at Deel itself
+
+This means Deel is the target account.
+
+```bash
+salesprompter account:resolve --domain deel.com --company-name Deel --out ./data/deel-account.json
+salesprompter leads:generate --icp ./data/icp.json --count 5 --domain deel.com --company-name Deel --out ./data/deel-leads.json
+```
+
+### 2. They sell for Deel and need Deel's ideal customer profile
+
+This means Deel is the vendor, not the target account.
+
+```bash
+salesprompter icp:vendor --vendor deel --market dach --out ./data/deel-icp.json
+salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --execute --out ./data/deel-leads-raw.json --lead-out ./data/deel-leads.json
+salesprompter leads:enrich --in ./data/deel-leads.json --out ./data/deel-enriched.json
+salesprompter leads:score --icp ./data/deel-icp.json --in ./data/deel-enriched.json --out ./data/deel-scored.json
+```
+
+### 3. They want the LLM to call the CLI directly
+
+Use the same commands, but prefer machine-readable output:
+
+```bash
+salesprompter --json icp:vendor --vendor deel --market dach --out ./data/deel-icp.json
+salesprompter --json leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --lead-out ./data/deel-leads.json
+```
+
+## Documentation
+
+This repository now includes a Mintlify docs site for the wider Salesprompter universe, including the app contract, CLI surface, Chrome extension contract, and the main warehouse-backed workflows.
+
+- Docs home: `./index.mdx`
+- Quickstart: `./quickstart.mdx`
+- Architecture: `./architecture.mdx`
+- App: `./platform/app.mdx`
+- CLI: `./platform/cli.mdx`
+- Chrome extension: `./platform/chrome-extension.mdx`
+- Domain finder: `./workflows/domain-finder.mdx`
+- Command reference: `./reference/cli.mdx`
+- Environment variables: `./reference/environment-variables.mdx`
+- Troubleshooting: `./operations/troubleshooting.mdx`
+
+Run the docs locally with:
+
+```bash
+npm run docs:dev
+```
+
 ## Integration Contract
 
 This CLI is not a standalone toy. It is a production integration surface for the Salesprompter app.
@@ -39,11 +113,11 @@ Global output flags:
 The CLI stores a local session file at `~/.config/salesprompter/auth-session.json` (or `SALESPROMPTER_CONFIG_DIR`).
 
 ```bash
-# Device flow through Salesprompter backend (recommended)
-salesprompter auth:login
+# Production path: generate a short-lived CLI token in the Salesprompter app
+salesprompter auth:login --token "$SALESPROMPTER_TOKEN" --api-url "https://salesprompter.ai"
 
-# Direct login using app-issued bearer token
-salesprompter auth:login --token "$SALESPROMPTER_TOKEN"
+# Optional: use device flow only if your Salesprompter app exposes it
+salesprompter auth:login
 
 # Verify active identity with backend
 salesprompter auth:whoami --verify
@@ -54,7 +128,7 @@ salesprompter auth:logout
 
 Environment variables:
 
-- `SALESPROMPTER_API_BASE_URL`: override backend URL (default `https://app.salesprompter.com`)
+- `SALESPROMPTER_API_BASE_URL`: override backend URL (default `https://salesprompter.ai`)
 - `SALESPROMPTER_CONFIG_DIR`: override local config dir
 - `SALESPROMPTER_SKIP_AUTH=1`: bypass auth guard (tests/dev only)
 - `INSTANTLY_API_KEY`: required for real `sync:outreach --target instantly`
@@ -63,17 +137,19 @@ Environment variables:
 
 App compatibility:
 
-- If your app exposes `/api/cli/auth/device/start` and `/api/cli/auth/device/poll`, use `salesprompter auth:login`.
+- Current Salesprompter production uses app-issued CLI tokens.
+- If your app exposes `/api/cli/auth/device/start` and `/api/cli/auth/device/poll`, `salesprompter auth:login` will use device flow.
 - If device auth is not enabled, create a CLI token from the app endpoint `POST /api/cli/auth/token` and use:
 
 ```bash
-salesprompter auth:login --token "<token-from-app>"
+salesprompter auth:login --token "<token-from-app>" --api-url "https://salesprompter.ai"
 ```
 
 ## Why this shape works for humans and LLMs
 
 - Every command reads and writes plain JSON.
 - Output is machine-readable and composable (`--json` for compact transport).
+- The top-level use cases map ambiguous prompts like "determine the ICP of deel.com" into explicit command paths.
 - Domain contracts are explicit and validated with `zod`.
 - External integrations are behind narrow provider interfaces.
 - Lead generation reports which provider and mode produced the result.

package/dist/auth.js

@@ -2,7 +2,7 @@ import os from "node:os";
 import path from "node:path";
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { z } from "zod";
-const DEFAULT_API_BASE_URL = "https://app.salesprompter.com";
+const DEFAULT_API_BASE_URL = "https://salesprompter.ai";
 const CLIENT_HEADER = "salesprompter-cli/0.2";
 const DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 3;
 const DEFAULT_DEVICE_TIMEOUT_SECONDS = 180;
@@ -94,6 +94,18 @@ function normalizeApiBaseUrl(apiBaseUrl) {
     const value = (apiBaseUrl ?? process.env.SALESPROMPTER_API_BASE_URL ?? DEFAULT_API_BASE_URL).trim();
     return value.replace(/\/+$/, "");
 }
+function isDeviceFlowUnavailableError(message) {
+    if (message.includes("invalid JSON response")) {
+        return true;
+    }
+    return /request failed \((401|403|404|405|500|501|502|503|504)\)/.test(message);
+}
+function buildDeviceFlowUnavailableMessage(apiBaseUrl) {
+    return [
+        "device login is not configured on this Salesprompter app.",
+        `Generate a CLI token in the app and run \`salesprompter auth:login --token <token> --api-url "${apiBaseUrl}"\`.`
+    ].join(" ");
+}
 async function hasSessionFile() {
     try {
         await access(getSessionPath());
@@ -106,7 +118,18 @@ async function hasSessionFile() {
 async function httpJson(url, init, schema) {
     const response = await fetch(url, init);
     const text = await response.text();
-    const payload = text.length > 0 ? JSON.parse(text) : {};
+    let payload = {};
+    if (text.length > 0) {
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            if (!response.ok) {
+                throw new Error(`request failed (${response.status}) for ${url}`);
+            }
+            throw new Error(`invalid JSON response for ${url}`);
+        }
+    }
     if (!response.ok) {
         throw new Error(`request failed (${response.status}) for ${url}`);
     }
@@ -195,8 +218,8 @@ export async function loginWithDeviceFlow(options) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("(404)")) {
-            throw new Error("device login is not configured on this Salesprompter app. Generate a CLI token in the app and run `salesprompter auth:login --token <token>`.");
+        if (isDeviceFlowUnavailableError(message)) {
+            throw new Error(buildDeviceFlowUnavailableMessage(apiBaseUrl));
         }
         throw error;
     }

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { Command } from "commander";
 import { z } from "zod";
 import { clearAuthSession, loginWithDeviceFlow, loginWithToken, requireAuthSession, shouldBypassAuth, verifySession } from "./auth.js";
@@ -11,6 +12,8 @@ import { buildHistoricalVendorIcp, buildVendorIcp } from "./icp-templates.js";
 import { InstantlySyncProvider } from "./instantly.js";
 import { buildLeadlistsFunnelQueries } from "./leadlists-funnel.js";
 import { readJsonFile, splitCsv, writeJsonFile, writeTextFile } from "./io.js";
+const require = createRequire(import.meta.url);
+const { version: packageVersion } = require("../package.json");
 const program = new Command();
 const leadProvider = new AccountLeadProvider(new HeuristicCompanyProvider(), new HeuristicPeopleSearchProvider());
 const enrichmentProvider = new HeuristicEnrichmentProvider();
@@ -166,14 +169,14 @@ async function fetchHistoricalQueryRows(tables) {
 program
     .name("salesprompter")
     .description("Sales workflow CLI for ICP definition, lead generation, enrichment, scoring, and sync.")
-    .version("0.1.1")
+    .version(packageVersion)
     .option("--json", "Emit compact machine-readable JSON output", false)
     .option("--quiet", "Suppress successful stdout output", false);
 program
     .command("auth:login")
-    .description("Authenticate CLI with Salesprompter app credentials.")
+    .description("Authenticate CLI with a Salesprompter app token, or device flow if the app supports it.")
     .option("--token <token>", "App-issued bearer token for direct login")
-    .option("--api-url <url>", "Salesprompter API base URL, defaults to SALESPROMPTER_API_BASE_URL or app.salesprompter.com")
+    .option("--api-url <url>", "Salesprompter API base URL, defaults to SALESPROMPTER_API_BASE_URL or salesprompter.ai")
     .option("--timeout-seconds <number>", "Device flow wait timeout in seconds", "180")
     .action(async (options) => {
     const timeoutSeconds = z.coerce.number().int().min(30).max(1800).parse(options.timeoutSeconds);
@@ -190,7 +193,9 @@ program
         return;
     }
     const startedAt = new Date().toISOString();
-    process.stderr.write("Starting device login flow. Complete login in the browser.\n");
+    if (!runtimeOutputOptions.json && !runtimeOutputOptions.quiet) {
+        process.stderr.write("Starting device login flow. Complete login in the browser.\n");
+    }
     const result = await loginWithDeviceFlow({
         apiBaseUrl: options.apiUrl,
         timeoutSeconds

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "salesprompter-cli",
-  "version": "0.1.2",
-  "description": "CLI for defining ICPs, generating leads, enriching them, scoring them, and syncing to GTM tools.",
+  "version": "0.1.4",
+  "description": "JSON-first sales prospecting CLI for ICP definition, lead generation, enrichment, scoring, and CRM/outreach sync.",
   "type": "module",
   "bin": {
     "salesprompter": "dist/cli.js"
@@ -13,16 +13,39 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check": "tsc --noEmit -p tsconfig.json",
+    "docs:dev": "mint dev",
+    "docs:broken-links": "mint broken-links",
+    "docs:a11y": "mint a11y",
     "start": "node ./dist/cli.js",
     "test": "npm run build && tsc -p tsconfig.test.json && node --test dist-tests/tests/**/*.test.js"
   },
   "keywords": [
     "sales",
+    "salesprompter",
     "cli",
+    "icp",
+    "ideal-customer-profile",
+    "prospecting",
     "lead-generation",
+    "lead-enrichment",
+    "lead-scoring",
+    "sales-intelligence",
     "crm",
-    "outreach"
+    "outreach",
+    "instantly",
+    "hubspot",
+    "llm",
+    "ai-agent",
+    "codex"
   ],
+  "homepage": "https://salesprompter.ai/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danielsinewe/salesprompter-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/danielsinewe/salesprompter-cli/issues"
+  },
   "license": "MIT",
   "dependencies": {
     "commander": "^14.0.1",
@@ -30,6 +53,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
+    "mint": "^4.2.420",
     "typescript": "^5.9.2"
   }
 }