openclaw-groupme 0.0.4 → 0.4.0

package/src/accounts.ts

@@ -1,4 +1,7 @@
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+} from "openclaw/plugin-sdk/account-id";
 import type {
   CoreConfig,
   GroupMeAccountConfig,
@@ -9,9 +12,11 @@ import type {
 const ENV_BOT_ID = "GROUPME_BOT_ID";
 const ENV_ACCESS_TOKEN = "GROUPME_ACCESS_TOKEN";
 const ENV_BOT_NAME = "GROUPME_BOT_NAME";
-const ENV_CALLBACK_PATH = "GROUPME_CALLBACK_PATH";
+const ENV_CALLBACK_URL = "GROUPME_CALLBACK_URL";
+const ENV_GROUP_ID = "GROUPME_GROUP_ID";
+const ENV_PUBLIC_DOMAIN = "GROUPME_PUBLIC_DOMAIN";
 
-function readTrimmed(value: unknown): string | undefined {
+export function readTrimmed(value: unknown): string | undefined {
   if (typeof value !== "string") {
     return undefined;
   }
@@ -49,15 +54,22 @@ function resolveAccountConfig(
     return accounts[accountId];
   }
 
-  const hit = Object.keys(accounts).find((key) => normalizeAccountId(key) === accountId);
+  const hit = Object.keys(accounts).find(
+    (key) => normalizeAccountId(key) === accountId,
+  );
   return hit ? accounts[hit] : undefined;
 }
 
-function mergeAccountConfig(cfg: CoreConfig, accountId: string): GroupMeAccountConfig {
+function mergeAccountConfig(
+  cfg: CoreConfig,
+  accountId: string,
+): GroupMeAccountConfig {
   const raw = (cfg.channels?.groupme ?? {}) as GroupMeConfig;
   const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
   const account =
-    accountId === DEFAULT_ACCOUNT_ID ? {} : (resolveAccountConfig(cfg, accountId) ?? {});
+    accountId === DEFAULT_ACCOUNT_ID
+      ? {}
+      : (resolveAccountConfig(cfg, accountId) ?? {});
 
   return {
     ...base,
@@ -66,17 +78,13 @@ function mergeAccountConfig(cfg: CoreConfig, accountId: string): GroupMeAccountC
 }
 
 export function listGroupMeAccountIds(cfg: CoreConfig): string[] {
-  const ids = new Set<string>([DEFAULT_ACCOUNT_ID]);
-  for (const id of listConfiguredAccountIds(cfg)) {
-    ids.add(id);
-  }
-
-  const ordered = [...ids].toSorted((a, b) => a.localeCompare(b));
-  if (ordered[0] !== DEFAULT_ACCOUNT_ID) {
-    ordered.unshift(DEFAULT_ACCOUNT_ID);
-    return Array.from(new Set(ordered));
-  }
-  return ordered;
+  const sorted = listConfiguredAccountIds(cfg).toSorted((a, b) =>
+    a.localeCompare(b),
+  );
+  return [
+    DEFAULT_ACCOUNT_ID,
+    ...sorted.filter((id) => id !== DEFAULT_ACCOUNT_ID),
+  ];
 }
 
 export function resolveDefaultGroupMeAccountId(cfg: CoreConfig): string {
@@ -94,7 +102,9 @@ export function resolveGroupMeAccount(params: {
 }): ResolvedGroupMeAccount {
   const normalizedRequested = normalizeAccountId(params.accountId);
   const accountId =
-    normalizedRequested || resolveDefaultGroupMeAccountId(params.cfg) || DEFAULT_ACCOUNT_ID;
+    normalizedRequested ||
+    resolveDefaultGroupMeAccountId(params.cfg) ||
+    DEFAULT_ACCOUNT_ID;
 
   const merged = mergeAccountConfig(params.cfg, accountId);
   const baseEnabled = params.cfg.channels?.groupme?.enabled !== false;
@@ -108,15 +118,31 @@ export function resolveGroupMeAccount(params: {
     "";
   const accessToken =
     readTrimmed(merged.accessToken) ||
-    (isDefaultAccount ? readTrimmed(process.env[ENV_ACCESS_TOKEN]) : undefined) ||
+    (isDefaultAccount
+      ? readTrimmed(process.env[ENV_ACCESS_TOKEN])
+      : undefined) ||
     "";
   const botName =
     readTrimmed(merged.botName) ||
     (isDefaultAccount ? readTrimmed(process.env[ENV_BOT_NAME]) : undefined) ||
     undefined;
-  const callbackPath =
-    readTrimmed(merged.callbackPath) ||
-    (isDefaultAccount ? readTrimmed(process.env[ENV_CALLBACK_PATH]) : undefined) ||
+  const groupId =
+    readTrimmed(merged.groupId) ||
+    (isDefaultAccount
+      ? readTrimmed(process.env[ENV_GROUP_ID])
+      : undefined) ||
+    undefined;
+  const callbackUrl =
+    readTrimmed(merged.callbackUrl) ||
+    (isDefaultAccount
+      ? readTrimmed(process.env[ENV_CALLBACK_URL])
+      : undefined) ||
+    undefined;
+  const publicDomain =
+    readTrimmed(merged.publicDomain) ||
+    (isDefaultAccount
+      ? readTrimmed(process.env[ENV_PUBLIC_DOMAIN])
+      : undefined) ||
     undefined;
 
   const config: GroupMeAccountConfig = {
@@ -124,7 +150,9 @@ export function resolveGroupMeAccount(params: {
     botId,
     accessToken,
     botName,
-    callbackPath,
+    groupId,
+    publicDomain,
+    callbackUrl,
   };
 
   return {

package/src/channel.ts

@@ -1,13 +1,22 @@
 import {
+  applyAccountNameToChannelSection,
   buildChannelConfigSchema,
   DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
+  migrateBaseNameToDefaultAccount,
   missingTargetError,
+  normalizeAccountId,
   registerPluginHttpRoute,
   setAccountEnabledInConfigSection,
   type ChannelPlugin,
+  type ChannelSetupAdapter,
 } from "openclaw/plugin-sdk";
-import type { CoreConfig, GroupMeProbe, ResolvedGroupMeAccount } from "./types.js";
+import type {
+  CoreConfig,
+  GroupMeConfig,
+  GroupMeProbe,
+  ResolvedGroupMeAccount,
+} from "./types.js";
 import {
   listGroupMeAccountIds,
   resolveDefaultGroupMeAccountId,
@@ -22,10 +31,44 @@ import {
 } from "./normalize.js";
 import { groupmeOnboardingAdapter } from "./onboarding.js";
 import { getGroupMeRuntime } from "./runtime.js";
-import { GROUPME_MAX_TEXT_LENGTH, sendGroupMeMedia, sendGroupMeText } from "./send.js";
+import { redactCallbackUrl, resolveGroupMeSecurity } from "./security.js";
+import {
+  GROUPME_MAX_TEXT_LENGTH,
+  sendGroupMeMedia,
+  sendGroupMeText,
+} from "./send.js";
 
 const CHANNEL_ID = "groupme" as const;
 
+function normalizeCallbackUrl(raw: string | undefined): string {
+  const trimmed = raw?.trim() ?? "";
+  if (!trimmed) {
+    return "/groupme";
+  }
+  try {
+    const parsed = new URL(trimmed, "http://localhost");
+    return parsed.pathname || "/groupme";
+  } catch {
+    const noQuery = trimmed.split("?")[0] ?? trimmed;
+    if (!noQuery) {
+      return "/groupme";
+    }
+    return noQuery.startsWith("/") ? noQuery : `/${noQuery}`;
+  }
+}
+
+function redactWebhookPath(
+  account: ResolvedGroupMeAccount,
+  callbackUrl: string | undefined,
+): string {
+  const normalized = callbackUrl?.trim() || "/groupme";
+  const security = resolveGroupMeSecurity(account.config);
+  if (!security.logging.redactSecrets) {
+    return normalized;
+  }
+  return redactCallbackUrl(normalized, security);
+}
+
 const meta = {
   id: CHANNEL_ID,
   label: "GroupMe",
@@ -38,10 +81,99 @@ const meta = {
   quickstartAllowFrom: true,
 };
 
-export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe> = {
+export const groupmePlugin: ChannelPlugin<
+  ResolvedGroupMeAccount,
+  GroupMeProbe
+> = {
   id: CHANNEL_ID,
   meta,
   onboarding: groupmeOnboardingAdapter,
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "groupme",
+        accountId,
+        name,
+      }),
+
+    validateInput: ({ input }) => {
+      if (!input.token?.trim()) {
+        return "GroupMe Bot ID is required (--token <bot-id>)";
+      }
+      return null;
+    },
+
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      let next = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "groupme",
+        accountId,
+        name: input.name,
+      });
+
+      if (accountId !== DEFAULT_ACCOUNT_ID) {
+        next = migrateBaseNameToDefaultAccount({
+          cfg: next,
+          channelKey: "groupme",
+        });
+      }
+
+      const updates: Record<string, unknown> = { enabled: true };
+      if (input.token?.trim()) updates.botId = input.token.trim();
+      if (input.accessToken?.trim())
+        updates.accessToken = input.accessToken.trim();
+      if (input.webhookUrl?.trim()) {
+        updates.callbackUrl = input.webhookUrl.trim();
+      } else if (input.webhookPath?.trim()) {
+        updates.callbackUrl = input.webhookPath.trim();
+      }
+
+      const section = (next.channels?.groupme ?? {}) as GroupMeConfig;
+
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            groupme: {
+              ...section,
+              ...updates,
+            },
+          },
+        };
+      }
+
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          groupme: {
+            ...section,
+            enabled: true,
+            accounts: {
+              ...(section.accounts ?? {}),
+              [accountId]: {
+                ...(section.accounts?.[accountId] ?? {}),
+                ...updates,
+              },
+            },
+          },
+        },
+      };
+    },
+
+    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"],
     media: true,
@@ -53,7 +185,8 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
     listAccountIds: (cfg) => listGroupMeAccountIds(cfg as CoreConfig),
     resolveAccount: (cfg, accountId) =>
       resolveGroupMeAccount({ cfg: cfg as CoreConfig, accountId }),
-    defaultAccountId: (cfg) => resolveDefaultGroupMeAccountId(cfg as CoreConfig),
+    defaultAccountId: (cfg) =>
+      resolveDefaultGroupMeAccountId(cfg as CoreConfig),
     setAccountEnabled: ({ cfg, accountId, enabled }) =>
       setAccountEnabledInConfigSection({
         cfg: cfg as CoreConfig,
@@ -72,12 +205,16 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
           "botId",
           "accessToken",
           "botName",
-          "callbackPath",
+          "groupId",
+          "publicDomain",
+          "callbackUrl",
           "mentionPatterns",
           "requireMention",
+          "historyLimit",
           "allowFrom",
           "textChunkLimit",
           "responsePrefix",
+          "security",
         ],
       }),
     isConfigured: (account) => account.configured,
@@ -87,12 +224,14 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
       enabled: account.enabled,
       configured: account.configured,
       botId: account.botId ? "***" : "",
-      callbackPath: account.config.callbackPath,
+      publicDomain: account.config.publicDomain ?? "",
+      callbackUrl: redactWebhookPath(account, account.config.callbackUrl),
     }),
     resolveAllowFrom: ({ cfg, accountId }) =>
-      (resolveGroupMeAccount({ cfg: cfg as CoreConfig, accountId }).config.allowFrom ?? []).map(
-        (entry) => String(entry),
-      ),
+      (
+        resolveGroupMeAccount({ cfg: cfg as CoreConfig, accountId }).config
+          .allowFrom ?? []
+      ).map((entry) => String(entry)),
     formatAllowFrom: ({ allowFrom }) =>
       allowFrom
         .map((entry) => normalizeGroupMeAllowEntry(String(entry)))
@@ -109,7 +248,8 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
   },
   outbound: {
     deliveryMode: "direct",
-    chunker: (text, limit) => getGroupMeRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunker: (text, limit) =>
+      getGroupMeRuntime().channel.text.chunkMarkdownText(text, limit),
     chunkerMode: "markdown",
     textChunkLimit: GROUPME_MAX_TEXT_LENGTH,
     resolveTarget: ({ to }) => {
@@ -215,7 +355,7 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
     buildChannelSummary: ({ snapshot }) => ({
       configured: snapshot.configured ?? false,
       running: snapshot.running ?? false,
-      callbackPath: snapshot.webhookPath ?? null,
+      callbackUrl: snapshot.webhookPath ?? null,
       lastStartAt: snapshot.lastStartAt ?? null,
       lastStopAt: snapshot.lastStopAt ?? null,
       lastInboundAt: snapshot.lastInboundAt ?? null,
@@ -229,7 +369,7 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
       configured: account.configured,
       botId: account.botId ? "***" : "",
       tokenSource: account.accessToken ? "configured" : "none",
-      webhookPath: account.config.callbackPath ?? "/groupme",
+      webhookPath: redactWebhookPath(account, account.config.callbackUrl),
       running: runtime?.running ?? false,
       lastStartAt: runtime?.lastStartAt ?? null,
       lastStopAt: runtime?.lastStopAt ?? null,
@@ -248,7 +388,11 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
         );
       }
 
-      const callbackPath = account.config.callbackPath?.trim() || "/groupme";
+      const callbackPath = normalizeCallbackUrl(account.config.callbackUrl);
+      const redactedCallbackPath = redactWebhookPath(
+        account,
+        account.config.callbackUrl ?? callbackPath,
+      );
       const unregister = registerPluginHttpRoute({
         path: callbackPath,
         fallbackPath: "/groupme",
@@ -256,7 +400,8 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
           account,
           config: ctx.cfg as CoreConfig,
           runtime: ctx.runtime,
-          statusSink: (patch) => ctx.setStatus({ accountId: account.accountId, ...patch }),
+          statusSink: (patch) =>
+            ctx.setStatus({ accountId: account.accountId, ...patch }),
         }),
         pluginId: CHANNEL_ID,
         accountId: account.accountId,
@@ -267,12 +412,14 @@ export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe>
         accountId: account.accountId,
         running: true,
         mode: "webhook",
-        webhookPath: callbackPath,
+        webhookPath: redactedCallbackPath,
         lastStartAt: Date.now(),
         lastError: null,
       });
 
-      ctx.log?.info(`[${account.accountId}] GroupMe webhook listening on ${callbackPath}`);
+      ctx.log?.info(
+        `[${account.accountId}] GroupMe webhook listening on ${redactedCallbackPath}`,
+      );
 
       if (ctx.abortSignal.aborted) {
         unregister();

package/src/config-schema.ts

@@ -1,8 +1,72 @@
-import { BlockStreamingCoalesceSchema, MarkdownConfigSchema } from "openclaw/plugin-sdk";
+import {
+  BlockStreamingCoalesceSchema,
+  MarkdownConfigSchema,
+} from "openclaw/plugin-sdk";
 import { z } from "zod";
 
 const allowFromEntry = z.union([z.string(), z.number()]);
 
+const GroupMeReplaySchema = z
+  .object({
+    ttlSeconds: z.number().int().positive().optional(),
+    maxEntries: z.number().int().positive().optional(),
+  })
+  .strict();
+
+const GroupMeRateLimitSchema = z
+  .object({
+    windowMs: z.number().int().positive().optional(),
+    maxRequestsPerIp: z.number().int().positive().optional(),
+    maxRequestsPerSender: z.number().int().positive().optional(),
+    maxConcurrent: z.number().int().positive().optional(),
+  })
+  .strict();
+
+const GroupMeMediaSecuritySchema = z
+  .object({
+    allowPrivateNetworks: z.boolean().optional().default(false),
+    maxDownloadBytes: z.number().int().positive().optional(),
+    requestTimeoutMs: z.number().int().positive().optional(),
+    allowedMimePrefixes: z.array(z.string()).optional(),
+  })
+  .strict();
+
+const GroupMeLoggingSecuritySchema = z
+  .object({
+    redactSecrets: z.boolean().optional().default(true),
+    logRejectedRequests: z.boolean().optional().default(true),
+  })
+  .strict();
+
+const GroupMeCommandBypassSecuritySchema = z
+  .object({
+    requireAllowFrom: z.boolean().optional().default(true),
+    requireMentionForCommands: z.boolean().optional().default(false),
+  })
+  .strict();
+
+const GroupMeProxySecuritySchema = z
+  .object({
+    trustedProxyCidrs: z.array(z.string()).optional(),
+    allowedPublicHosts: z.array(z.string()).optional(),
+    requireHttpsProto: z.boolean().optional().default(false),
+    rejectStatus: z
+      .union([z.literal(400), z.literal(403), z.literal(404)])
+      .optional(),
+  })
+  .strict();
+
+const GroupMeSecuritySchema = z
+  .object({
+    replay: GroupMeReplaySchema.optional(),
+    rateLimit: GroupMeRateLimitSchema.optional(),
+    media: GroupMeMediaSecuritySchema.optional(),
+    logging: GroupMeLoggingSecuritySchema.optional(),
+    commandBypass: GroupMeCommandBypassSecuritySchema.optional(),
+    proxy: GroupMeProxySecuritySchema.optional(),
+  })
+  .strict();
+
 export const GroupMeAccountSchemaBase = z
   .object({
     name: z.string().optional(),
@@ -10,9 +74,12 @@ export const GroupMeAccountSchemaBase = z
     botId: z.string().optional(),
     accessToken: z.string().optional(),
     botName: z.string().optional(),
-    callbackPath: z.string().optional(),
+    groupId: z.string().optional(),
+    publicDomain: z.string().optional(),
+    callbackUrl: z.string().optional(),
     mentionPatterns: z.array(z.string()).optional(),
     requireMention: z.boolean().optional().default(true),
+    historyLimit: z.number().int().nonnegative().optional(),
     allowFrom: z.array(allowFromEntry).optional(),
     markdown: MarkdownConfigSchema,
     textChunkLimit: z.number().int().positive().optional(),
@@ -20,10 +87,13 @@ export const GroupMeAccountSchemaBase = z
     blockStreamingCoalesce: BlockStreamingCoalesceSchema.optional(),
     responsePrefix: z.string().optional(),
     mediaMaxMb: z.number().positive().optional(),
+    security: GroupMeSecuritySchema.optional(),
   })
   .strict();
 
 export const GroupMeConfigSchema = GroupMeAccountSchemaBase.extend({
-  accounts: z.record(z.string(), GroupMeAccountSchemaBase.optional()).optional(),
+  accounts: z
+    .record(z.string(), GroupMeAccountSchemaBase.optional())
+    .optional(),
   defaultAccount: z.string().optional(),
 }).strict();

package/src/groupme-api.ts

@@ -0,0 +1,98 @@
+import type { GroupMeApiBot, GroupMeApiGroup } from "./types.js";
+
+const GROUPME_API_BASE = "https://api.groupme.com/v3";
+
+async function readApiError(response: Response): Promise<string> {
+  const fallback = `GroupMe API error: ${response.status} ${response.statusText}`;
+  try {
+    const payload = (await response.json()) as { meta?: { errors?: unknown } };
+    const errors = payload?.meta?.errors;
+    if (Array.isArray(errors) && errors.length > 0) {
+      const text = errors
+        .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+        .filter(Boolean)
+        .join("; ");
+      if (text) {
+        return `${fallback} (${text})`;
+      }
+    }
+  } catch {
+    // Ignore JSON parse errors; fall back to generic status text.
+  }
+  return fallback;
+}
+
+function readGroupsResponse(payload: unknown): GroupMeApiGroup[] {
+  const response = (payload as { response?: unknown })?.response;
+  if (!Array.isArray(response)) {
+    throw new Error("GroupMe groups fetch returned an invalid payload");
+  }
+  return response as GroupMeApiGroup[];
+}
+
+function readBotResponse(payload: unknown): GroupMeApiBot {
+  const bot = (payload as { response?: { bot?: unknown } })?.response?.bot;
+  if (!bot) {
+    throw new Error("GroupMe bot creation returned an invalid payload");
+  }
+  return bot as GroupMeApiBot;
+}
+
+export async function fetchGroups(accessToken: string): Promise<GroupMeApiGroup[]> {
+  const groups: GroupMeApiGroup[] = [];
+  let page = 1;
+
+  while (true) {
+    const url = new URL(`${GROUPME_API_BASE}/groups`);
+    url.searchParams.set("token", accessToken);
+    url.searchParams.set("per_page", "100");
+    url.searchParams.set("omit", "memberships");
+    url.searchParams.set("page", String(page));
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(await readApiError(response));
+    }
+
+    const payload = await response.json();
+    const pageGroups = readGroupsResponse(payload);
+    if (pageGroups.length === 0) {
+      break;
+    }
+
+    groups.push(...pageGroups);
+    page += 1;
+  }
+
+  return groups;
+}
+
+export async function createBot(params: {
+  accessToken: string;
+  name: string;
+  groupId: string;
+  callbackUrl: string;
+}): Promise<GroupMeApiBot> {
+  const url = new URL(`${GROUPME_API_BASE}/bots`);
+  url.searchParams.set("token", params.accessToken);
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      bot: {
+        name: params.name,
+        group_id: params.groupId,
+        callback_url: params.callbackUrl,
+        active: true,
+      },
+    }),
+  });
+  if (!response.ok) {
+    const apiError = await readApiError(response);
+    throw new Error(`GroupMe bot creation failed: ${apiError}`);
+  }
+
+  const payload = await response.json();
+  return readBotResponse(payload);
+}

package/src/history.ts

@@ -0,0 +1,54 @@
+import type { HistoryEntry } from "openclaw/plugin-sdk";
+
+export const DEFAULT_GROUPME_HISTORY_LIMIT = 20;
+
+export function resolveGroupMeHistoryLimit(configured?: number): number {
+  if (!Number.isFinite(configured)) {
+    return DEFAULT_GROUPME_HISTORY_LIMIT;
+  }
+
+  const normalized = Math.floor(configured as number);
+  if (normalized < 0) {
+    return DEFAULT_GROUPME_HISTORY_LIMIT;
+  }
+
+  return normalized;
+}
+
+export function resolveGroupMeBodyForAgent(params: {
+  rawBody: string;
+  imageUrls: string[];
+}): string {
+  const { rawBody, imageUrls } = params;
+  const trimmed = rawBody.trim();
+  if (trimmed) {
+    return trimmed;
+  }
+  if (imageUrls.length > 0) {
+    return imageUrls.map((url) => `Image: ${url}`).join("\n");
+  }
+  return rawBody;
+}
+
+export function buildGroupMeHistoryEntry(params: {
+  senderName: string;
+  body: string;
+  timestamp: number;
+  messageId: string;
+}): HistoryEntry | null {
+  const body = params.body.trim();
+  if (!body) {
+    return null;
+  }
+
+  return {
+    sender: params.senderName,
+    body,
+    timestamp: params.timestamp,
+    messageId: params.messageId,
+  };
+}
+
+export function formatGroupMeHistoryEntry(entry: HistoryEntry): string {
+  return `${entry.sender}: ${entry.body}`;
+}