@floomhq/signaldash 0.2.0 → 0.4.0

package/README.md

@@ -102,6 +102,10 @@ receive the Unipile access key.
 SignalDash enforces a daily send cap. The safe-usage skill adds the human
 workflow around that runtime control:
 
+- Every successful send includes `rate_limit.limit`, `used`, `remaining`, and
+  `resets_at`, plus matching `X-RateLimit-*` headers. When the per-user cap is
+  exhausted, SignalDash returns HTTP 429 with `code: "rate_limit_exceeded"` and
+  `Retry-After`. Usage is persisted server-side and resets at midnight UTC.
 - 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.

package/bin/sd.mjs

@@ -97,7 +97,7 @@ export async function cmdConnect(provider, dependencies = {}) {
     await sleep(Math.min(pollMs, Math.max(0, deadline - now())));
   }
 
-  error(`Connection timed out. Manual fallback:\n  signaldash connect ${provider} claim <account_id>`);
+  error(`Not connected yet. The link above stays valid — open it, finish authenticating, then run:\n  npx @floomhq/signaldash connect ${provider}`);
   process.exitCode = 1;
 }
 export async function cmdClaim(provider, accountId, dependencies = {}) {
@@ -141,14 +141,56 @@ export async function runMcp(dependencies = {}) {
   }
 }
 
+
+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.");
+}
+
+
+// One-command onboarding: login + skill + MCP registration + connect both channels.
+export async function cmdSetup(code, dependencies = {}) {
+  const log = dependencies.log || console.log;
+  const { execSync } = await import("node:child_process");
+  log("SignalDash setup\n");
+  await cmdLogin(code, undefined, dependencies);
+  if (process.exitCode === 1) return;
+  await cmdSkill(dependencies);
+  try {
+    execSync("claude mcp add signaldash -- npx -y @floomhq/signaldash mcp", { stdio: "ignore" });
+    log("Registered the MCP with Claude Code.");
+  } catch {
+    log("To finish in Cursor, add to .cursor/mcp.json:");
+    log('  {"mcpServers":{"signaldash":{"command":"npx","args":["-y","@floomhq/signaldash","mcp"]}}}');
+  }
+  for (const provider of ["linkedin", "whatsapp"]) {
+    log(`\n--- connect ${provider} ---`);
+    await cmdConnect(provider, dependencies);
+    process.exitCode = 0; // a skipped channel should not fail the whole setup
+  }
+  log("\nDone. Ask your agent: \"list my recent LinkedIn chats and draft replies.\"");
+}
+
 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);
+  if (cmd === "setup") await cmdSetup(a, dependencies);
+  else if (cmd && /^[0-9a-f]{8,}$/i.test(cmd) && !["login","connect","mcp","skill"].includes(cmd)) await cmdSetup(cmd, dependencies);
+  else 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 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\nThe agent reaches channels only through SignalDash. No keys on your machine.`);
+  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 (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/signaldash",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Secure LinkedIn and WhatsApp MCP access for AI agents",
   "type": "module",
   "bin": {

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.