openclaw-groupme 0.0.1

package/src/onboarding.ts

@@ -0,0 +1,154 @@
+import type { ChannelOnboardingAdapter } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { CoreConfig, GroupMeConfig } from "./types.js";
+import { resolveGroupMeAccount } from "./accounts.js";
+
+function applyGroupMeConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  updates: Record<string, unknown>;
+}): OpenClawConfig {
+  const { cfg, accountId, updates } = params;
+  const section = (cfg.channels?.groupme ?? {}) as GroupMeConfig;
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        groupme: {
+          ...section,
+          ...updates,
+          enabled: true,
+        },
+      },
+    };
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      groupme: {
+        ...section,
+        enabled: true,
+        accounts: {
+          ...(section.accounts ?? {}),
+          [accountId]: {
+            ...(section.accounts?.[accountId] ?? {}),
+            ...updates,
+            enabled: true,
+          },
+        },
+      },
+    },
+  };
+}
+
+export const groupmeOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel: "groupme",
+  getStatus: async ({ cfg, accountOverrides }) => {
+    const accountId = accountOverrides.groupme ?? DEFAULT_ACCOUNT_ID;
+    const account = resolveGroupMeAccount({
+      cfg: cfg as CoreConfig,
+      accountId,
+    });
+
+    const configured = account.configured;
+    return {
+      channel: "groupme",
+      configured,
+      statusLines: [
+        `GroupMe (${accountId}): ${configured ? "configured" : "needs botId"}`,
+        account.config.accessToken?.trim()
+          ? "Access token configured"
+          : "Access token missing (needed for image uploads)",
+      ],
+      selectionHint: configured ? "configured" : "needs bot ID",
+      quickstartScore: configured ? 1 : 0,
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides }) => {
+    const accountId = accountOverrides.groupme ?? DEFAULT_ACCOUNT_ID;
+
+    await prompter.note(
+      [
+        "GroupMe bots are bound to a single group.",
+        "Create a bot at https://dev.groupme.com/bots and copy bot_id + access token.",
+      ].join("\n"),
+      "GroupMe setup",
+    );
+
+    const botId = (
+      await prompter.text({
+        message: "Bot ID",
+        validate: (value) => (value.trim() ? undefined : "Bot ID is required"),
+      })
+    ).trim();
+
+    const accessToken = (
+      await prompter.text({
+        message: "Access token",
+        validate: (value) => (value.trim() ? undefined : "Access token is required"),
+      })
+    ).trim();
+
+    const botName = (
+      await prompter.text({
+        message: "Bot name (mention fallback)",
+        initialValue: "openclaw",
+      })
+    ).trim();
+
+    const callbackPath = (
+      await prompter.text({
+        message: "Webhook path",
+        initialValue: "/groupme",
+        validate: (value) => (value.trim().startsWith("/") ? undefined : "Path must start with /"),
+      })
+    ).trim();
+
+    const requireMention = await prompter.confirm({
+      message: "Require mention to respond?",
+      initialValue: true,
+    });
+
+    const next = applyGroupMeConfig({
+      cfg,
+      accountId,
+      updates: {
+        botId,
+        accessToken,
+        botName,
+        callbackPath,
+        requireMention,
+      },
+    });
+
+    await prompter.note(
+      [
+        "Next steps:",
+        `1. Set GroupMe callback URL to https://<your-domain>${callbackPath}`,
+        "2. Restart gateway",
+        "3. Send a message in the group to test",
+      ].join("\n"),
+      "GroupMe next steps",
+    );
+
+    return {
+      cfg: next,
+      accountId,
+    };
+  },
+  disable: (cfg) => ({
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      groupme: {
+        ...(cfg.channels?.groupme ?? {}),
+        enabled: false,
+      },
+    },
+  }),
+};

package/src/parse.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+import {
+  detectGroupMeMention,
+  extractImageUrls,
+  parseGroupMeCallback,
+  shouldProcessCallback,
+} from "./parse.js";
+
+const validPayload = {
+  id: "msg-1",
+  text: "hello @oddclaw",
+  name: "Alice",
+  sender_type: "user",
+  sender_id: "123",
+  user_id: "123",
+  group_id: "999",
+  source_guid: "src-1",
+  created_at: 1_700_000_000,
+  system: false,
+  avatar_url: "https://i.groupme.com/a.png",
+  attachments: [{ type: "image", url: "https://i.groupme.com/img" }],
+};
+
+describe("parseGroupMeCallback", () => {
+  it("parses a valid callback payload", () => {
+    const parsed = parseGroupMeCallback(validPayload);
+    expect(parsed).not.toBeNull();
+    expect(parsed?.id).toBe("msg-1");
+    expect(parsed?.senderType).toBe("user");
+    expect(parsed?.attachments).toHaveLength(1);
+  });
+
+  it("returns null for invalid payload", () => {
+    expect(parseGroupMeCallback(null)).toBeNull();
+    expect(parseGroupMeCallback({})).toBeNull();
+    expect(
+      parseGroupMeCallback({
+        ...validPayload,
+        sender_id: null,
+      }),
+    ).toBeNull();
+  });
+
+  it("handles missing text field by normalizing to empty string", () => {
+    const parsed = parseGroupMeCallback({
+      ...validPayload,
+      text: null,
+    });
+    expect(parsed?.text).toBe("");
+  });
+
+  it("extracts image URLs from attachments", () => {
+    const parsed = parseGroupMeCallback({
+      ...validPayload,
+      attachments: [
+        { type: "image", url: "https://i.groupme.com/one" },
+        { type: "emoji", placeholder: "x", charmap: [[1, 2]] },
+        { type: "image", url: "https://i.groupme.com/two" },
+      ],
+    });
+    expect(extractImageUrls(parsed?.attachments ?? [])).toEqual([
+      "https://i.groupme.com/one",
+      "https://i.groupme.com/two",
+    ]);
+  });
+});
+
+describe("shouldProcessCallback", () => {
+  it("accepts user messages", () => {
+    const parsed = parseGroupMeCallback(validPayload);
+    expect(parsed).not.toBeNull();
+    expect(shouldProcessCallback(parsed!)).toBeNull();
+  });
+
+  it("rejects bot messages", () => {
+    const parsed = parseGroupMeCallback({
+      ...validPayload,
+      sender_type: "bot",
+    });
+    expect(parsed).not.toBeNull();
+    expect(shouldProcessCallback(parsed!)).toBe("non-user message");
+  });
+
+  it("rejects system messages", () => {
+    const parsed = parseGroupMeCallback({
+      ...validPayload,
+      system: true,
+    });
+    expect(parsed).not.toBeNull();
+    expect(shouldProcessCallback(parsed!)).toBe("system message");
+  });
+
+  it("rejects empty messages with no attachments", () => {
+    const parsed = parseGroupMeCallback({
+      ...validPayload,
+      text: "  ",
+      attachments: [],
+    });
+    expect(parsed).not.toBeNull();
+    expect(shouldProcessCallback(parsed!)).toBe("empty message");
+  });
+
+  it("accepts image-only messages", () => {
+    const parsed = parseGroupMeCallback({
+      ...validPayload,
+      text: "",
+      attachments: [{ type: "image", url: "https://i.groupme.com/only" }],
+    });
+    expect(parsed).not.toBeNull();
+    expect(shouldProcessCallback(parsed!)).toBeNull();
+  });
+});
+
+describe("detectGroupMeMention", () => {
+  it("detects exact bot name mention", () => {
+    expect(detectGroupMeMention({ text: "oddclaw help", botName: "oddclaw" })).toBe(true);
+  });
+
+  it("detects @botname mention", () => {
+    expect(detectGroupMeMention({ text: "@oddclaw help", botName: "oddclaw" })).toBe(true);
+  });
+
+  it("is case-insensitive", () => {
+    expect(detectGroupMeMention({ text: "ODDCLAW", botName: "oddclaw" })).toBe(true);
+  });
+
+  it("uses mentionPatterns regex", () => {
+    expect(
+      detectGroupMeMention({
+        text: "hey there",
+        channelMentionPatterns: ["hey\\s+there"],
+      }),
+    ).toBe(true);
+  });
+
+  it("uses agent mention regexes", () => {
+    expect(
+      detectGroupMeMention({
+        text: "Need oddclaw now",
+        mentionRegexes: [/\boddclaw\b/i],
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false for unrelated messages", () => {
+    expect(detectGroupMeMention({ text: "random chat", botName: "oddclaw" })).toBe(false);
+  });
+
+  it("handles empty text", () => {
+    expect(detectGroupMeMention({ text: "", botName: "oddclaw" })).toBe(false);
+  });
+
+  it("ignores invalid regex patterns", () => {
+    expect(
+      detectGroupMeMention({
+        text: "oddclaw",
+        botName: "oddclaw",
+        channelMentionPatterns: ["[(invalid"],
+      }),
+    ).toBe(true);
+  });
+});

package/src/parse.ts

@@ -0,0 +1,273 @@
+import type {
+  GroupMeAttachment,
+  GroupMeCallbackData,
+  GroupMeEmojiAttachment,
+  GroupMeImageAttachment,
+  GroupMeLocationAttachment,
+  GroupMeMentionsAttachment,
+} from "./types.js";
+
+type JsonRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function readString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function readBoolean(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return undefined;
+}
+
+function parseNumberMatrix(value: unknown): number[][] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const rows: number[][] = [];
+  for (const row of value) {
+    if (!Array.isArray(row)) {
+      continue;
+    }
+    const parsedRow: number[] = [];
+    for (const cell of row) {
+      const num = readNumber(cell);
+      if (typeof num !== "number") {
+        continue;
+      }
+      parsedRow.push(num);
+    }
+    if (parsedRow.length > 0) {
+      rows.push(parsedRow);
+    }
+  }
+  return rows;
+}
+
+function parseStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.map((entry) => readString(entry)).filter((entry): entry is string => Boolean(entry));
+}
+
+function parseAttachment(entry: unknown): GroupMeAttachment | null {
+  if (!isRecord(entry)) {
+    return null;
+  }
+
+  const type = readString(entry.type);
+  if (!type) {
+    return null;
+  }
+
+  if (type === "image") {
+    const url = readString(entry.url);
+    if (!url) {
+      return null;
+    }
+    const imageAttachment: GroupMeImageAttachment = {
+      type,
+      url,
+    };
+    return imageAttachment;
+  }
+
+  if (type === "location") {
+    const lat = readString(entry.lat);
+    const lng = readString(entry.lng);
+    const name = readString(entry.name);
+    if (!lat || !lng || !name) {
+      return null;
+    }
+    const locationAttachment: GroupMeLocationAttachment = {
+      type,
+      lat,
+      lng,
+      name,
+    };
+    return locationAttachment;
+  }
+
+  if (type === "mentions") {
+    const mentionsAttachment: GroupMeMentionsAttachment = {
+      type,
+      user_ids: parseStringArray(entry.user_ids),
+      loci: parseNumberMatrix(entry.loci),
+    };
+    return mentionsAttachment;
+  }
+
+  if (type === "emoji") {
+    const placeholder = readString(entry.placeholder);
+    if (!placeholder) {
+      return null;
+    }
+    const emojiAttachment: GroupMeEmojiAttachment = {
+      type,
+      placeholder,
+      charmap: parseNumberMatrix(entry.charmap),
+    };
+    return emojiAttachment;
+  }
+
+  return {
+    ...entry,
+    type,
+  };
+}
+
+function parseAttachments(value: unknown): GroupMeAttachment[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const attachments: GroupMeAttachment[] = [];
+  for (const entry of value) {
+    const parsed = parseAttachment(entry);
+    if (parsed) {
+      attachments.push(parsed);
+    }
+  }
+  return attachments;
+}
+
+export function parseGroupMeCallback(data: unknown): GroupMeCallbackData | null {
+  if (!isRecord(data)) {
+    return null;
+  }
+
+  const id = readString(data.id);
+  const name = readString(data.name);
+  const senderType = readString(data.sender_type);
+  const senderId = readString(data.sender_id);
+  const userId = readString(data.user_id);
+  const groupId = readString(data.group_id);
+  const sourceGuid = readString(data.source_guid);
+  const createdAt = readNumber(data.created_at);
+
+  if (!id || !name || !senderType || !senderId || !userId || !groupId || !sourceGuid) {
+    return null;
+  }
+  if (typeof createdAt !== "number") {
+    return null;
+  }
+
+  const avatarUrl = readString(data.avatar_url) ?? null;
+  const text = typeof data.text === "string" ? data.text : "";
+
+  return {
+    id,
+    text,
+    name,
+    senderType,
+    senderId,
+    userId,
+    groupId,
+    sourceGuid,
+    createdAt,
+    system: readBoolean(data.system) ?? false,
+    avatarUrl,
+    attachments: parseAttachments(data.attachments),
+  };
+}
+
+export function hasImageAttachment(attachments: GroupMeAttachment[]): boolean {
+  return attachments.some((attachment) => attachment.type === "image");
+}
+
+export function shouldProcessCallback(msg: GroupMeCallbackData): string | null {
+  if (msg.senderType !== "user") {
+    return "non-user message";
+  }
+  if (msg.system) {
+    return "system message";
+  }
+  if (!msg.text.trim() && !hasImageAttachment(msg.attachments)) {
+    return "empty message";
+  }
+
+  return null;
+}
+
+export function extractImageUrls(attachments: GroupMeAttachment[]): string[] {
+  return attachments
+    .filter((attachment): attachment is GroupMeImageAttachment => attachment.type === "image")
+    .map((attachment) => attachment.url);
+}
+
+function normalizeMentionText(text: string): string {
+  return text.replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g, "").toLowerCase();
+}
+
+function buildRegexes(patterns?: string[]): RegExp[] {
+  if (!patterns || patterns.length === 0) {
+    return [];
+  }
+
+  return patterns
+    .map((pattern) => {
+      try {
+        return new RegExp(pattern, "i");
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry): entry is RegExp => Boolean(entry));
+}
+
+function escapeRegexLiteral(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function detectGroupMeMention(params: {
+  text: string;
+  botName?: string;
+  channelMentionPatterns?: string[];
+  mentionRegexes?: RegExp[];
+}): boolean {
+  const text = params.text?.trim() ?? "";
+  if (!text) {
+    return false;
+  }
+
+  const normalizedText = normalizeMentionText(text);
+  const channelRegexes = buildRegexes(params.channelMentionPatterns);
+  if (channelRegexes.some((regex) => regex.test(text))) {
+    return true;
+  }
+
+  const mentionRegexes = params.mentionRegexes ?? [];
+  if (mentionRegexes.some((regex) => regex.test(normalizedText))) {
+    return true;
+  }
+
+  const botName = params.botName?.trim();
+  if (!botName) {
+    return false;
+  }
+
+  const escaped = escapeRegexLiteral(botName);
+  const botRegex = new RegExp(`\\b@?${escaped}\\b`, "i");
+  return botRegex.test(text);
+}

package/src/policy.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { resolveSenderAccess } from "./policy.js";
+
+describe("resolveSenderAccess", () => {
+  it("allows all when allowFrom is empty", () => {
+    expect(resolveSenderAccess({ senderId: "123", allowFrom: [] })).toBe(true);
+    expect(resolveSenderAccess({ senderId: "123" })).toBe(true);
+  });
+
+  it("allows wildcard", () => {
+    expect(resolveSenderAccess({ senderId: "123", allowFrom: ["*"] })).toBe(true);
+  });
+
+  it("allows listed sender", () => {
+    expect(resolveSenderAccess({ senderId: "123", allowFrom: ["123"] })).toBe(true);
+    expect(resolveSenderAccess({ senderId: "123", allowFrom: [123] })).toBe(true);
+    expect(resolveSenderAccess({ senderId: "123", allowFrom: ["groupme:user:123"] })).toBe(true);
+  });
+
+  it("blocks unlisted sender", () => {
+    expect(resolveSenderAccess({ senderId: "999", allowFrom: ["123", "456"] })).toBe(false);
+  });
+});

package/src/policy.ts

@@ -0,0 +1,26 @@
+import { normalizeGroupMeAllowEntry, normalizeGroupMeUserId } from "./normalize.js";
+
+export function resolveSenderAccess(params: {
+  senderId: string;
+  allowFrom?: Array<string | number>;
+}): boolean {
+  const senderId = normalizeGroupMeUserId(params.senderId);
+  if (!senderId) {
+    return false;
+  }
+
+  const allowFrom = params.allowFrom ?? [];
+  if (allowFrom.length === 0) {
+    return true;
+  }
+
+  const normalizedAllow = allowFrom
+    .map((entry) => normalizeGroupMeAllowEntry(String(entry)))
+    .filter((entry): entry is string => Boolean(entry));
+
+  if (normalizedAllow.includes("*")) {
+    return true;
+  }
+
+  return normalizedAllow.includes(senderId);
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setGroupMeRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getGroupMeRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("GroupMe runtime not initialized");
+  }
+  return runtime;
+}