@floomhq/signaldash 0.1.0 → 0.3.0

package/README.md

@@ -2,59 +2,52 @@
 
 Secure LinkedIn and WhatsApp access for AI agents.
 
-`@floomhq/signaldash` connects your own accounts through Unipile and exposes
-six account-scoped MCP tools. There is no email integration, CRM cockpit,
-signals engine, campaigns layer, sync database, or web UI in this package.
+`@floomhq/signaldash` connects your accounts through the hosted SignalDash
+service and exposes six account-scoped MCP tools. The CLI never receives or
+stores the server's Unipile access key.
 
-## Connect
+## Quickstart
 
-SignalDash requires Node.js 20+ and a Unipile account. In the
-[Unipile dashboard](https://developer.unipile.com/docs/getting-started), copy
-your DSN and generate an Access Token. The API URL is your DSN followed by
-`/api/v1`.
+You need Node.js 20 or newer and a single-use SignalDash invite code. Ask the
+SignalDash administrator for an invite code, then run:
 
 ```bash
-export SIGNALDASH_UNIPILE_BASE="https://apiXXX.unipile.com:XXXXX/api/v1"
-export SIGNALDASH_UNIPILE_KEY="..."
-
+npx -y @floomhq/signaldash login <invite-code>
 npx -y @floomhq/signaldash connect linkedin
 npx -y @floomhq/signaldash connect whatsapp
 ```
 
-Each command creates a short-lived
-[Unipile hosted-auth](https://developer.unipile.com/docs/hosted-auth) URL.
-Open it to complete LinkedIn login or scan the live WhatsApp QR, then return
-to the terminal. SignalDash verifies the account through `GET /accounts` and
-stores its account ID.
-
-Without environment variables, run either command in a terminal. SignalDash
-prompts for the API URL and hides API-key input.
-
-Credentials live under `~/.signaldash` by default:
+Each connect command prints a short-lived hosted-auth URL and waits for the
+connection to finish. Open the LinkedIn URL and sign in, or open the WhatsApp
+URL and scan the live QR code. The CLI prints `Connected linkedin` or
+`Connected whatsapp` when the account is ready.
 
-- `device.key`: local 256-bit encryption key, mode `0600`
-- `secrets.enc`: AES-256-GCM credential envelope, mode `0600`
-- `config.json`: non-secret account references, mode `0600`
+The invite code is single-use. Login stores a SignalDash user token in
+`~/.signaldash/config.json`; the Unipile access key remains on the SignalDash
+server. Set `SIGNALDASH_HOME` to keep the local config in another directory.
 
-The Unipile key is never written to config, printed, returned by an MCP tool,
-or passed to an MCP caller. Set `SIGNALDASH_HOME` to use another workspace.
-
-## MCP
+If automatic account detection times out, the CLI prints the manual claim
+command for the provider:
 
 ```bash
-npx -y @floomhq/signaldash mcp
+npx -y @floomhq/signaldash connect linkedin claim <account_id>
 ```
 
-The command starts a stdio MCP server. Its one-line registration hint is
-written to stderr so stdout remains valid JSON-RPC.
+## Add SignalDash to your agent
+
+### Claude Code
 
-Claude Code:
+Paste this command into a terminal:
 
 ```bash
 claude mcp add signaldash -- npx -y @floomhq/signaldash mcp
 ```
 
-Cursor, `.cursor/mcp.json`:
+### Cursor
+
+Create or update `.cursor/mcp.json` in the project. Merge the `signaldash`
+entry into an existing `mcpServers` object when the file already contains
+other servers:
 
 ```json
 {
@@ -67,49 +60,57 @@ Cursor, `.cursor/mcp.json`:
 }
 ```
 
-The entire MCP surface is:
+Both registrations start the same stdio server:
+
+```bash
+npx -y @floomhq/signaldash mcp
+```
+
+The MCP server uses the user token created by `login`. It cannot access a
+LinkedIn or WhatsApp account until that channel has been connected for the
+same logged-in user.
+
+## Give the agent the safety skill
+
+Before allowing the agent to send messages, give it the bundled
+[`signaldash-safe-usage` skill](skills/signaldash-safe-usage/SKILL.md). The
+skill requires the agent to resolve the exact chat, read recent thread
+history, check for duplicates, and obtain approval when the recipient or text
+has not already been approved.
+
+The MCP registration does not automatically load the skill yet. Copy
+`skills/signaldash-safe-usage/SKILL.md` into the agent's skills directory or
+attach its contents to the agent instructions. Keep this requirement in both
+Claude Code and Cursor.
+
+## MCP tools
+
+SignalDash exposes:
 
 - `li_list_chats`
-- `li_read_messages(chat)`
-- `li_send_message(chat, text)`
+- `li_read_messages(chat_id)`
+- `li_send_message(chat_id, text)`
 - `wa_list_chats`
-- `wa_read_messages(chat)`
-- `wa_send_message(chat, text)`
-
-Every read and send verifies that the chat belongs to the configured account.
-List tools use chat-list endpoints only and never fetch profiles.
-
-## Safety is a feature
-
-The package includes
-[`skills/signaldash-safe-usage/SKILL.md`](skills/signaldash-safe-usage/SKILL.md).
-Install or give that skill to the agent using SignalDash.
-
-The runtime also enforces non-configurable safeguards:
-
-- LinkedIn: 18 send attempts per account per UTC day; 45 to 90 seconds
-  between sends.
-- WhatsApp: 30 send attempts per account per UTC day; 15 to 35 seconds
-  between sends.
-- The first send also receives randomized pre-send jitter.
-- Every send re-reads the recent thread and blocks an exact duplicate.
-- Provider warning headers, checkpoints, restrictions, HTTP 403, and HTTP 429
-  fail closed and persistently disable sends for that account.
-- A file lock serializes sends across concurrent MCP processes.
-
-LinkedIn invitation ceilings vary by account and often appear around 100 per
-week. SignalDash exposes no invitation tool. Keep invitation automation out
-of agent loops.
-
-Avoid bulk profile reads, copied message bursts, cold-account automation, and
-repeated retries after a checkpoint. Let the agent act slowly and human-like.
-On WhatsApp, use established accounts, keep the phone online, and avoid bulk
-or unsolicited messaging.
-
-After a provider warning, stop. Review the provider account manually and wait
-for it to return to good standing. The warning lock is recorded in
-`~/.signaldash/safety/send-state.json`; only a human may clear the relevant
-account entry after resolving the restriction.
+- `wa_read_messages(chat_id)`
+- `wa_send_message(chat_id, text)`
+
+Every operation runs through the hosted SignalDash backend. Agents never
+receive the Unipile access key.
+
+## Safety limits
+
+SignalDash enforces a daily send cap. The safe-usage skill adds the human
+workflow around that runtime control:
+
+- Read the exact thread before every send.
+- Never infer a recipient from a partial name.
+- Never send a duplicate or retry an ambiguous timeout without re-reading.
+- Do not parallelize sends or work around a rate limit.
+- Stop on a provider warning, checkpoint, restriction, HTTP 403, or HTTP 429.
+- Avoid bulk profile reads, copied message bursts, cold-account automation,
+  and unsolicited WhatsApp messaging.
+
+SignalDash exposes no LinkedIn invitation tool.
 
 ## Development
 

package/bin/sd.mjs

@@ -3,48 +3,109 @@
 // bearer token. Never holds a Unipile key, never calls Unipile directly. The MCP
 // tools an agent uses all proxy through the backend, so agents access channels
 // THROUGH SignalDash, not around it.
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, realpathSync, writeFileSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 
-const CFG_DIR = process.env.SIGNALDASH_HOME || `${homedir()}/.signaldash`;
-const CFG = `${CFG_DIR}/config.json`;
 const DEFAULT_BACKEND = process.env.SIGNALDASH_BACKEND || "https://signaldash-api.floom.dev";
 
-function loadCfg() { try { return JSON.parse(readFileSync(CFG, "utf8")); } catch { return {}; } }
-function saveCfg(c) { mkdirSync(CFG_DIR, { recursive: true }); writeFileSync(CFG, JSON.stringify(c, null, 2), { mode: 0o600 }); }
+function configPaths() {
+  const directory = process.env.SIGNALDASH_HOME || `${homedir()}/.signaldash`;
+  return { directory, file: `${directory}/config.json` };
+}
+function loadCfg() {
+  try {
+    return JSON.parse(readFileSync(configPaths().file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveCfg(c) {
+  const config = configPaths();
+  mkdirSync(config.directory, { recursive: true });
+  writeFileSync(config.file, JSON.stringify(c, null, 2), { mode: 0o600 });
+}
 
-async function api(path, body, { auth = true } = {}) {
+async function api(path, body, { auth = true, method = "POST" } = {}) {
   const cfg = loadCfg();
   const backend = cfg.backend || DEFAULT_BACKEND;
   const r = await fetch(backend + path, {
-    method: "POST",
+    method,
     headers: { "Content-Type": "application/json", ...(auth && cfg.token ? { Authorization: `Bearer ${cfg.token}` } : {}) },
-    body: JSON.stringify(body || {}),
+    ...(method === "GET" ? {} : { body: JSON.stringify(body || {}) }),
   });
   return { status: r.status, json: await r.json().catch(() => ({})) };
 }
 
-async function cmdLogin(code, backend) {
+const wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+function positiveMilliseconds(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export async function cmdLogin(code, backend, dependencies = {}) {
+  const request = dependencies.request || api;
+  const log = dependencies.log || console.log;
+  const error = dependencies.error || console.error;
   const cfg = loadCfg();
   cfg.backend = backend || cfg.backend || DEFAULT_BACKEND;
   saveCfg(cfg);
-  const r = await api("/login", { code }, { auth: false });
-  if (r.status !== 200) { console.error("login failed:", r.json.error || r.status); process.exit(1); }
+  const r = await request("/login", { code }, { auth: false });
+  if (r.status !== 200) { error("login failed:", r.json.error || r.status); process.exitCode = 1; return; }
   cfg.token = r.json.token; saveCfg(cfg);
-  console.log("Logged in to SignalDash. Token stored (no channel keys on your side).");
+  log("Logged in to SignalDash. Token stored (no channel keys on your side).");
 }
 
-async function cmdConnect(provider) {
-  if (!["linkedin", "whatsapp"].includes(provider)) { console.error("usage: sd connect linkedin|whatsapp"); process.exit(1); }
-  const r = await api(`/connect/${provider}`, {});
-  if (r.status >= 300) { console.error("connect failed:", r.json.error || r.status); process.exit(1); }
-  console.log(`Open this to connect your ${provider}:\n\n  ${r.json.url}\n`);
-  console.log(`After authenticating, run:\n  sd connect ${provider} claim <account_id>`);
+export async function cmdConnect(provider, dependencies = {}) {
+  const request = dependencies.request || api;
+  const sleep = dependencies.wait || wait;
+  const now = dependencies.now || Date.now;
+  const log = dependencies.log || console.log;
+  const error = dependencies.error || console.error;
+  if (!["linkedin", "whatsapp"].includes(provider)) {
+    error("usage: signaldash connect linkedin|whatsapp");
+    process.exitCode = 1;
+    return;
+  }
+  const r = await request(`/connect/${provider}`, {});
+  if (r.status >= 300) {
+    error("connect failed:", r.json.error || r.status);
+    process.exitCode = 1;
+    return;
+  }
+  log(`Open this to connect your ${provider}:\n\n  ${r.json.url}\n`);
+  log("Waiting for authentication to complete...");
+
+  const timeoutMs = positiveMilliseconds("SIGNALDASH_CONNECT_TIMEOUT_MS", 5 * 60 * 1000);
+  const pollMs = positiveMilliseconds("SIGNALDASH_CONNECT_POLL_MS", 2000);
+  const deadline = now() + timeoutMs;
+  while (now() < deadline) {
+    const status = await request(`/connect/${provider}/status`, undefined, { method: "GET" });
+    if (status.status === 200 && status.json.connected) {
+      log(`Connected ${provider}${status.json.name ? `: ${status.json.name}` : ""}`);
+      return;
+    }
+    if (status.status !== 202) {
+      error("connect status failed:", status.json.error || status.status);
+      process.exitCode = 1;
+      return;
+    }
+    await sleep(Math.min(pollMs, Math.max(0, deadline - now())));
+  }
+
+  error(`Connection timed out. Manual fallback:\n  signaldash connect ${provider} claim <account_id>`);
+  process.exitCode = 1;
 }
-async function cmdClaim(provider, accountId) {
-  const r = await api(`/connect/${provider}/claim`, { account_id: accountId });
-  console.log(r.status === 200 ? `Connected ${provider}: ${r.json.name}` : `claim failed: ${r.json.error}`);
+export async function cmdClaim(provider, accountId, dependencies = {}) {
+  const request = dependencies.request || api;
+  const log = dependencies.log || console.log;
+  const r = await request(`/connect/${provider}/claim`, { account_id: accountId });
+  log(r.status === 200 ? `Connected ${provider}: ${r.json.name}` : `claim failed: ${r.json.error}`);
+  if (r.status !== 200) process.exitCode = 1;
 }
 
 // ---- MCP (stdio). Every tool proxies through the backend with the token. ----
@@ -60,9 +121,12 @@ function mcpTool(name) {
   return { name, description: TOOLS.find(t => t.name === name).description,
     inputSchema: { type: "object", properties: { chat_id: { type: "string" }, text: { type: "string" }, limit: { type: "number" } } } };
 }
-async function runMcp() {
-  const rl = createInterface({ input: process.stdin });
-  const reply = (id, result, error) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, ...(error ? { error } : { result }) }) + "\n");
+export async function runMcp(dependencies = {}) {
+  const input = dependencies.input || process.stdin;
+  const output = dependencies.output || process.stdout;
+  const request = dependencies.request || api;
+  const rl = createInterface({ input });
+  const reply = (id, result, error) => output.write(JSON.stringify({ jsonrpc: "2.0", id, ...(error ? { error } : { result }) }) + "\n");
   for await (const line of rl) {
     let msg; try { msg = JSON.parse(line); } catch { continue; }
     const { id, method, params } = msg;
@@ -71,15 +135,41 @@ async function runMcp() {
     else if (method === "tools/call") {
       const t = TOOLS.find(x => x.name === params.name);
       if (!t) { reply(id, null, { code: -32601, message: "unknown tool" }); continue; }
-      const r = await api(`/${t.ch}/${t.action}`, params.arguments || {});
+      const r = await request(`/${t.ch}/${t.action}`, params.arguments || {});
       reply(id, { content: [{ type: "text", text: JSON.stringify(r.json) }], isError: r.status >= 300 });
     } else if (id !== undefined) reply(id, {});
   }
 }
 
-const [cmd, a, b, c] = process.argv.slice(2);
-if (cmd === "login") await cmdLogin(a, b === "--backend" ? c : undefined);
-else if (cmd === "connect" && b === "claim") await cmdClaim(a, c);
-else if (cmd === "connect") await cmdConnect(a);
-else if (cmd === "mcp") await runMcp();
-else console.log(`SignalDash — secure LinkedIn + WhatsApp access for your agent.\n\n  sd login <invite-code> [--backend URL]\n  sd connect linkedin|whatsapp\n  sd connect linkedin|whatsapp claim <account_id>\n  sd mcp\n\nThe agent reaches channels only through SignalDash. No keys on your machine.`);
+
+export async function cmdSkill(dependencies = {}) {
+  const log = dependencies.log || console.log;
+  const { mkdirSync: mk, writeFileSync: wf, readFileSync: rf, existsSync: ex } = await import("node:fs");
+  const { dirname, join } = await import("node:path");
+  const here = dirname(fileURLToPath(import.meta.url));
+  const src = join(here, "..", "skills", "signaldash", "SKILL.md");
+  if (!ex(src)) { log("skill file not found in package"); process.exitCode = 1; return; }
+  const dest = join(homedir(), ".claude", "skills", "signaldash");
+  mk(dest, { recursive: true });
+  wf(join(dest, "SKILL.md"), rf(src, "utf8"));
+  log(`Installed the SignalDash skill to ${dest}/SKILL.md`);
+  log("Your agent now knows how to use LinkedIn + WhatsApp safely through SignalDash.");
+}
+
+export async function main(argv = process.argv.slice(2), dependencies = {}) {
+  const [cmd, a, b, c] = argv;
+  const log = dependencies.log || console.log;
+  if (cmd === "login") await cmdLogin(a, b === "--backend" ? c : undefined, dependencies);
+  else if (cmd === "connect" && b === "claim") await cmdClaim(a, c, dependencies);
+  else if (cmd === "connect") await cmdConnect(a, dependencies);
+  else if (cmd === "mcp") await runMcp(dependencies);
+  else if (cmd === "skill") await cmdSkill(dependencies);
+  else log(`SignalDash — secure LinkedIn + WhatsApp access for your agent.\n\n  signaldash login <invite-code> [--backend URL]\n  signaldash connect linkedin|whatsapp\n  signaldash connect linkedin|whatsapp claim <account_id>\n  signaldash mcp\n  signaldash skill            install the agent skill\n\nThe agent reaches channels only through SignalDash. No keys on your machine.`);
+}
+
+if (
+  process.argv[1] &&
+  realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  await main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/signaldash",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Secure LinkedIn and WhatsApp MCP access for AI agents",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "check": "node --check bin/signaldash.js && node --check lib/cli.js && node --check lib/mcp.js && node --check lib/rate-guard.js && node --check lib/secrets.js && node --check lib/unipile.js"
+    "check": "node --check bin/sd.mjs && node --check server/server.cjs && node --check bin/signaldash.js && node --check lib/cli.js && node --check lib/mcp.js && node --check lib/rate-guard.js && node --check lib/secrets.js && node --check lib/unipile.js"
   },
   "keywords": [
     "mcp",

package/skills/signaldash/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: signaldash
+description: Give this agent secure access to the user's LinkedIn and WhatsApp — list chats, read threads, and send messages — through SignalDash. Use whenever the user asks to check, read, triage, reply to, or send LinkedIn/WhatsApp messages. Also covers first-time setup.
+---
+
+# SignalDash — LinkedIn + WhatsApp for this agent
+
+SignalDash is the gate between you and the user's real messaging accounts. The
+user's channel credentials live on the SignalDash server, never on their machine
+and never in your context. You act through SignalDash tools only.
+
+## Setup (only if the tools are not available yet)
+
+The user needs an invite code from Federico, then:
+
+```bash
+npx @floomhq/signaldash login <invite-code>
+npx @floomhq/signaldash connect linkedin     # opens a link; user authenticates; auto-detects
+npx @floomhq/signaldash connect whatsapp     # same, QR scan from WhatsApp > Linked Devices
+claude mcp add signaldash -- npx -y @floomhq/signaldash mcp
+```
+
+Cursor: add to `.cursor/mcp.json` →
+`{"mcpServers":{"signaldash":{"command":"npx","args":["-y","@floomhq/signaldash","mcp"]}}}`
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `li_list_chats` | list the user's LinkedIn chats |
+| `li_read_messages` | read a LinkedIn thread (`chat_id`) |
+| `li_send_message` | send a LinkedIn message (`chat_id`, `text`) |
+| `wa_list_chats` | list the user's WhatsApp chats |
+| `wa_read_messages` | read a WhatsApp thread (`chat_id`) |
+| `wa_send_message` | send a WhatsApp message (`chat_id`, `text`) |
+
+## The rules you MUST follow
+
+These protect the user's accounts from being restricted or banned, and protect
+them from you sending something wrong. They are not optional.
+
+1. **Never send without the user's explicit approval of the exact recipient and
+   exact text.** Draft it, show it, wait. Discussion is not approval.
+2. **Read the thread before you send.** Always `*_read_messages` on that exact
+   chat first: check who it is, what they last said, and whether this was
+   already sent. Never send blind. Never double-send.
+3. **Never bulk.** No mass messaging, no "message everyone who…", no bulk
+   profile fetching. LinkedIn restricts accounts for exactly this. Hard ceiling
+   is roughly 15-20 LinkedIn sends per day; the server enforces a daily cap and
+   spacing, do not try to work around it or parallelize sends.
+4. **One message at a time, human pace.** Let the server's pacing do its work.
+5. **Stop on any warning.** A checkpoint, restriction, "unusual activity"
+   prompt, 403 or 429 means halt all activity on that account and tell the user.
+   Do not retry.
+6. **Personalize.** Read the thread and write a specific reply. Templated
+   identical messages get reported as spam.
+
+## Good vs bad requests
+
+Good: "list my unread LinkedIn chats and draft replies for my approval" ·
+"read the thread with Mircea and suggest an answer" · "what came in on WhatsApp
+from people I've spoken to before?"
+
+Bad (refuse or push back): "connection-request everyone who liked my post" ·
+"message all my connections about X" · "pull every profile in my network".
+
+Rule of thumb: if a human could not plausibly do it by hand in a day, do not do
+it. Account health beats throughput.