@floomhq/signaldash 0.1.0

package/lib/unipile.js

@@ -0,0 +1,166 @@
+const WARNING_PATTERN =
+  /warning|checkpoint|restriction|rate.?limit|automated activity|spam|temporar(?:ily)? blocked/i;
+
+function topLevelWarning(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return null;
+  }
+  for (const key of ["warning", "warnings"]) {
+    const value = payload[key];
+    if (value !== undefined && value !== null && value !== "") {
+      return `${key}: ${JSON.stringify(value).slice(0, 300)}`;
+    }
+  }
+  const description = [
+    payload.type,
+    payload.title,
+    payload.detail,
+    payload.error,
+    payload.message,
+  ]
+    .filter((value) => typeof value === "string")
+    .join(" ");
+  return WARNING_PATTERN.test(description) ? description.slice(0, 300) : null;
+}
+
+export class UnipileWarningError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnipileWarningError";
+  }
+}
+
+export function accountIsReady(account) {
+  const sources = Array.isArray(account?.sources) ? account.sources : [];
+  return (
+    Boolean(account?.id) &&
+    (sources.length === 0 ||
+      sources.every(
+        (source) => String(source.status || "").toUpperCase() === "OK",
+      ))
+  );
+}
+
+export class UnipileClient {
+  constructor({ base, key, fetchImpl = globalThis.fetch }) {
+    this.base = base.replace(/\/+$/, "");
+    this.key = key;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async request(method, route, { query, body } = {}) {
+    if (!route.startsWith("/") || route.startsWith("//")) {
+      throw new Error("invalid Unipile route");
+    }
+    const url = new URL(`${this.base}${route}`);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value !== undefined && value !== null && value !== "") {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method,
+        headers: {
+          "X-API-KEY": this.key,
+          Accept: "application/json",
+          ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(30_000),
+      });
+    } catch (error) {
+      throw new Error(
+        `Unipile request failed: ${error.cause?.code || error.message}`,
+      );
+    }
+
+    const raw = await response.text();
+    let payload = {};
+    if (raw.trim()) {
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        throw new Error(`Unipile returned invalid JSON (${response.status})`);
+      }
+    }
+
+    const warningHeader = [...response.headers.entries()].find(([name]) =>
+      name.toLowerCase().includes("warning"),
+    );
+    const warning = topLevelWarning(payload);
+    if (warningHeader || response.status === 403 || response.status === 429 || warning) {
+      const detail =
+        warningHeader?.join(": ") ||
+        warning ||
+        `HTTP ${response.status}`;
+      throw new UnipileWarningError(
+        `Unipile safety warning on ${route}: ${detail}`,
+      );
+    }
+    if (!response.ok) {
+      const detail = [
+        payload.title,
+        payload.detail,
+        payload.message,
+        raw.slice(0, 200),
+      ].find((value) => typeof value === "string" && value.trim());
+      throw new Error(
+        `Unipile request failed (${response.status})${detail ? `: ${detail}` : ""}`,
+      );
+    }
+    return payload;
+  }
+
+  listAccounts() {
+    return this.request("GET", "/accounts");
+  }
+
+  async createHostedAuthLink(provider) {
+    const payload = await this.request("POST", "/hosted/accounts/link", {
+      body: {
+        type: "create",
+        providers: [provider],
+        api_url: this.base,
+        expiresOn: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
+      },
+    });
+    let url;
+    try {
+      url = new URL(payload.url);
+    } catch {
+      throw new Error("Unipile did not return a hosted-auth URL");
+    }
+    if (url.protocol !== "https:" || url.hostname !== "account.unipile.com") {
+      throw new Error("Unipile returned an unexpected hosted-auth URL");
+    }
+    return url.toString();
+  }
+
+  listChats(accountId, limit) {
+    return this.request("GET", "/chats", {
+      query: { account_id: accountId, limit },
+    });
+  }
+
+  getChat(chatId) {
+    return this.request("GET", `/chats/${encodeURIComponent(chatId)}`);
+  }
+
+  listMessages(chatId, limit) {
+    return this.request(
+      "GET",
+      `/chats/${encodeURIComponent(chatId)}/messages`,
+      { query: { limit } },
+    );
+  }
+
+  sendMessage(chatId, text) {
+    return this.request(
+      "POST",
+      `/chats/${encodeURIComponent(chatId)}/messages`,
+      { body: { text } },
+    );
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@floomhq/signaldash",
+  "version": "0.1.0",
+  "description": "Secure LinkedIn and WhatsApp MCP access for AI agents",
+  "type": "module",
+  "bin": {
+    "signaldash": "bin/sd.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "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"
+  },
+  "keywords": [
+    "mcp",
+    "linkedin",
+    "whatsapp",
+    "unipile",
+    "ai-agent"
+  ],
+  "license": "MIT"
+}

package/skills/signaldash-safe-usage/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: signaldash-safe-usage
+description: Safely read and send LinkedIn or WhatsApp messages through the SignalDash MCP without triggering account restrictions or contacting the wrong person. Use whenever an agent uses li_list_chats, li_read_messages, li_send_message, wa_list_chats, wa_read_messages, or wa_send_message.
+---
+
+# Use SignalDash safely
+
+Treat LinkedIn and WhatsApp as human accounts, not bulk messaging APIs.
+
+## Before every send
+
+1. Confirm the requested channel and exact chat.
+2. Use `li_list_chats` or `wa_list_chats`; never fetch profiles in bulk.
+3. Read at least the 10 most recent messages in the exact thread.
+4. Check the recipient, prior conversation, last inbound message, and whether
+   the proposed text was already sent.
+5. Obtain explicit human approval for the exact recipient and exact text when
+   the user has not already approved both.
+6. Send one message, then read the thread again to confirm delivery.
+
+Never infer a recipient from a partial name. Never send blind. Never retry a
+send after an ambiguous timeout without first reading the thread.
+
+## LinkedIn limits
+
+- Keep normal messaging at 15 to 20 sends per day. SignalDash hard-caps at 18
+  send attempts per account per UTC day.
+- Let SignalDash enforce 45 to 90 seconds between sends. Do not parallelize
+  send calls or bypass the guard.
+- LinkedIn invitation ceilings vary and often surface around 100 invitations
+  per week. SignalDash exposes no invitation tool. Do not automate invites.
+- Never bulk-fetch profiles, run enrichment sweeps, or repeatedly open
+  individual profiles. Prefer chat lists, exported connection data, and
+  cached records.
+- Stop all LinkedIn activity on any checkpoint, warning, restriction, unusual
+  verification prompt, HTTP 403, or HTTP 429.
+
+LinkedIn detects behavior, not only API request frequency. Repeated copy,
+bursting sends, high profile-view volume, many ignored invitations, concurrent
+sessions, and repeated checkpoint retries trigger restrictions.
+
+## WhatsApp limits
+
+- SignalDash hard-caps at 30 send attempts per account per UTC day and
+  enforces 15 to 35 seconds between sends.
+- Send only in existing, relevant conversations unless the human explicitly
+  authorizes a new contact.
+- Avoid repeated identical text, bulk cold outreach, rapid group posting, and
+  many new chats from a fresh number.
+- Use an established number with real conversation history. Keep the primary
+  phone powered on and connected so linked-device history remains current.
+- Stop on logout, QR re-authentication, delivery anomalies, provider warnings,
+  HTTP 403, or HTTP 429.
+
+## When a guard blocks
+
+Do not work around daily caps, jitter, duplicate detection, account scoping,
+or the persistent warning lock.
+
+On a warning:
+
+1. Stop all sends on that account.
+2. Inspect LinkedIn or WhatsApp manually for a restriction or checkpoint.
+3. Wait until the account is clearly back in good standing.
+4. Let a human clear only that account's entry in
+   `~/.signaldash/safety/send-state.json`.
+5. Resume at a lower volume.
+
+Let the agent act slowly and human-like. Account health outranks throughput.