salesprompter-cli 0.1.3 → 0.1.5

package/README.md

@@ -12,6 +12,59 @@
 - 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.
@@ -24,6 +77,8 @@ This repository now includes a Mintlify docs site for the wider Salesprompter un
 - 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:
 
@@ -58,12 +113,12 @@ Global output flags:
 The CLI stores a local session file at `~/.config/salesprompter/auth-session.json` (or `SALESPROMPTER_CONFIG_DIR`).
 
 ```bash
-# Production path: generate a short-lived CLI token in the Salesprompter app
-salesprompter auth:login --token "$SALESPROMPTER_TOKEN" --api-url "https://salesprompter.ai"
-
-# Optional: use device flow only if your Salesprompter app exposes it
+# Preferred path: browser/device login
 salesprompter auth:login
 
+# Fallback path: generate a short-lived CLI token in the Salesprompter app
+salesprompter auth:login --token "$SALESPROMPTER_TOKEN" --api-url "https://salesprompter.ai"
+
 # Verify active identity with backend
 salesprompter auth:whoami --verify
 
@@ -82,9 +137,11 @@ Environment variables:
 
 App compatibility:
 
-- 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:
+- Salesprompter app should expose `/api/cli/auth/device/start`, `/api/cli/auth/device/poll`, and `/api/cli/auth/me`.
+- `salesprompter auth:login` uses browser/device login and prints the verification URL plus code before polling.
+- `POST /api/cli/auth/token` remains the fallback path when browser/device login is disabled or unavailable.
+
+Fallback command:
 
 ```bash
 salesprompter auth:login --token "<token-from-app>" --api-url "https://salesprompter.ai"
@@ -94,6 +151,7 @@ salesprompter auth:login --token "<token-from-app>" --api-url "https://salesprom
 
 - 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

@@ -1,3 +1,5 @@
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
 import os from "node:os";
 import path from "node:path";
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
@@ -106,6 +108,12 @@ function buildDeviceFlowUnavailableMessage(apiBaseUrl) {
         `Generate a CLI token in the app and run \`salesprompter auth:login --token <token> --api-url "${apiBaseUrl}"\`.`
     ].join(" ");
 }
+function isBrowserConnectUnavailableError(message) {
+    if (/request failed \((401|403|404|405|500|501|502|503|504)\)/.test(message)) {
+        return true;
+    }
+    return message.includes("invalid localhost callback response");
+}
 async function hasSessionFile() {
     try {
         await access(getSessionPath());
@@ -202,6 +210,99 @@ export async function loginWithToken(token, apiBaseUrl) {
     await writeAuthSession(session);
     return session;
 }
+export async function loginWithBrowserConnect(options) {
+    const apiBaseUrl = normalizeApiBaseUrl(options?.apiBaseUrl);
+    const timeoutSeconds = options?.timeoutSeconds ?? DEFAULT_DEVICE_TIMEOUT_SECONDS;
+    const state = randomBytes(16).toString("hex");
+    let resolveToken;
+    let rejectToken;
+    const tokenPromise = new Promise((resolve, reject) => {
+        resolveToken = resolve;
+        rejectToken = reject;
+    });
+    const server = createServer((request, response) => {
+        try {
+            const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+            if (requestUrl.pathname !== "/callback") {
+                response.statusCode = 404;
+                response.end("Not found");
+                return;
+            }
+            const accessToken = requestUrl.searchParams.get("access_token") ?? "";
+            const responseState = requestUrl.searchParams.get("state") ?? "";
+            if (accessToken.trim().length === 0 || responseState.trim().length === 0) {
+                response.statusCode = 400;
+                response.end("Invalid login response");
+                return;
+            }
+            response.statusCode = 200;
+            response.setHeader("Content-Type", "text/html; charset=utf-8");
+            response.end("<!doctype html><html><body><p>Salesprompter CLI login complete. You can return to the terminal.</p></body></html>");
+            resolveToken?.({ accessToken, state: responseState });
+        }
+        catch (error) {
+            response.statusCode = 500;
+            response.end("Login failed");
+            rejectToken?.(error);
+        }
+    });
+    server.once("error", (error) => {
+        rejectToken?.(error);
+    });
+    await new Promise((resolve, reject) => {
+        server.listen(0, "127.0.0.1", () => resolve());
+        server.once("error", reject);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        server.close();
+        throw new Error("failed to bind localhost callback server");
+    }
+    const redirectUri = `http://127.0.0.1:${address.port}/callback`;
+    const closeServer = async () => await new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+    const browserUrl = new URL(`${apiBaseUrl}/api/cli/auth/connect`);
+    browserUrl.searchParams.set("redirect_uri", redirectUri);
+    browserUrl.searchParams.set("state", state);
+    let preflightResponse;
+    try {
+        preflightResponse = await fetch(browserUrl, {
+            method: "GET",
+            redirect: "manual",
+            headers: {
+                "X-Salesprompter-Client": CLIENT_HEADER
+            }
+        });
+    }
+    catch (error) {
+        await closeServer();
+        throw error;
+    }
+    if (preflightResponse.status < 300 || preflightResponse.status >= 400) {
+        await closeServer();
+        throw new Error(`request failed (${preflightResponse.status}) for ${browserUrl}`);
+    }
+    await options?.onConnectStart?.({
+        browserUrl: browserUrl.toString(),
+        redirectUri
+    });
+    const timeoutHandle = setTimeout(() => {
+        rejectToken?.(new Error("timed out waiting for browser login"));
+    }, Math.max(timeoutSeconds, 30) * 1000);
+    let result;
+    try {
+        result = await tokenPromise;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+        await closeServer();
+    }
+    if (result.state !== state) {
+        throw new Error("invalid localhost callback response");
+    }
+    return await loginWithToken(result.accessToken, apiBaseUrl);
+}
 export async function loginWithDeviceFlow(options) {
     const apiBaseUrl = normalizeApiBaseUrl(options?.apiBaseUrl);
     const timeoutSeconds = options?.timeoutSeconds ?? DEFAULT_DEVICE_TIMEOUT_SECONDS;
@@ -227,6 +328,12 @@ export async function loginWithDeviceFlow(options) {
     if (verificationUrl === undefined) {
         throw new Error("device start response missing verification url");
     }
+    await options?.onDeviceStart?.({
+        verificationUrl,
+        userCode: start.userCode,
+        intervalSeconds: start.intervalSeconds,
+        expiresInSeconds: start.expiresInSeconds
+    });
     const pollIntervalMs = (start.intervalSeconds ?? DEFAULT_DEVICE_POLL_INTERVAL_SECONDS) * 1000;
     const deadline = Date.now() + Math.max(timeoutSeconds, 30) * 1000;
     while (Date.now() < deadline) {

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import { z } from "zod";
-import { clearAuthSession, loginWithDeviceFlow, loginWithToken, requireAuthSession, shouldBypassAuth, verifySession } from "./auth.js";
+import { clearAuthSession, loginWithBrowserConnect, loginWithDeviceFlow, loginWithToken, requireAuthSession, shouldBypassAuth, verifySession } from "./auth.js";
 import { buildBigQueryLeadLookupSql, executeBigQuerySql, normalizeBigQueryLeadRows, runBigQueryQuery, runBigQueryRows } from "./bigquery.js";
 import { AccountProfileSchema, EnrichedLeadSchema, IcpSchema, LeadSchema, ScoredLeadSchema, SyncTargetSchema } from "./domain.js";
 import { auditDomainDecisions, buildDomainfinderBacklogQueries, buildDomainfinderCandidatesSql, buildDomainfinderInputSql, buildDomainfinderWritebackSql, buildExistingDomainRepairSql, buildExistingDomainAuditQueries, compareDomainSelectionStrategies, selectBestDomains } from "./domainfinder.js";
@@ -35,6 +36,59 @@ function applyGlobalOutputOptions(actionCommand) {
     runtimeOutputOptions.json = Boolean(globalOptions.json);
     runtimeOutputOptions.quiet = Boolean(globalOptions.quiet);
 }
+function openUrlInBrowser(url) {
+    if (!process.stderr.isTTY) {
+        return false;
+    }
+    const launch = (command, args) => {
+        try {
+            const child = spawn(command, args, { detached: true, stdio: "ignore" });
+            child.on("error", () => undefined);
+            child.unref();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    try {
+        if (process.platform === "darwin") {
+            return launch("open", [url]);
+        }
+        if (process.platform === "win32") {
+            return launch("cmd", ["/c", "start", "", url]);
+        }
+        return launch("xdg-open", [url]);
+    }
+    catch {
+        return false;
+    }
+}
+function writeDeviceLoginInstructions(info) {
+    if (runtimeOutputOptions.json || runtimeOutputOptions.quiet) {
+        return;
+    }
+    process.stderr.write("Starting device login flow. Complete login in the browser.\n");
+    process.stderr.write(`Open this URL: ${info.verificationUrl}\n`);
+    process.stderr.write(`Enter this code if prompted: ${info.userCode}\n`);
+    if (info.expiresInSeconds !== undefined) {
+        const expiresInMinutes = Math.max(1, Math.ceil(info.expiresInSeconds / 60));
+        process.stderr.write(`Code expires in about ${expiresInMinutes} minute${expiresInMinutes === 1 ? "" : "s"}.\n`);
+    }
+    if (openUrlInBrowser(info.verificationUrl)) {
+        process.stderr.write("Opened the browser for you.\n");
+    }
+}
+function writeBrowserLoginInstructions(info) {
+    if (runtimeOutputOptions.json || runtimeOutputOptions.quiet) {
+        return;
+    }
+    process.stderr.write("Starting browser login flow. Complete login in the browser.\n");
+    process.stderr.write(`Open this URL: ${info.browserUrl}\n`);
+    if (openUrlInBrowser(info.browserUrl)) {
+        process.stderr.write("Opened the browser for you.\n");
+    }
+}
 function buildCliError(error) {
     if (error instanceof z.ZodError) {
         return {
@@ -193,12 +247,35 @@ program
         return;
     }
     const startedAt = new Date().toISOString();
-    if (!runtimeOutputOptions.json && !runtimeOutputOptions.quiet) {
-        process.stderr.write("Starting device login flow. Complete login in the browser.\n");
+    try {
+        const session = await loginWithBrowserConnect({
+            apiBaseUrl: options.apiUrl,
+            timeoutSeconds,
+            onConnectStart: writeBrowserLoginInstructions
+        });
+        printOutput({
+            status: "ok",
+            method: "browser",
+            startedAt,
+            apiBaseUrl: session.apiBaseUrl,
+            user: session.user,
+            expiresAt: session.expiresAt ?? null
+        });
+        return;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!message.includes("timed out waiting for browser login") && !message.includes("invalid localhost callback response") && !message.includes("request failed")) {
+            throw error;
+        }
+        if (!/request failed \((401|403|404|405|500|501|502|503|504)\)/.test(message)) {
+            throw error;
+        }
     }
     const result = await loginWithDeviceFlow({
         apiBaseUrl: options.apiUrl,
-        timeoutSeconds
+        timeoutSeconds,
+        onDeviceStart: writeDeviceLoginInstructions
     });
     printOutput({
         status: "ok",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "salesprompter-cli",
-  "version": "0.1.3",
-  "description": "CLI for defining ICPs, generating leads, enriching them, scoring them, and syncing to GTM tools.",
+  "version": "0.1.5",
+  "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,19 +13,39 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check": "tsc --noEmit -p tsconfig.json",
-    "docs:dev": "npx mint dev",
-    "docs:broken-links": "npx mint broken-links",
-    "docs:a11y": "npx mint a11y",
+    "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",
@@ -33,6 +53,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
+    "mint": "^4.2.420",
     "typescript": "^5.9.2"
   }
 }