openclaw-groupme 0.0.1

package/src/inbound.ts

@@ -0,0 +1,310 @@
+import type { OpenClawConfig, ReplyPayload, RuntimeEnv } from "openclaw/plugin-sdk";
+import {
+  createReplyPrefixOptions,
+  logInboundDrop,
+  resolveControlCommandGate,
+  resolveMentionGatingWithBypass,
+} from "openclaw/plugin-sdk";
+import type { GroupMeCallbackData, ResolvedGroupMeAccount, CoreConfig } from "./types.js";
+import { extractImageUrls, detectGroupMeMention } from "./parse.js";
+import { resolveSenderAccess } from "./policy.js";
+import { getGroupMeRuntime } from "./runtime.js";
+import { GROUPME_MAX_TEXT_LENGTH, sendGroupMeMedia, sendGroupMeText } from "./send.js";
+
+const CHANNEL_ID = "groupme" as const;
+
+function resolveTextChunkLimit(account: ResolvedGroupMeAccount): number {
+  const configured = account.config.textChunkLimit;
+  if (!Number.isFinite(configured)) {
+    return GROUPME_MAX_TEXT_LENGTH;
+  }
+  const value = Math.floor(configured as number);
+  if (value <= 0) {
+    return GROUPME_MAX_TEXT_LENGTH;
+  }
+  return Math.min(value, GROUPME_MAX_TEXT_LENGTH);
+}
+
+function chunkReplyText(params: {
+  text: string;
+  limit: number;
+  core: ReturnType<typeof getGroupMeRuntime>;
+}): string[] {
+  const trimmed = params.text.trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  return params.core.channel.text.chunkMarkdownText(trimmed, params.limit).filter(Boolean);
+}
+
+async function deliverGroupMeReply(params: {
+  payload: ReplyPayload;
+  account: ResolvedGroupMeAccount;
+  cfg: CoreConfig;
+  target: string;
+  statusSink?: (patch: { lastOutboundAt?: number }) => void;
+}) {
+  const { payload, account, cfg, target, statusSink } = params;
+  const core = getGroupMeRuntime();
+
+  const text = payload.text ?? "";
+  const mediaUrls = payload.mediaUrls?.length
+    ? payload.mediaUrls
+    : payload.mediaUrl
+      ? [payload.mediaUrl]
+      : [];
+
+  if (!text.trim() && mediaUrls.length === 0) {
+    return;
+  }
+
+  const chunks = chunkReplyText({
+    text,
+    limit: resolveTextChunkLimit(account),
+    core,
+  });
+
+  const sendTextChunk = async (chunk: string) => {
+    await sendGroupMeText({
+      cfg,
+      to: target,
+      text: chunk,
+      accountId: account.accountId,
+    });
+    statusSink?.({ lastOutboundAt: Date.now() });
+    core.channel.activity.record({
+      channel: CHANNEL_ID,
+      accountId: account.accountId,
+      direction: "outbound",
+    });
+  };
+
+  if (mediaUrls.length === 0) {
+    for (const chunk of chunks) {
+      await sendTextChunk(chunk);
+    }
+    return;
+  }
+
+  const [firstMedia, ...restMedia] = mediaUrls;
+  const [firstChunk, ...restChunks] = chunks;
+
+  await sendGroupMeMedia({
+    cfg,
+    to: target,
+    text: firstChunk ?? "",
+    mediaUrl: firstMedia,
+    accountId: account.accountId,
+  });
+  statusSink?.({ lastOutboundAt: Date.now() });
+  core.channel.activity.record({
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    direction: "outbound",
+  });
+
+  for (const chunk of restChunks) {
+    await sendTextChunk(chunk);
+  }
+
+  for (const mediaUrl of restMedia) {
+    await sendGroupMeMedia({
+      cfg,
+      to: target,
+      text: "",
+      mediaUrl,
+      accountId: account.accountId,
+    });
+    statusSink?.({ lastOutboundAt: Date.now() });
+    core.channel.activity.record({
+      channel: CHANNEL_ID,
+      accountId: account.accountId,
+      direction: "outbound",
+    });
+  }
+}
+
+export async function handleGroupMeInbound(params: {
+  message: GroupMeCallbackData;
+  account: ResolvedGroupMeAccount;
+  config: CoreConfig;
+  runtime: RuntimeEnv;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+}): Promise<void> {
+  const { message, account, config, runtime, statusSink } = params;
+  const core = getGroupMeRuntime();
+
+  const inboundTimestamp = message.createdAt * 1000;
+  statusSink?.({ lastInboundAt: inboundTimestamp });
+  core.channel.activity.record({
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    direction: "inbound",
+    at: inboundTimestamp,
+  });
+
+  const allowFrom = account.config.allowFrom ?? [];
+  const senderAllowed = resolveSenderAccess({
+    senderId: message.senderId,
+    allowFrom,
+  });
+  if (!senderAllowed) {
+    runtime.log?.(`groupme: drop sender ${message.senderId} (not in allowFrom)`);
+    return;
+  }
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config as OpenClawConfig,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    peer: {
+      kind: "group",
+      id: message.groupId,
+    },
+  });
+
+  const mentionRegexes = core.channel.mentions.buildMentionRegexes(
+    config as OpenClawConfig,
+    route.agentId,
+  );
+  const wasMentioned = detectGroupMeMention({
+    text: message.text,
+    botName: account.config.botName,
+    channelMentionPatterns: account.config.mentionPatterns,
+    mentionRegexes,
+  });
+
+  const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+    cfg: config as OpenClawConfig,
+    surface: CHANNEL_ID,
+  });
+  const hasControlCommand = core.channel.text.hasControlCommand(
+    message.text,
+    config as OpenClawConfig,
+  );
+
+  const commandGate = resolveControlCommandGate({
+    useAccessGroups: config.commands?.useAccessGroups !== false,
+    authorizers: [{ configured: allowFrom.length > 0, allowed: senderAllowed }],
+    allowTextCommands,
+    hasControlCommand,
+  });
+  if (commandGate.shouldBlock) {
+    logInboundDrop({
+      log: (line) => runtime.log?.(line),
+      channel: CHANNEL_ID,
+      reason: "control command (unauthorized)",
+      target: message.senderId,
+    });
+    return;
+  }
+
+  const mentionGate = resolveMentionGatingWithBypass({
+    isGroup: true,
+    requireMention: account.config.requireMention ?? true,
+    canDetectMention: true,
+    wasMentioned,
+    hasAnyMention: false,
+    allowTextCommands,
+    hasControlCommand,
+    commandAuthorized: commandGate.commandAuthorized,
+  });
+
+  if (mentionGate.shouldSkip) {
+    runtime.log?.("groupme: skip message (mention required, not mentioned)");
+    return;
+  }
+
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config as OpenClawConfig);
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+
+  const imageUrls = extractImageUrls(message.attachments);
+  const rawBody = message.text;
+  const bodyForAgent =
+    rawBody.trim() ||
+    (imageUrls.length > 0 ? imageUrls.map((url) => `Image: ${url}`).join("\n") : rawBody);
+
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "GroupMe",
+    from: message.name,
+    timestamp: inboundTimestamp,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: bodyForAgent,
+  });
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    BodyForAgent: bodyForAgent,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: `groupme:user:${message.senderId}`,
+    To: `groupme:group:${message.groupId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: "group",
+    ConversationLabel: `groupme:${message.groupId}`,
+    SenderName: message.name,
+    SenderId: message.senderId,
+    Provider: CHANNEL_ID,
+    Surface: CHANNEL_ID,
+    WasMentioned: mentionGate.effectiveWasMentioned,
+    MessageSid: message.id,
+    Timestamp: inboundTimestamp,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo: `groupme:group:${message.groupId}`,
+    CommandAuthorized: commandGate.commandAuthorized,
+    MediaUrl: imageUrls[0],
+    MediaUrls: imageUrls.length > 0 ? imageUrls : undefined,
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => {
+      runtime.error?.(`groupme: failed updating session meta: ${String(err)}`);
+    },
+  });
+
+  const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+    cfg: config as OpenClawConfig,
+    agentId: route.agentId,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+  });
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config as OpenClawConfig,
+    dispatcherOptions: {
+      ...prefixOptions,
+      deliver: async (payload) => {
+        await deliverGroupMeReply({
+          payload,
+          account,
+          cfg: config,
+          target: `groupme:group:${message.groupId}`,
+          statusSink,
+        });
+      },
+      onError: (err, info) => {
+        runtime.error?.(`groupme ${info.kind} reply failed: ${String(err)}`);
+      },
+    },
+    replyOptions: {
+      onModelSelected,
+      disableBlockStreaming:
+        typeof account.config.blockStreaming === "boolean"
+          ? !account.config.blockStreaming
+          : undefined,
+    },
+  });
+}

package/src/monitor.test.ts

@@ -0,0 +1,186 @@
+import type { AddressInfo } from "node:net";
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { createServer } from "node:http";
+import { describe, expect, it, vi } from "vitest";
+import type { CoreConfig, ResolvedGroupMeAccount } from "./types.js";
+
+const handleGroupMeInboundMock = vi.hoisted(() => vi.fn(async () => undefined));
+
+vi.mock("./inbound.js", () => ({
+  handleGroupMeInbound: handleGroupMeInboundMock,
+}));
+
+import { createGroupMeWebhookHandler } from "./monitor.js";
+
+async function withServer(
+  handler: Parameters<typeof createServer>[0],
+  fn: (baseUrl: string) => Promise<void>,
+) {
+  const server = createServer(handler);
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: Error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(0, "127.0.0.1");
+  });
+
+  const address = server.address() as AddressInfo | null;
+  if (!address) {
+    throw new Error("missing server address");
+  }
+
+  try {
+    await fn(`http://127.0.0.1:${address.port}`);
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+function isListenPermissionError(error: unknown): boolean {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const maybeErr = error as { code?: unknown; syscall?: unknown };
+  return maybeErr.code === "EPERM" && maybeErr.syscall === "listen";
+}
+
+async function runIfServerAllowed(fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn();
+  } catch (error) {
+    if (isListenPermissionError(error)) {
+      return;
+    }
+    throw error;
+  }
+}
+
+function buildRuntime(): RuntimeEnv {
+  return {
+    log: vi.fn(),
+    error: vi.fn(),
+    exit: (() => {
+      throw new Error("exit");
+    }) as RuntimeEnv["exit"],
+  };
+}
+
+const account: ResolvedGroupMeAccount = {
+  accountId: "default",
+  enabled: true,
+  configured: true,
+  botId: "bot-1",
+  accessToken: "token-1",
+  config: {
+    botId: "bot-1",
+    accessToken: "token-1",
+  },
+};
+
+const config = {} as CoreConfig;
+
+describe("createGroupMeWebhookHandler", () => {
+  it("returns 405 for non-POST", async () => {
+    const runtime = buildRuntime();
+    const handler = createGroupMeWebhookHandler({ account, config, runtime });
+
+    await runIfServerAllowed(async () => {
+      await withServer(
+        async (req, res) => handler(req, res),
+        async (baseUrl) => {
+          const response = await fetch(`${baseUrl}/groupme`, { method: "GET" });
+          expect(response.status).toBe(405);
+          expect(await response.text()).toBe("Method Not Allowed");
+        },
+      );
+    });
+  });
+
+  it("returns 400 for invalid JSON", async () => {
+    const runtime = buildRuntime();
+    const handler = createGroupMeWebhookHandler({ account, config, runtime });
+
+    await runIfServerAllowed(async () => {
+      await withServer(
+        async (req, res) => handler(req, res),
+        async (baseUrl) => {
+          const response = await fetch(`${baseUrl}/groupme`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: "{",
+          });
+          expect(response.status).toBe(400);
+        },
+      );
+    });
+  });
+
+  it("acknowledges parseable payload and dispatches inbound", async () => {
+    handleGroupMeInboundMock.mockClear();
+    const runtime = buildRuntime();
+    const handler = createGroupMeWebhookHandler({ account, config, runtime });
+
+    const payload = {
+      id: "msg-1",
+      text: "hello",
+      name: "Alice",
+      sender_type: "user",
+      sender_id: "123",
+      user_id: "123",
+      group_id: "456",
+      source_guid: "source",
+      created_at: 1_700_000_000,
+      system: false,
+      attachments: [],
+    };
+
+    await runIfServerAllowed(async () => {
+      await withServer(
+        async (req, res) => handler(req, res),
+        async (baseUrl) => {
+          const response = await fetch(`${baseUrl}/groupme`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(payload),
+          });
+          expect(response.status).toBe(200);
+          expect(await response.text()).toBe("ok");
+
+          // Wait for fire-and-forget processing.
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          expect(handleGroupMeInboundMock).toHaveBeenCalledTimes(1);
+        },
+      );
+    });
+  });
+
+  it("drops unparseable payload after returning 200", async () => {
+    handleGroupMeInboundMock.mockClear();
+    const runtime = buildRuntime();
+    const handler = createGroupMeWebhookHandler({ account, config, runtime });
+
+    await runIfServerAllowed(async () => {
+      await withServer(
+        async (req, res) => handler(req, res),
+        async (baseUrl) => {
+          const response = await fetch(`${baseUrl}/groupme`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ nope: true }),
+          });
+          expect(response.status).toBe(200);
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          expect(handleGroupMeInboundMock).not.toHaveBeenCalled();
+          expect(runtime.log).toHaveBeenCalledWith("groupme: unparseable callback payload");
+        },
+      );
+    });
+  });
+});

package/src/monitor.ts

@@ -0,0 +1,63 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { readJsonBodyWithLimit, requestBodyErrorToText } from "openclaw/plugin-sdk";
+import type { CoreConfig, ResolvedGroupMeAccount } from "./types.js";
+import { handleGroupMeInbound } from "./inbound.js";
+import { parseGroupMeCallback, shouldProcessCallback } from "./parse.js";
+
+export type GroupMeWebhookHandlerParams = {
+  account: ResolvedGroupMeAccount;
+  config: CoreConfig;
+  runtime: RuntimeEnv;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+export function createGroupMeWebhookHandler(
+  params: GroupMeWebhookHandlerParams,
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+  return async (req, res) => {
+    if (req.method !== "POST") {
+      res.statusCode = 405;
+      res.setHeader("Allow", "POST");
+      res.end("Method Not Allowed");
+      return;
+    }
+
+    const body = await readJsonBodyWithLimit(req, {
+      maxBytes: 64 * 1024,
+      timeoutMs: 15_000,
+      emptyObjectOnEmpty: false,
+    });
+    if (!body.ok) {
+      res.statusCode =
+        body.code === "PAYLOAD_TOO_LARGE" ? 413 : body.code === "REQUEST_BODY_TIMEOUT" ? 408 : 400;
+      res.end(body.code === "INVALID_JSON" ? body.error : requestBodyErrorToText(body.code));
+      return;
+    }
+
+    res.statusCode = 200;
+    res.end("ok");
+
+    const message = parseGroupMeCallback(body.value);
+    if (!message) {
+      params.runtime.log?.("groupme: unparseable callback payload");
+      return;
+    }
+
+    const ignoreReason = shouldProcessCallback(message);
+    if (ignoreReason) {
+      params.runtime.log?.(`groupme: ignoring message (${ignoreReason})`);
+      return;
+    }
+
+    void handleGroupMeInbound({
+      message,
+      account: params.account,
+      config: params.config,
+      runtime: params.runtime,
+      statusSink: params.statusSink,
+    }).catch((err) => {
+      params.runtime.error?.(`groupme: inbound processing failed: ${String(err)}`);
+    });
+  };
+}

package/src/normalize.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import {
+  looksLikeGroupMeTargetId,
+  normalizeGroupMeAllowEntry,
+  normalizeGroupMeGroupId,
+  normalizeGroupMeTarget,
+  normalizeGroupMeUserId,
+} from "./normalize.js";
+
+describe("groupme normalize", () => {
+  it("normalizes user and group ids", () => {
+    expect(normalizeGroupMeUserId(" 123 ")).toBe("123");
+    expect(normalizeGroupMeGroupId(456)).toBe("456");
+  });
+
+  it("returns undefined for empty IDs", () => {
+    expect(normalizeGroupMeUserId("   ")).toBeUndefined();
+    expect(normalizeGroupMeGroupId("")).toBeUndefined();
+  });
+
+  it("normalizes prefixed targets", () => {
+    expect(normalizeGroupMeTarget("groupme:group:12345")).toBe("12345");
+    expect(normalizeGroupMeTarget("groupme:user:54321")).toBe("54321");
+    expect(normalizeGroupMeTarget("group:abc")).toBe("abc");
+    expect(normalizeGroupMeTarget("12345")).toBe("12345");
+  });
+
+  it("returns undefined for empty target", () => {
+    expect(normalizeGroupMeTarget("  ")).toBeUndefined();
+  });
+
+  it("normalizes allow entries and keeps wildcard", () => {
+    expect(normalizeGroupMeAllowEntry("groupme:user:123")).toBe("123");
+    expect(normalizeGroupMeAllowEntry("*")).toBe("*");
+  });
+
+  it("validates likely target IDs", () => {
+    expect(looksLikeGroupMeTargetId("groupme:group:123")).toBe(true);
+    expect(looksLikeGroupMeTargetId("abc-123")).toBe(true);
+    expect(looksLikeGroupMeTargetId("has spaces")).toBe(false);
+    expect(looksLikeGroupMeTargetId(" ")).toBe(false);
+  });
+});

package/src/normalize.ts

@@ -0,0 +1,43 @@
+function normalizeStringId(raw: string | number): string | undefined {
+  const normalized = String(raw).trim();
+  return normalized || undefined;
+}
+
+export function normalizeGroupMeUserId(raw: string | number): string | undefined {
+  return normalizeStringId(raw);
+}
+
+export function normalizeGroupMeGroupId(raw: string | number): string | undefined {
+  return normalizeStringId(raw);
+}
+
+const TARGET_PREFIX_RE = /^(groupme:)?(user:|group:)?/i;
+
+export function normalizeGroupMeTarget(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const stripped = trimmed.replace(TARGET_PREFIX_RE, "").trim();
+  return stripped || undefined;
+}
+
+export function normalizeGroupMeAllowEntry(raw: string): string | undefined {
+  const normalized = normalizeGroupMeTarget(raw);
+  if (!normalized) {
+    return undefined;
+  }
+  return normalized.toLowerCase() === "*" ? "*" : normalized;
+}
+
+export function looksLikeGroupMeTargetId(raw: string): boolean {
+  const normalized = normalizeGroupMeTarget(raw);
+  if (!normalized) {
+    return false;
+  }
+  if (normalized === "*") {
+    return false;
+  }
+  return !/\s/.test(normalized);
+}