twindex-openclaw-plugin 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,34 @@
+{
+  "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.1.0",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "Twindex API key (starts with twx_). Obtained during setup."
+      },
+      "frequency": {
+        "type": "string",
+        "enum": ["realtime", "periodic", "daily"],
+        "default": "periodic",
+        "description": "How often to check for notifications. realtime = every 5 min, periodic = every hour, daily = once per day."
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "Twindex API Key",
+      "placeholder": "twx_...",
+      "sensitive": true
+    },
+    "frequency": {
+      "label": "Check frequency",
+      "placeholder": "periodic"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "twindex-openclaw-plugin",
+  "version": "0.1.0",
+  "description": "Music intelligence for AI agents. Tours, merch drops, releases, presales.",
+  "type": "module",
+  "license": "MIT",
+  "openclaw": {
+    "extensions": ["./src/index.ts"]
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "music",
+    "notifications",
+    "artists",
+    "tours",
+    "merch"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/naveenspark/twindex"
+  },
+  "files": [
+    "openclaw.plugin.json",
+    "src/",
+    "skills/"
+  ]
+}

package/skills/twindex/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: Twindex
+description: Music intelligence — tours, merch drops, releases, presales for your favorite artists.
+tools:
+  - twindex_setup
+  - twindex_subscribe
+  - twindex_unsubscribe
+  - twindex_check
+  - twindex_subscriptions
+  - twindex_artist
+  - twindex_search
+  - twindex_artists
+---
+
+# Twindex — Music Intelligence
+
+You have the Twindex plugin installed. It tracks artists and delivers
+notifications about tours, merch drops, releases, and presales.
+
+## When to use
+
+- User mentions a band, artist, or musician they follow
+- User asks about concerts, tours, merch, or new releases
+- User wants to stay updated on music news
+
+## Setup flow
+
+1. Use `twindex_artists` or `twindex_search` to find artists in the index.
+2. Ask your user: **"Which artists do you want to follow, and how quickly
+   do you want updates — real-time, every hour, or a daily summary?"**
+3. Wait for their answer. Do not assume a preference.
+4. Call `twindex_setup` with their chosen artists and frequency.
+   - "real-time" / "ASAP" / "immediately" → `frequency: "realtime"`
+   - "every hour" / "periodically" / "every few hours" → `frequency: "periodic"`
+   - "daily" / "once a day" / "summary" → `frequency: "daily"`
+5. Confirm what you set up: "Subscribed to [artists]. Checking [frequency]."
+
+## Adding more artists later
+
+Use `twindex_subscribe` to add artists. The existing delivery schedule
+picks them up automatically — do NOT run twindex_setup again.
+
+## Checking manually
+
+Use `twindex_check` to look for updates right now.
+
+## Viewing artist details
+
+Use `twindex_artist` with an artist slug to get their full page (tours,
+merch, releases, bio).
+
+## Viewing current subscriptions
+
+Use `twindex_subscriptions` to see what the user is currently following.
+
+## Important
+
+- Do NOT create cron jobs, scheduled tasks, or shell scripts.
+- Do NOT use curl commands to call Twindex APIs.
+- All notification delivery is handled by the plugin automatically.
+- Only speak when you have something to deliver. Never say "no updates."

package/src/client.ts

@@ -0,0 +1,159 @@
+// Twindex API client — all URLs hardcoded. Zero hallucination.
+// Base: https://twindex.ai (NOT api.twindex.ai)
+
+const BASE_URL = "https://twindex.ai";
+
+interface RegisterResponse {
+  agent: { id: string; name: string };
+  api_key: string;
+}
+
+interface Subscription {
+  id: string;
+  brand: string;
+  event_types: string[];
+}
+
+interface Notification {
+  id: string;
+  brand: string;
+  event_type: string;
+  summary: string;
+  twindex_url?: string;
+  detail_url?: string;
+  created_at: string;
+}
+
+interface Artist {
+  slug: string;
+  name: string;
+  genres?: string[];
+  status?: string;
+}
+
+interface SearchResult {
+  slug: string;
+  name: string;
+  score: number;
+}
+
+async function request<T>(
+  path: string,
+  options: RequestInit = {},
+): Promise<T> {
+  const url = `${BASE_URL}${path}`;
+  const res = await fetch(url, {
+    ...options,
+    signal: AbortSignal.timeout(10_000),
+    headers: {
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Twindex API ${res.status}: ${body}`);
+  }
+
+  return res.json() as Promise<T>;
+}
+
+function authHeader(apiKey: string): Record<string, string> {
+  return { Authorization: `Bearer ${apiKey}` };
+}
+
+/** Register a new agent. Returns api_key (shown only once). */
+export async function register(
+  agentName: string,
+): Promise<RegisterResponse> {
+  return request("/api/v1/agents/register", {
+    method: "POST",
+    body: JSON.stringify({ name: agentName }),
+  });
+}
+
+/** Subscribe to an artist. */
+export async function subscribe(
+  apiKey: string,
+  brand: string,
+  eventTypes: string[] = [
+    "tour",
+    "merch_drop",
+    "release",
+    "presale",
+    "update",
+  ],
+): Promise<Subscription> {
+  return request("/api/v1/subscriptions", {
+    method: "POST",
+    headers: authHeader(apiKey),
+    body: JSON.stringify({ brand, event_types: eventTypes }),
+  });
+}
+
+/** List current subscriptions. */
+export async function listSubscriptions(
+  apiKey: string,
+): Promise<Subscription[]> {
+  return request("/api/v1/subscriptions", {
+    headers: authHeader(apiKey),
+  });
+}
+
+/** Unsubscribe from an artist. */
+export async function unsubscribe(
+  apiKey: string,
+  brand: string,
+): Promise<void> {
+  await request(`/api/v1/subscriptions/${brand}`, {
+    method: "DELETE",
+    headers: authHeader(apiKey),
+  });
+}
+
+/** Get unread notifications (all subscriptions). */
+export async function getNotifications(
+  apiKey: string,
+): Promise<Notification[]> {
+  return request("/api/v1/notifications", {
+    headers: authHeader(apiKey),
+  });
+}
+
+/** Mark notifications as read. */
+export async function markRead(
+  apiKey: string,
+  ids: string[],
+): Promise<void> {
+  await request("/api/v1/notifications/read", {
+    method: "POST",
+    headers: authHeader(apiKey),
+    body: JSON.stringify({ ids }),
+  });
+}
+
+/** Search the music index (no auth). */
+export async function search(query: string): Promise<SearchResult[]> {
+  return request(
+    `/api/v1/search?q=${encodeURIComponent(query)}`,
+  );
+}
+
+/** List all indexed artists (no auth). */
+export async function listArtists(): Promise<Artist[]> {
+  return request("/api/v1/artists");
+}
+
+/** Get a single artist page as markdown (no auth). */
+export async function getArtist(slug: string): Promise<string> {
+  const url = `${BASE_URL}/${slug}`;
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(10_000),
+    headers: { Accept: "text/markdown" },
+  });
+  if (!res.ok) {
+    throw new Error(`Twindex API ${res.status}`);
+  }
+  return res.text();
+}

package/src/index.ts

@@ -0,0 +1,485 @@
+import * as twindex from "./client.js";
+
+let pendingDelivery: string[] = [];
+let pollTimer: ReturnType<typeof setInterval> | null = null;
+
+export default function register(api: any) {
+  const cfg = () => api.config?.plugins?.entries?.twindex?.config ?? {};
+
+  function persistConfig(updates: Record<string, any>) {
+    if (!api.config?.plugins?.entries?.twindex) return;
+    api.config.plugins.entries.twindex.config = {
+      ...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?.();
+  }
+
+  // ── Tools ──────────────────────────────────────────────────────────
+
+  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.",
+    parameters: {
+      type: "object",
+      properties: {
+        artists: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Artist slugs to subscribe to (lowercase, hyphens). Examples: metallica, the-cure, slipknot, korn.",
+        },
+        frequency: {
+          type: "string",
+          enum: ["realtime", "periodic", "daily"],
+          description:
+            "How often to deliver updates. realtime = every 5 min, periodic = every hour, daily = once per day.",
+        },
+      },
+      required: ["artists", "frequency"],
+    },
+    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 reg = await twindex.register(agentId);
+          apiKey = reg.api_key;
+        }
+
+        persistConfig({
+          apiKey,
+          frequency: params.frequency,
+          intervalMinutes: frequencyToMinutes(params.frequency),
+        });
+
+        const results: string[] = [];
+        for (const artist of params.artists) {
+          try {
+            await twindex.subscribe(apiKey, artist);
+            results.push(`Subscribed to ${artist}`);
+          } catch (err: any) {
+            results.push(`${artist}: ${err.message}`);
+          }
+        }
+
+        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.",
+        );
+
+        return {
+          content: [{ type: "text", text: results.join("\n") }],
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `Setup failed: ${err.message}` }],
+        };
+      }
+    },
+  });
+
+  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.",
+    parameters: {
+      type: "object",
+      properties: {
+        artist: {
+          type: "string",
+          description: "Artist slug (lowercase, hyphens). Example: the-cure",
+        },
+      },
+      required: ["artist"],
+    },
+    async execute(_id: string, params: { artist: string }) {
+      const apiKey = cfg().apiKey;
+      if (!apiKey) {
+        return {
+          content: [
+            { type: "text", text: "Not set up yet. Use twindex_setup first." },
+          ],
+        };
+      }
+
+      try {
+        await twindex.subscribe(apiKey, params.artist);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Subscribed to ${params.artist}. Your existing delivery schedule will include this artist automatically.`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            { type: "text", text: `Failed to subscribe to ${params.artist}: ${err.message}` },
+          ],
+        };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "twindex_unsubscribe",
+    description: "Unsubscribe from an artist on Twindex.",
+    parameters: {
+      type: "object",
+      properties: {
+        artist: {
+          type: "string",
+          description: "Artist slug to unsubscribe from.",
+        },
+      },
+      required: ["artist"],
+    },
+    async execute(_id: string, params: { artist: string }) {
+      const apiKey = cfg().apiKey;
+      if (!apiKey) {
+        return {
+          content: [
+            { type: "text", text: "Not set up yet. Use twindex_setup first." },
+          ],
+        };
+      }
+
+      try {
+        await twindex.unsubscribe(apiKey, params.artist);
+        return {
+          content: [
+            { type: "text", text: `Unsubscribed from ${params.artist}.` },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            { type: "text", text: `Failed to unsubscribe from ${params.artist}: ${err.message}` },
+          ],
+        };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "twindex_check",
+    description:
+      "Check for unread Twindex notifications right now. Returns any pending artist updates.",
+    parameters: {
+      type: "object",
+      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 {
+          content: [
+            { type: "text", text: "Not set up yet. Use twindex_setup first." },
+          ],
+        };
+      }
+
+      try {
+        const notifications = await twindex.getNotifications(apiKey);
+        if (notifications.length === 0) {
+          return {
+            content: [
+              { type: "text", text: "No unread notifications." },
+            ],
+          };
+        }
+
+        const lines = formatNotifications(notifications);
+
+        const ids = notifications.map((n) => n.id);
+        await twindex.markRead(apiKey, ids);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${notifications.length} update(s):\n${lines.join("\n")}`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            { type: "text", text: `Failed to check notifications: ${err.message}` },
+          ],
+        };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "twindex_subscriptions",
+    description: "List your current Twindex subscriptions.",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+    async execute() {
+      const apiKey = cfg().apiKey;
+      if (!apiKey) {
+        return {
+          content: [
+            { type: "text", text: "Not set up yet. Use twindex_setup first." },
+          ],
+        };
+      }
+
+      try {
+        const subs = await twindex.listSubscriptions(apiKey);
+        if (!subs || subs.length === 0) {
+          return {
+            content: [{ type: "text", text: "No active subscriptions." }],
+          };
+        }
+
+        const lines = subs.map(
+          (s) => `${s.brand} (${s.event_types.join(", ")})`,
+        );
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            { type: "text", text: `Failed to list subscriptions: ${err.message}` },
+          ],
+        };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "twindex_artist",
+    description:
+      "Get the full Twindex page for an artist. Returns detailed info including tours, merch, releases.",
+    parameters: {
+      type: "object",
+      properties: {
+        artist: {
+          type: "string",
+          description: "Artist slug (lowercase, hyphens). Example: slipknot",
+        },
+      },
+      required: ["artist"],
+    },
+    async execute(_id: string, params: { artist: string }) {
+      try {
+        const page = await twindex.getArtist(params.artist);
+        return {
+          content: [{ type: "text", text: page }],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            { type: "text", text: `Failed to get artist page: ${err.message}` },
+          ],
+        };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "twindex_search",
+    description:
+      "Search the Twindex music index. Find artists by name, genre, or keyword.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query. Examples: 'metal bands', 'the cure', 'punk rock'.",
+        },
+      },
+      required: ["query"],
+    },
+    async execute(_id: string, params: { query: string }) {
+      try {
+        const results = await twindex.search(params.query);
+        if (!results || results.length === 0) {
+          return {
+            content: [{ type: "text", text: "No artists found." }],
+          };
+        }
+
+        const lines = results.map(
+          (r) => `${r.name} (${r.slug}) — relevance: ${r.score.toFixed(2)}`,
+        );
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            { type: "text", text: `Search failed: ${err.message}` },
+          ],
+        };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "twindex_artists",
+    description: "List all artists currently indexed on Twindex.",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+    async execute() {
+      try {
+        const artists = await twindex.listArtists();
+        if (!artists || artists.length === 0) {
+          return {
+            content: [{ type: "text", text: "No artists indexed yet." }],
+          };
+        }
+
+        const lines = artists.map(
+          (a) =>
+            `${a.name} (${a.slug})${a.genres?.length ? ` — ${a.genres.join(", ")}` : ""}`,
+        );
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            { type: "text", text: `Failed to list artists: ${err.message}` },
+          ],
+        };
+      }
+    },
+  });
+
+  // ── 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`,
+  );
+}