openclaw-groupme 0.3.0 → 0.4.1

package/README.md

@@ -5,7 +5,13 @@ An [OpenClaw](https://github.com/oddrationale/openclaw) channel plugin that brin
 ## Install
 
 ```bash
-openclaw plugins install openclaw-groupme
+openclaw plugins install clawhub:openclaw-groupme
+```
+
+You can also install directly from npm if you want npm to be the explicit source:
+
+```bash
+openclaw plugins install npm:openclaw-groupme
 ```
 
 After installing, restart the gateway so it picks up the new plugin:
@@ -148,6 +154,20 @@ If you prefer editing config files directly, here's what a complete setup looks
 }
 ```
 
+## Reconfiguring an Existing Setup
+
+If GroupMe is already configured and you run `openclaw configure` again, you'll get a menu of targeted actions instead of repeating the full wizard:
+
+- **Skip** — leave everything as-is
+- **Rotate access token** — replace the stored access token (validates the new token by fetching your groups)
+- **Change group** — pick a different GroupMe group and optionally register a new bot in it
+- **Regenerate callback URL** — create a new random callback path and secret token (you'll need to update the bot's callback URL in GroupMe afterward)
+- **Toggle requireMention** — flip mention-required mode on or off
+- **Update public domain** — change the public domain used for callback URLs
+- **Full re-setup** — start from scratch with the interactive wizard
+
+This lets you make quick adjustments — like rotating a leaked token or moving the bot to a different group — without tearing down the whole config.
+
 ## Response Modes
 
 ### Always respond (`requireMention: false`)
@@ -349,7 +369,18 @@ https://bot.example.com/groupme/e60b3e59da98950f?k=775c9958da544c73e6d97c04f8849
 
 ## Notes and Limitations
 
-- **Group chats only** — no DM support (GroupMe Bot API limitation)
+### GroupMe Bot API Constraints
+
+GroupMe bots are intentionally limited compared to full user accounts. These constraints come from the GroupMe Bot API itself, not from this plugin:
+
+- **Group chats only** — bots cannot send or receive direct messages. Each bot is bound to a single group.
+- **One group per bot** — a bot registration is tied to exactly one group. To serve multiple groups, register a separate bot (and account) for each.
+- **No message history** — bots only see messages as they arrive via the callback webhook. They cannot fetch past messages from the group. (This plugin buffers recent messages locally for context when `requireMention` is enabled.)
+- **No reactions** — bots cannot like or unlike messages.
+- **Text and images only** — bots can post text and attach a single image per message. Other attachment types (video, files, locations) are not supported.
+
+### Plugin-Specific Notes
+
 - Bot and system messages from GroupMe are automatically ignored
 - GroupMe has a 1000-character limit per message — longer replies are chunked automatically
 - Image replies require `accessToken` so the plugin can upload images to GroupMe's Image Service

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-groupme",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "OpenClaw GroupMe channel plugin",
   "license": "MIT",
   "keywords": [
@@ -36,12 +36,13 @@
     "zod": ">=4.3.6 <5"
   },
   "devDependencies": {
-    "openclaw": ">=2026.2.14",
-    "typescript": "^5.9.3",
+    "@types/node": "20.19.41",
+    "openclaw": "2026.2.26",
+    "typescript": "^6.0.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.2.14"
+    "openclaw": ">=2026.2.26 <2026.6.0"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -52,6 +53,12 @@
     "extensions": [
       "./index.ts"
     ],
+    "compat": {
+      "pluginApi": ">=2026.2.26 <2026.6.0"
+    },
+    "build": {
+      "openclawVersion": "2026.2.26"
+    },
     "channel": {
       "id": "groupme",
       "label": "GroupMe",

package/src/channel.ts

@@ -164,6 +164,15 @@ export const groupmePlugin: ChannelPlugin<
         },
       };
     },
+
+    resolveBindingAccountId: ({ cfg, accountId }) => {
+      if (accountId) return accountId;
+      const ids = listGroupMeAccountIds(cfg as CoreConfig);
+      if (ids.length <= 1) return DEFAULT_ACCOUNT_ID;
+      const section = (cfg as CoreConfig).channels?.groupme;
+      const explicitDefault = section?.defaultAccount?.trim();
+      return explicitDefault ? resolveDefaultGroupMeAccountId(cfg as CoreConfig) : undefined;
+    },
   } satisfies ChannelSetupAdapter,
   capabilities: {
     chatTypes: ["group"],

package/src/inbound.ts

@@ -365,6 +365,7 @@ export async function handleGroupMeInbound(params: {
     Timestamp: inboundTimestamp,
     OriginatingChannel: CHANNEL_ID,
     OriginatingTo: `groupme:group:${message.groupId}`,
+    GroupSpace: message.groupId,
     CommandAuthorized: commandGate.commandAuthorized,
     MediaUrl: imageUrls[0],
     MediaUrls: imageUrls.length > 0 ? imageUrls : undefined,

package/src/monitor.ts

@@ -24,6 +24,11 @@ import type {
   WebhookDecision,
 } from "./types.js";
 
+// GroupMe callbacks are small JSON payloads; use tighter limits than the SDK
+// defaults (DEFAULT_WEBHOOK_MAX_BODY_BYTES = 1 MB, DEFAULT_WEBHOOK_BODY_TIMEOUT_MS = 30 s).
+const GROUPME_WEBHOOK_MAX_BODY_BYTES = 64 * 1024;
+const GROUPME_WEBHOOK_BODY_TIMEOUT_MS = 15_000;
+
 export type GroupMeWebhookHandlerParams = {
   account: ResolvedGroupMeAccount;
   config: CoreConfig;
@@ -138,8 +143,8 @@ async function decideWebhookRequest(params: {
   }
 
   const body = await readJsonBodyWithLimit(params.req, {
-    maxBytes: 64 * 1024,
-    timeoutMs: 15_000,
+    maxBytes: GROUPME_WEBHOOK_MAX_BODY_BYTES,
+    timeoutMs: GROUPME_WEBHOOK_BODY_TIMEOUT_MS,
     emptyObjectOnEmpty: false,
   });
   if (!body.ok) {
@@ -226,6 +231,11 @@ export function createGroupMeWebhookHandler(
     params.account.config.historyLimit,
   );
   const security = resolveGroupMeSecurity(params.account.config);
+  if (!security.groupId) {
+    params.runtime.error?.(
+      "groupme: WARNING — no groupId configured; all inbound messages will be rejected. Set groupId in your account config.",
+    );
+  }
   const replayCache = new GroupMeReplayCache({
     ttlSeconds: security.replay.ttlSeconds,
     maxEntries: security.replay.maxEntries,

package/src/onboarding.ts

@@ -1,6 +1,8 @@
 import { randomBytes } from "node:crypto";
-import type { ChannelOnboardingAdapter } from "openclaw/plugin-sdk";
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type {
+  ChannelOnboardingAdapter,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
 import { resolveGroupMeAccount } from "./accounts.js";
 import { createBot, fetchGroups } from "./groupme-api.js";
@@ -48,6 +50,27 @@ function applyGroupMeConfig(params: {
   };
 }
 
+function parsePublicDomain(raw: string): string {
+  const trimmed = raw.trim();
+  try {
+    if (/^https?:\/\//i.test(trimmed)) {
+      const url = new URL(trimmed);
+      return url.port ? `${url.hostname}:${url.port}` : url.hostname;
+    }
+    const withoutLeadingSlashes = trimmed.replace(/^\/+/, "");
+    return withoutLeadingSlashes.split(/[\/?#]/, 1)[0];
+  } catch {
+    const noScheme = trimmed.replace(/^https?:\/\//i, "");
+    return noScheme.split(/[\/?#]/, 1)[0];
+  }
+}
+
+function generateCallbackUrl(): string {
+  const pathSegment = randomBytes(8).toString("hex");
+  const callbackToken = randomBytes(32).toString("hex");
+  return `/groupme/${pathSegment}?k=${callbackToken}`;
+}
+
 function redactMiddle(value: string): string {
   if (value.length <= 10) {
     return value;
@@ -158,28 +181,18 @@ export const groupmeOnboardingAdapter: ChannelOnboardingAdapter = {
           if (!normalized) {
             return "Public domain is required";
           }
+          const parsed = parsePublicDomain(trimmed);
+          if (!parsed) {
+            return "Public domain is required";
+          }
           return undefined;
         },
       })
     ).trim();
-    let publicDomain: string;
-    try {
-      if (/^https?:\/\//i.test(publicDomainRaw)) {
-        const url = new URL(publicDomainRaw);
-        publicDomain = url.port ? `${url.hostname}:${url.port}` : url.hostname;
-      } else {
-        const withoutLeadingSlashes = publicDomainRaw.replace(/^\/+/, "");
-        publicDomain = withoutLeadingSlashes.split(/[\/?#]/, 1)[0];
-      }
-    } catch {
-      // Fallback: best-effort stripping of scheme and any path/query/fragment
-      const noScheme = publicDomainRaw.replace(/^https?:\/\//i, "");
-      publicDomain = noScheme.split(/[\/?#]/, 1)[0];
-    }
+    const publicDomain = parsePublicDomain(publicDomainRaw);
 
-    const pathSegment = randomBytes(8).toString("hex");
-    const callbackToken = randomBytes(32).toString("hex");
-    const callbackUrl = `/groupme/${pathSegment}?k=${callbackToken}`;
+    const callbackUrl = generateCallbackUrl();
+    const pathSegment = callbackUrl.split("?")[0].split("/").pop()!;
     await prompter.note(
       `Generated webhook callback URL: /groupme/${pathSegment}?k=***`,
       "Generated callback URL",
@@ -241,6 +254,268 @@ export const groupmeOnboardingAdapter: ChannelOnboardingAdapter = {
       accountId,
     };
   },
+  configureWhenConfigured: async ({
+    cfg,
+    prompter,
+    runtime,
+    accountOverrides,
+  }) => {
+    const accountId = accountOverrides.groupme ?? DEFAULT_ACCOUNT_ID;
+    const account = resolveGroupMeAccount({
+      cfg: cfg as CoreConfig,
+      accountId,
+    });
+
+    const action = await prompter.select<string>({
+      message: "GroupMe is already configured. What would you like to do?",
+      options: [
+        { value: "skip", label: "Skip", hint: "no changes" },
+        { value: "rotate_token", label: "Rotate access token" },
+        { value: "change_group", label: "Change group" },
+        { value: "regen_callback", label: "Regenerate callback URL" },
+        { value: "toggle_mention", label: "Toggle requireMention" },
+        { value: "update_domain", label: "Update public domain" },
+        { value: "full_setup", label: "Full re-setup", hint: "start from scratch" },
+      ],
+    });
+
+    if (action === "skip") {
+      return "skip";
+    }
+
+    if (action === "full_setup") {
+      return groupmeOnboardingAdapter.configure({
+        cfg,
+        prompter,
+        runtime,
+        accountOverrides,
+        options: {},
+        shouldPromptAccountIds: false,
+        forceAllowFrom: false,
+      });
+    }
+
+    if (action === "rotate_token") {
+      const newToken = (
+        await prompter.text({
+          message: "New GroupMe access token",
+          validate: (value) =>
+            value.trim() ? undefined : "Access token is required",
+        })
+      ).trim();
+
+      const spin = prompter.progress("Validating access token...");
+      try {
+        await fetchGroups(newToken);
+        spin.stop("Token validated");
+      } catch {
+        spin.stop("Failed");
+        await prompter.note(
+          "Could not validate token. Check your access token and try again.",
+          "Validation failed",
+        );
+        throw new Error("Could not validate access token");
+      }
+
+      const next = applyGroupMeConfig({
+        cfg,
+        accountId,
+        updates: { accessToken: newToken },
+      });
+      await prompter.note("Access token updated.", "Token rotated");
+      return { cfg: next, accountId };
+    }
+
+    if (action === "change_group") {
+      const existingToken = account.accessToken;
+      if (!existingToken) {
+        await prompter.note(
+          "No access token configured. Use \"Rotate access token\" first.",
+          "Missing token",
+        );
+        return "skip";
+      }
+
+      const spin = prompter.progress("Fetching your GroupMe groups...");
+      let groups: Awaited<ReturnType<typeof fetchGroups>>;
+      try {
+        groups = await fetchGroups(existingToken);
+      } catch {
+        spin.stop("Failed");
+        await prompter.note(
+          "Could not fetch groups. Check your access token and try again.",
+          "GroupMe error",
+        );
+        throw new Error("Could not fetch groups");
+      }
+
+      if (groups.length === 0) {
+        spin.stop("No groups found");
+        await prompter.note(
+          "No groups found. Create or join a GroupMe group first.",
+          "No groups",
+        );
+        return "skip";
+      }
+      spin.stop(`Found ${groups.length} groups`);
+
+      const newGroupId = await prompter.select<string>({
+        message: "Select a GroupMe group",
+        options: groups.map((group) => ({
+          value: group.id,
+          label: group.name || group.id,
+          hint: group.id === account.config.groupId ? "current" : group.id,
+        })),
+      });
+
+      const selectedGroup = groups.find((g) => g.id === newGroupId);
+      const updates: Record<string, unknown> = { groupId: newGroupId };
+
+      const registerNew = await prompter.confirm({
+        message: "Register a new bot in this group?",
+        initialValue: true,
+      });
+
+      if (!registerNew) {
+        const newBotId = (
+          await prompter.text({
+            message:
+              "Bot ID for the new group (existing bot won't work in a different group)",
+            validate: (value) =>
+              value.trim() ? undefined : "Bot ID is required",
+          })
+        ).trim();
+        updates.botId = newBotId;
+      }
+
+      if (registerNew) {
+        const botName = account.config.botName || "openclaw";
+        let publicDomain = account.config.publicDomain;
+        if (!publicDomain) {
+          const domainRaw = (
+            await prompter.text({
+              message: "Public domain (required for bot registration)",
+              validate: (value) => {
+                const trimmed = value.trim();
+                if (!trimmed) return "Public domain is required";
+                const normalized = trimmed
+                  .replace(/^https?:\/\//, "")
+                  .replace(/\/+$/, "");
+                if (!normalized) return "Public domain is required";
+                const parsed = parsePublicDomain(trimmed);
+                if (!parsed) return "Public domain is required";
+                return undefined;
+              },
+            })
+          ).trim();
+          publicDomain = parsePublicDomain(domainRaw);
+          updates.publicDomain = publicDomain;
+        }
+        let rawCallbackUrl = account.config.callbackUrl;
+        if (!rawCallbackUrl) {
+          rawCallbackUrl = generateCallbackUrl();
+          updates.callbackUrl = rawCallbackUrl;
+        }
+        const parsedCallback = new URL(rawCallbackUrl, "http://localhost");
+        const callbackPath = `${parsedCallback.pathname}${parsedCallback.search}`;
+
+        const botSpin = prompter.progress("Registering bot with GroupMe...");
+        try {
+          const bot = await createBot({
+            accessToken: existingToken,
+            name: botName,
+            groupId: newGroupId,
+            callbackUrl: `https://${publicDomain}${callbackPath}`,
+          });
+          updates.botId = bot.bot_id;
+          botSpin.stop("Bot registered");
+        } catch (error) {
+          botSpin.stop("Failed");
+          const detail =
+            error instanceof Error ? `\n\nDetails: ${error.message}` : "";
+          await prompter.note(
+            `Failed to register bot.${detail}`,
+            "Bot registration failed",
+          );
+          throw new Error("Failed to register GroupMe bot", {
+            cause: error instanceof Error ? error : undefined,
+          });
+        }
+      }
+
+      const next = applyGroupMeConfig({ cfg, accountId, updates });
+      await prompter.note(
+        `Group changed to "${selectedGroup?.name ?? newGroupId}".`,
+        "Group updated",
+      );
+      return { cfg: next, accountId };
+    }
+
+    if (action === "regen_callback") {
+      const callbackUrl = generateCallbackUrl();
+      const next = applyGroupMeConfig({
+        cfg,
+        accountId,
+        updates: { callbackUrl },
+      });
+      await prompter.note(
+        [
+          "Callback URL regenerated.",
+          "Remember to update your GroupMe bot settings or re-register the bot.",
+        ].join("\n"),
+        "Callback URL updated",
+      );
+      return { cfg: next, accountId };
+    }
+
+    if (action === "toggle_mention") {
+      const current = account.config.requireMention ?? true;
+      const next = applyGroupMeConfig({
+        cfg,
+        accountId,
+        updates: { requireMention: !current },
+      });
+      await prompter.note(
+        `requireMention changed from ${current} to ${!current}.`,
+        "Mention setting updated",
+      );
+      return { cfg: next, accountId };
+    }
+
+    if (action === "update_domain") {
+      const newDomainRaw = (
+        await prompter.text({
+          message: "New public domain",
+          initialValue: account.config.publicDomain ?? "",
+          validate: (value) => {
+            const trimmed = value.trim();
+            if (!trimmed) return "Public domain is required";
+            const normalized = trimmed
+              .replace(/^https?:\/\//, "")
+              .replace(/\/+$/, "");
+            if (!normalized) return "Public domain is required";
+            const parsed = parsePublicDomain(trimmed);
+            if (!parsed) return "Public domain is required";
+            return undefined;
+          },
+        })
+      ).trim();
+
+      const publicDomain = parsePublicDomain(newDomainRaw);
+      const next = applyGroupMeConfig({
+        cfg,
+        accountId,
+        updates: { publicDomain },
+      });
+      await prompter.note(
+        `Public domain updated to "${publicDomain}".`,
+        "Domain updated",
+      );
+      return { cfg: next, accountId };
+    }
+
+    return "skip";
+  },
   disable: (cfg) => ({
     ...cfg,
     channels: {

package/src/security.ts

@@ -1,4 +1,4 @@
-import { timingSafeEqual } from "node:crypto";
+import { createHash, timingSafeEqual } from "node:crypto";
 import type { IncomingHttpHeaders } from "node:http";
 import { BlockList, isIP } from "node:net";
 import { readTrimmed } from "./accounts.js";
@@ -309,12 +309,9 @@ export function resolveGroupMeSecurity(
 }
 
 function safeEqualToken(left: string, right: string): boolean {
-  const leftBuffer = Buffer.from(left);
-  const rightBuffer = Buffer.from(right);
-  if (leftBuffer.length !== rightBuffer.length) {
-    return false;
-  }
-  return timingSafeEqual(leftBuffer, rightBuffer);
+  const leftHash = createHash("sha256").update(left).digest();
+  const rightHash = createHash("sha256").update(right).digest();
+  return timingSafeEqual(leftHash, rightHash);
 }
 
 export function verifyCallbackAuth(params: {