twindex-openclaw-plugin 0.2.0 → 0.4.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "twindex",
   "name": "Twindex",
   "description": "Music intelligence for AI agents. Get notified about tours, merch drops, releases, and presales for your favorite artists.",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twindex-openclaw-plugin",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Music intelligence for AI agents. Tours, merch drops, releases, presales.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -1,7 +1,5 @@
 import * as twindex from "./client.js";
-
-let pendingDelivery: string[] = [];
-let pollTimer: ReturnType<typeof setInterval> | null = null;
+import { createNotificationService } from "./sse-service.js";
 
 export default function register(api: any) {
   const cfg = () => api.config?.plugins?.entries?.twindex?.config ?? {};
@@ -12,18 +10,21 @@ export default function register(api: any) {
       ...cfg(),
       ...updates,
     };
-    // OpenClaw auto-persists config mutations on the entries object.
-    // If a future version requires explicit save, call api.config.save?.() here.
     api.config.save?.();
   }
 
-  // ── Auto-bootstrap: if artists + frequency set but no apiKey, self-configure ──
+  // ── SSE notification service ──────────────────────────────────────
+  const sseService = createNotificationService(api);
+  api.registerService?.(sseService);
+
+  // ── Auto-bootstrap: register + subscribe ────────────────────────
 
   (async () => {
     const config = cfg();
     if (config.artists?.length > 0 && config.frequency && !config.apiKey) {
       try {
-        const agentId = api.agentId ?? api.config?.agentId ?? `openclaw-${crypto.randomUUID()}`;
+        const agentId =
+          api.agentId ?? api.config?.agentId ?? `openclaw-${crypto.randomUUID()}`;
         const reg = await twindex.register(agentId);
         const apiKey = reg.api_key;
 
@@ -32,13 +33,17 @@ export default function register(api: any) {
             await twindex.subscribe(apiKey, artist);
             api.logger?.info?.(`Twindex: auto-subscribed to ${artist}`);
           } catch (err: any) {
-            api.logger?.warn?.(`Twindex: failed to subscribe to ${artist}: ${err.message}`);
+            api.logger?.warn?.(
+              `Twindex: failed to subscribe to ${artist}: ${err.message}`,
+            );
           }
         }
 
         persistConfig({ apiKey });
-        startPolling(api, apiKey, config.frequency);
-        api.logger?.info?.(`Twindex: auto-bootstrap complete. Polling ${config.frequency}.`);
+        sseService.start();
+        api.logger?.info?.(
+          "Twindex: auto-bootstrap complete. Delivery via SSE push.",
+        );
       } catch (err: any) {
         api.logger?.warn?.(`Twindex: auto-bootstrap failed: ${err.message}`);
       }
@@ -50,7 +55,7 @@ export default function register(api: any) {
   api.registerTool({
     name: "twindex_setup",
     description:
-      "Set up Twindex music notifications. Registers with Twindex, subscribes to artists, and configures delivery. Call this after asking your user which artists they want and how often they want updates.",
+      "Set up Twindex music notifications. Registers with Twindex, subscribes to artists, and starts real-time push delivery via SSE. Call this after asking your user which artists they want.",
     parameters: {
       type: "object",
       properties: {
@@ -69,21 +74,27 @@ export default function register(api: any) {
       },
       required: ["artists", "frequency"],
     },
-    async execute(_id: string, params: { artists: string[]; frequency: string }) {
+    async execute(
+      _id: string,
+      params: { artists: string[]; frequency: string },
+    ) {
       try {
         const config = cfg();
         let apiKey = config.apiKey;
 
         if (!apiKey) {
-          const agentId = api.agentId ?? api.config?.agentId ?? `openclaw-${crypto.randomUUID()}`;
+          const agentId =
+            api.agentId ??
+            api.config?.agentId ??
+            `openclaw-${crypto.randomUUID()}`;
           const reg = await twindex.register(agentId);
           apiKey = reg.api_key;
         }
 
         persistConfig({
           apiKey,
+          artists: params.artists,
           frequency: params.frequency,
-          intervalMinutes: frequencyToMinutes(params.frequency),
         });
 
         const results: string[] = [];
@@ -96,13 +107,8 @@ export default function register(api: any) {
           }
         }
 
-        startPolling(api, apiKey, params.frequency);
-
-        const intervalDesc = frequencyDescription(params.frequency);
-        results.push(`Delivery configured: ${intervalDesc}`);
-        results.push(
-          "Notifications will be delivered automatically. No cron jobs needed.",
-        );
+        sseService.start();
+        results.push("Real-time push notifications enabled (SSE)");
 
         return {
           content: [{ type: "text", text: results.join("\n") }],
@@ -118,7 +124,7 @@ export default function register(api: any) {
   api.registerTool({
     name: "twindex_subscribe",
     description:
-      "Subscribe to a new artist on Twindex. The existing delivery job will automatically pick up notifications for this artist.",
+      "Subscribe to a new artist on Twindex. The existing delivery schedule will automatically pick up notifications for this artist.",
     parameters: {
       type: "object",
       properties: {
@@ -152,7 +158,10 @@ export default function register(api: any) {
       } catch (err: any) {
         return {
           content: [
-            { type: "text", text: `Failed to subscribe to ${params.artist}: ${err.message}` },
+            {
+              type: "text",
+              text: `Failed to subscribe to ${params.artist}: ${err.message}`,
+            },
           ],
         };
       }
@@ -192,7 +201,10 @@ export default function register(api: any) {
       } catch (err: any) {
         return {
           content: [
-            { type: "text", text: `Failed to unsubscribe from ${params.artist}: ${err.message}` },
+            {
+              type: "text",
+              text: `Failed to unsubscribe from ${params.artist}: ${err.message}`,
+            },
           ],
         };
       }
@@ -208,19 +220,6 @@ export default function register(api: any) {
       properties: {},
     },
     async execute() {
-      // Drain the in-process buffer first (avoids double-delivery with poll service)
-      if (pendingDelivery.length > 0) {
-        const buffered = pendingDelivery.splice(0);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `${buffered.length} update(s):\n${buffered.join("\n")}`,
-            },
-          ],
-        };
-      }
-
       const apiKey = cfg().apiKey;
       if (!apiKey) {
         return {
@@ -234,13 +233,14 @@ export default function register(api: any) {
         const notifications = await twindex.getNotifications(apiKey);
         if (notifications.length === 0) {
           return {
-            content: [
-              { type: "text", text: "No unread notifications." },
-            ],
+            content: [{ type: "text", text: "No unread notifications." }],
           };
         }
 
-        const lines = formatNotifications(notifications);
+        const lines = notifications.map(
+          (n) =>
+            `[${n.brand}] ${n.event_type}: ${n.summary}${n.detail_url ? ` — ${n.detail_url}` : ""}`,
+        );
 
         const ids = notifications.map((n) => n.id);
         await twindex.markRead(apiKey, ids);
@@ -256,7 +256,10 @@ export default function register(api: any) {
       } catch (err: any) {
         return {
           content: [
-            { type: "text", text: `Failed to check notifications: ${err.message}` },
+            {
+              type: "text",
+              text: `Failed to check notifications: ${err.message}`,
+            },
           ],
         };
       }
@@ -297,7 +300,10 @@ export default function register(api: any) {
       } catch (err: any) {
         return {
           content: [
-            { type: "text", text: `Failed to list subscriptions: ${err.message}` },
+            {
+              type: "text",
+              text: `Failed to list subscriptions: ${err.message}`,
+            },
           ],
         };
       }
@@ -327,7 +333,10 @@ export default function register(api: any) {
       } catch (err: any) {
         return {
           content: [
-            { type: "text", text: `Failed to get artist page: ${err.message}` },
+            {
+              type: "text",
+              text: `Failed to get artist page: ${err.message}`,
+            },
           ],
         };
       }
@@ -343,7 +352,8 @@ export default function register(api: any) {
       properties: {
         query: {
           type: "string",
-          description: "Search query. Examples: 'metal bands', 'the cure', 'punk rock'.",
+          description:
+            "Search query. Examples: 'metal bands', 'the cure', 'punk rock'.",
         },
       },
       required: ["query"],
@@ -405,109 +415,5 @@ export default function register(api: any) {
       }
     },
   });
-
-  // ── Lifecycle Hook: inject notifications into agent context ────────
-
-  api.on("before_agent_start", async () => {
-    if (pendingDelivery.length === 0) return;
-
-    const messages = pendingDelivery.splice(0);
-    return {
-      systemMessage: [
-        "TWINDEX NOTIFICATIONS (deliver these to your user):",
-        ...messages,
-      ].join("\n"),
-    };
-  });
-
-  // ── Background Service: poll for notifications ─────────────────────
-
-  api.registerService?.({
-    id: "twindex-poll",
-    start: () => {
-      const config = cfg();
-      if (config.apiKey && config.frequency) {
-        startPolling(api, config.apiKey, config.frequency);
-      }
-    },
-    stop: () => {
-      if (pollTimer) {
-        clearInterval(pollTimer);
-        pollTimer = null;
-      }
-    },
-  });
-}
-
-// ── Helpers ────────────────────────────────────────────────────────────
-
-function frequencyToMinutes(frequency: string): number {
-  switch (frequency) {
-    case "realtime":
-      return 5;
-    case "daily":
-      return 1440;
-    case "periodic":
-    default:
-      return 60;
-  }
-}
-
-function frequencyDescription(frequency: string): string {
-  switch (frequency) {
-    case "realtime":
-      return "checking every 5 minutes";
-    case "daily":
-      return "checking once per day";
-    case "periodic":
-    default:
-      return "checking every hour";
-  }
 }
 
-function formatNotifications(
-  notifications: Array<{
-    brand: string;
-    event_type: string;
-    summary: string;
-    detail_url?: string;
-  }>,
-): string[] {
-  return notifications.map(
-    (n) =>
-      `[${n.brand}] ${n.event_type}: ${n.summary}${n.detail_url ? ` — ${n.detail_url}` : ""}`,
-  );
-}
-
-function startPolling(api: any, apiKey: string, frequency: string) {
-  if (pollTimer) {
-    clearInterval(pollTimer);
-  }
-
-  const intervalMs = frequencyToMinutes(frequency) * 60 * 1000;
-
-  pollTimer = setInterval(async () => {
-    try {
-      const notifications = await twindex.getNotifications(apiKey);
-      if (notifications.length === 0) return;
-
-      // Queue for delivery BEFORE marking read — if process crashes after
-      // markRead, notifications are lost. This way they survive in the buffer.
-      const lines = formatNotifications(notifications);
-      pendingDelivery.push(...lines);
-
-      const ids = notifications.map((n) => n.id);
-      await twindex.markRead(apiKey, ids);
-
-      api.logger?.info?.(
-        `Twindex: ${notifications.length} notification(s) queued for delivery`,
-      );
-    } catch (err: any) {
-      api.logger?.warn?.(`Twindex poll error: ${err.message}`);
-    }
-  }, intervalMs);
-
-  api.logger?.info?.(
-    `Twindex: polling every ${frequencyToMinutes(frequency)} min`,
-  );
-}

package/src/sse-service.ts

@@ -0,0 +1,172 @@
+// SSE background service — replaces cron polling with real-time push.
+// Opens persistent connection to twindex.ai/api/v1/notifications/stream,
+// delivers notifications via `openclaw agent` CLI, marks them read.
+
+import { execFile } from "child_process";
+import * as twindex from "./client.js";
+
+const BASE_URL = "https://twindex.ai";
+const BACKOFF_STEPS = [1000, 2000, 5000, 10_000, 30_000, 60_000];
+
+function runAgent(message: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    execFile(
+      "openclaw",
+      [
+        "agent",
+        "--session-id",
+        "twindex-push",
+        "--deliver",
+        "--channel",
+        "last",
+        "-m",
+        message,
+      ],
+      { timeout: 120_000 },
+      (err) => resolve(!err),
+    );
+  });
+}
+
+export function createNotificationService(api: any) {
+  let controller: AbortController | null = null;
+  let retryCount = 0;
+  let lastEventId: string | null = null;
+  let running = false;
+
+  function getApiKey(): string | undefined {
+    return api.config?.plugins?.entries?.twindex?.config?.apiKey;
+  }
+
+  const logger = api.logger;
+
+  async function processLine(line: string) {
+    if (line.startsWith("id: ")) {
+      lastEventId = line.slice(4).trim();
+      return;
+    }
+
+    if (!line.startsWith("data: ")) return;
+
+    const json = line.slice(6).trim();
+    if (!json) return;
+
+    let notif: { id: string; brand: string; event_type: string; summary: string };
+    try {
+      notif = JSON.parse(json);
+    } catch {
+      return;
+    }
+
+    logger?.info?.(`Twindex: notification received — ${notif.brand} ${notif.event_type}`);
+
+    const message =
+      `New Twindex update for ${notif.brand} (${notif.event_type}): ${notif.summary}\n` +
+      "Share this with the user naturally. If they seem busy, keep it brief.";
+
+    const delivered = await runAgent(message);
+    if (delivered) {
+      const apiKey = getApiKey();
+      if (apiKey) {
+        try {
+          await twindex.markRead(apiKey, [notif.id]);
+        } catch {
+          // Non-fatal — notification delivered, read status will catch up
+        }
+      }
+    } else {
+      logger?.warn?.("Twindex: agent delivery failed, notification will replay on reconnect");
+    }
+  }
+
+  async function connect() {
+    const apiKey = getApiKey();
+    if (!apiKey) return;
+
+    controller = new AbortController();
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${apiKey}`,
+      Accept: "text/event-stream",
+    };
+    if (lastEventId) {
+      headers["Last-Event-ID"] = lastEventId;
+    }
+
+    try {
+      const res = await fetch(`${BASE_URL}/api/v1/notifications/stream`, {
+        headers,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        throw new Error(`SSE connect failed: ${res.status}`);
+      }
+
+      if (!res.body) {
+        throw new Error("SSE: no response body");
+      }
+
+      // Connected successfully — reset backoff
+      retryCount = 0;
+      logger?.info?.("Twindex: SSE connected");
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (running) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        // Keep incomplete last line in buffer
+        buffer = lines.pop() ?? "";
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (trimmed === "" || trimmed.startsWith(": ")) continue;
+          await processLine(trimmed);
+        }
+      }
+    } catch (err: any) {
+      if (err.name === "AbortError") return;
+      logger?.warn?.(`Twindex: SSE error — ${err.message}`);
+    }
+
+    // Reconnect with backoff if still running
+    if (running) {
+      const delay = BACKOFF_STEPS[Math.min(retryCount, BACKOFF_STEPS.length - 1)];
+      retryCount++;
+      logger?.info?.(`Twindex: reconnecting in ${delay}ms (attempt ${retryCount})`);
+      await new Promise((r) => setTimeout(r, delay));
+      if (running) connect();
+    }
+  }
+
+  return {
+    name: "twindex-notifications",
+
+    start() {
+      if (running) return;
+      const apiKey = getApiKey();
+      if (!apiKey) {
+        logger?.info?.("Twindex: no API key — SSE service waiting for setup");
+        return;
+      }
+      running = true;
+      connect();
+      logger?.info?.("Twindex: SSE notification service started");
+    },
+
+    stop() {
+      running = false;
+      if (controller) {
+        controller.abort();
+        controller = null;
+      }
+      logger?.info?.("Twindex: SSE notification service stopped");
+    },
+  };
+}