@openclaw/googlechat 2026.5.2-beta.1

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@openclaw/googlechat",
+  "version": "2026.5.2-beta.1",
+  "description": "OpenClaw Google Chat channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
+  "type": "module",
+  "dependencies": {
+    "gaxios": "7.1.4",
+    "google-auth-library": "10.6.2",
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*",
+    "openclaw": "workspace:*"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.5.2-beta.1"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "googlechat",
+      "label": "Google Chat",
+      "selectionLabel": "Google Chat (Chat API)",
+      "detailLabel": "Google Chat",
+      "docsPath": "/channels/googlechat",
+      "docsLabel": "googlechat",
+      "blurb": "Google Workspace Chat app with HTTP webhook.",
+      "aliases": [
+        "gchat",
+        "google-chat"
+      ],
+      "order": 55,
+      "systemImage": "message.badge",
+      "markdownCapable": true,
+      "doctorCapabilities": {
+        "dmAllowFromMode": "nestedOnly",
+        "groupModel": "route",
+        "groupAllowFromFallbackToAllowFrom": false,
+        "warnOnEmptyGroupSenderAllowlist": false
+      },
+      "cliAddOptions": [
+        {
+          "flags": "--webhook-path <path>",
+          "description": "Google Chat webhook path"
+        },
+        {
+          "flags": "--webhook-url <url>",
+          "description": "Google Chat webhook URL"
+        },
+        {
+          "flags": "--audience-type <type>",
+          "description": "Google Chat audience type (app-url|project-number)"
+        },
+        {
+          "flags": "--audience <value>",
+          "description": "Google Chat audience value (app URL or project number)"
+        }
+      ]
+    },
+    "install": {
+      "npmSpec": "@openclaw/googlechat",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.2-beta.1"
+    },
+    "build": {
+      "openclawVersion": "2026.5.2-beta.1"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,60 @@
+// Private runtime barrel for the bundled Google Chat extension.
+// Keep this barrel thin and avoid broad plugin-sdk surfaces during bootstrap.
+
+export { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+export {
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+} from "openclaw/plugin-sdk/channel-actions";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
+export type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+  ChannelStatusIssue,
+} from "openclaw/plugin-sdk/channel-contract";
+export { missingTargetError } from "openclaw/plugin-sdk/channel-feedback";
+export {
+  createAccountStatusSink,
+  runPassiveAccountLifecycle,
+} from "openclaw/plugin-sdk/channel-lifecycle";
+export { createChannelPairingController } from "openclaw/plugin-sdk/channel-pairing";
+export { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
+export {
+  evaluateGroupRouteAccessForPolicy,
+  resolveDmGroupAccessWithLists,
+  resolveSenderScopedGroupPolicy,
+} from "openclaw/plugin-sdk/channel-policy";
+export { PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk/channel-status";
+export { chunkTextForOutbound } from "openclaw/plugin-sdk/text-chunking";
+export type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+export { GoogleChatConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
+export {
+  GROUP_POLICY_BLOCKED_LABEL,
+  resolveAllowlistProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
+  warnMissingProviderGroupPolicyFallbackOnce,
+} from "openclaw/plugin-sdk/runtime-group-policy";
+export { isDangerousNameMatchingEnabled } from "openclaw/plugin-sdk/dangerous-name-runtime";
+export { fetchRemoteMedia, resolveChannelMediaMaxBytes } from "openclaw/plugin-sdk/media-runtime";
+export { loadOutboundMediaFromUrl } from "openclaw/plugin-sdk/outbound-media";
+export type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
+export { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
+export type { GoogleChatAccountConfig, GoogleChatConfig } from "openclaw/plugin-sdk/config-types";
+export { extractToolSend } from "openclaw/plugin-sdk/tool-send";
+export { resolveInboundMentionDecision } from "openclaw/plugin-sdk/channel-inbound";
+export { resolveInboundRouteEnvelopeBuilderWithRuntime } from "openclaw/plugin-sdk/inbound-envelope";
+export { resolveWebhookPath } from "openclaw/plugin-sdk/webhook-path";
+export {
+  registerWebhookTargetWithPluginRoute,
+  resolveWebhookTargetWithAuthOrReject,
+  withResolvedWebhookRequestPipeline,
+} from "openclaw/plugin-sdk/webhook-targets";
+export {
+  createWebhookInFlightLimiter,
+  readJsonWebhookBodyOrReject,
+  type WebhookInFlightLimiter,
+} from "openclaw/plugin-sdk/webhook-request-guards";
+export { setGoogleChatRuntime } from "./src/runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-entry.ts

@@ -0,0 +1,13 @@
+import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "googlechatSetupPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled setup entry imports narrow so setup loads do not pull the
+// broader Google Chat runtime plugin surface.
+export { googlechatSetupPlugin } from "./src/channel.setup.js";

package/src/accounts.ts

@@ -0,0 +1,169 @@
+import {
+  createAccountListHelpers,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type OpenClawConfig,
+  resolveAccountEntry,
+  resolveMergedAccountConfig,
+} from "openclaw/plugin-sdk/account-resolution";
+import { safeParseJsonWithSchema, safeParseWithSchema } from "openclaw/plugin-sdk/extension-shared";
+import { isSecretRef } from "openclaw/plugin-sdk/secret-input";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { z } from "zod";
+import type { GoogleChatAccountConfig } from "./types.config.js";
+
+type GoogleChatCredentialSource = "file" | "inline" | "env" | "none";
+
+export type ResolvedGoogleChatAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  config: GoogleChatAccountConfig;
+  credentialSource: GoogleChatCredentialSource;
+  credentials?: Record<string, unknown>;
+  credentialsFile?: string;
+};
+
+export type GoogleChatConfigAccessorAccount = {
+  config: GoogleChatAccountConfig;
+};
+
+const ENV_SERVICE_ACCOUNT = "GOOGLE_CHAT_SERVICE_ACCOUNT";
+const ENV_SERVICE_ACCOUNT_FILE = "GOOGLE_CHAT_SERVICE_ACCOUNT_FILE";
+const JsonRecordSchema = z.record(z.string(), z.unknown());
+
+const {
+  listAccountIds: listGoogleChatAccountIds,
+  resolveDefaultAccountId: resolveDefaultGoogleChatAccountId,
+} = createAccountListHelpers("googlechat");
+export { listGoogleChatAccountIds, resolveDefaultGoogleChatAccountId };
+
+function mergeGoogleChatAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+): GoogleChatAccountConfig {
+  const raw = cfg.channels?.["googlechat"] ?? {};
+  const base = resolveMergedAccountConfig<GoogleChatAccountConfig>({
+    channelConfig: raw as GoogleChatAccountConfig,
+    accounts: raw.accounts as Record<string, Partial<GoogleChatAccountConfig>> | undefined,
+    accountId,
+    omitKeys: ["defaultAccount"],
+  });
+  const defaultAccountConfig = resolveAccountEntry(raw.accounts, DEFAULT_ACCOUNT_ID) ?? {};
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return base;
+  }
+  const {
+    enabled: _ignoredEnabled,
+    dangerouslyAllowNameMatching: _ignoredDangerouslyAllowNameMatching,
+    serviceAccount: _ignoredServiceAccount,
+    serviceAccountRef: _ignoredServiceAccountRef,
+    serviceAccountFile: _ignoredServiceAccountFile,
+    ...defaultAccountShared
+  } = defaultAccountConfig;
+  // In multi-account setups, allow accounts.default to provide shared defaults
+  // (for example webhook/audience fields) while preserving top-level and account overrides.
+  return { ...defaultAccountShared, ...base } as GoogleChatAccountConfig;
+}
+
+export function resolveGoogleChatConfigAccessorAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): GoogleChatConfigAccessorAccount {
+  const accountId = normalizeAccountId(
+    params.accountId ?? params.cfg.channels?.googlechat?.defaultAccount,
+  );
+  return { config: mergeGoogleChatAccountConfig(params.cfg, accountId) };
+}
+
+function parseServiceAccount(value: unknown): Record<string, unknown> | null {
+  if (isSecretRef(value)) {
+    return null;
+  }
+
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return null;
+    }
+    return safeParseJsonWithSchema(JsonRecordSchema, trimmed);
+  }
+
+  return safeParseWithSchema(JsonRecordSchema, value);
+}
+
+function resolveCredentialsFromConfig(params: {
+  accountId: string;
+  account: GoogleChatAccountConfig;
+}): {
+  credentials?: Record<string, unknown>;
+  credentialsFile?: string;
+  source: GoogleChatCredentialSource;
+} {
+  const { account, accountId } = params;
+  const inline = parseServiceAccount(account.serviceAccount);
+  if (inline) {
+    return { credentials: inline, source: "inline" };
+  }
+
+  if (isSecretRef(account.serviceAccount)) {
+    throw new Error(
+      `channels.googlechat.accounts.${accountId}.serviceAccount: unresolved SecretRef "${account.serviceAccount.source}:${account.serviceAccount.provider}:${account.serviceAccount.id}". Resolve this command against an active gateway runtime snapshot before reading it.`,
+    );
+  }
+
+  if (isSecretRef(account.serviceAccountRef)) {
+    throw new Error(
+      `channels.googlechat.accounts.${accountId}.serviceAccount: unresolved SecretRef "${account.serviceAccountRef.source}:${account.serviceAccountRef.provider}:${account.serviceAccountRef.id}". Resolve this command against an active gateway runtime snapshot before reading it.`,
+    );
+  }
+
+  const file = normalizeOptionalString(account.serviceAccountFile);
+  if (file) {
+    return { credentialsFile: file, source: "file" };
+  }
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const envJson = process.env[ENV_SERVICE_ACCOUNT];
+    const envInline = parseServiceAccount(envJson);
+    if (envInline) {
+      return { credentials: envInline, source: "env" };
+    }
+    const envFile = normalizeOptionalString(process.env[ENV_SERVICE_ACCOUNT_FILE]);
+    if (envFile) {
+      return { credentialsFile: envFile, source: "env" };
+    }
+  }
+
+  return { source: "none" };
+}
+
+export function resolveGoogleChatAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedGoogleChatAccount {
+  const accountId = normalizeAccountId(
+    params.accountId ?? params.cfg.channels?.["googlechat"]?.defaultAccount,
+  );
+  const baseEnabled = params.cfg.channels?.["googlechat"]?.enabled !== false;
+  const merged = mergeGoogleChatAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+  const credentials = resolveCredentialsFromConfig({ accountId, account: merged });
+
+  return {
+    accountId,
+    name: normalizeOptionalString(merged.name),
+    enabled,
+    config: merged,
+    credentialSource: credentials.source,
+    credentials: credentials.credentials,
+    credentialsFile: credentials.credentialsFile,
+  };
+}
+
+export function listEnabledGoogleChatAccounts(cfg: OpenClawConfig): ResolvedGoogleChatAccount[] {
+  return listGoogleChatAccountIds(cfg)
+    .map((accountId) => resolveGoogleChatAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

package/src/actions.test.ts

@@ -0,0 +1,265 @@
+import path from "node:path";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const listEnabledGoogleChatAccounts = vi.hoisted(() => vi.fn());
+const resolveGoogleChatAccount = vi.hoisted(() => vi.fn());
+const createGoogleChatReaction = vi.hoisted(() => vi.fn());
+const deleteGoogleChatReaction = vi.hoisted(() => vi.fn());
+const listGoogleChatReactions = vi.hoisted(() => vi.fn());
+const sendGoogleChatMessage = vi.hoisted(() => vi.fn());
+const uploadGoogleChatAttachment = vi.hoisted(() => vi.fn());
+const resolveGoogleChatOutboundSpace = vi.hoisted(() => vi.fn());
+const getGoogleChatRuntime = vi.hoisted(() => vi.fn());
+
+vi.mock("./accounts.js", () => ({
+  listEnabledGoogleChatAccounts,
+  resolveGoogleChatAccount,
+}));
+
+vi.mock("./api.js", () => ({
+  createGoogleChatReaction,
+  deleteGoogleChatReaction,
+  listGoogleChatReactions,
+  sendGoogleChatMessage,
+  uploadGoogleChatAttachment,
+}));
+
+vi.mock("./runtime.js", () => ({
+  getGoogleChatRuntime,
+}));
+
+vi.mock("./targets.js", () => ({
+  resolveGoogleChatOutboundSpace,
+}));
+
+let googlechatMessageActions: typeof import("./actions.js").googlechatMessageActions;
+
+describe("googlechat message actions", () => {
+  beforeAll(async () => {
+    ({ googlechatMessageActions } = await import("./actions.js"));
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("describes send and reaction actions only when enabled accounts exist", async () => {
+    listEnabledGoogleChatAccounts.mockReturnValueOnce([]);
+    expect(googlechatMessageActions.describeMessageTool?.({ cfg: {} as never })).toBeNull();
+
+    listEnabledGoogleChatAccounts.mockReturnValueOnce([
+      {
+        enabled: true,
+        credentialSource: "service-account",
+        config: { actions: { reactions: true } },
+      },
+    ]);
+
+    expect(googlechatMessageActions.describeMessageTool?.({ cfg: {} as never })).toEqual({
+      actions: ["send", "upload-file", "react", "reactions"],
+    });
+  });
+
+  it("honors account-scoped reaction gates during discovery", () => {
+    resolveGoogleChatAccount.mockImplementation(({ accountId }: { accountId?: string | null }) => ({
+      enabled: true,
+      credentialSource: "service-account",
+      config: {
+        actions: { reactions: accountId === "work" },
+      },
+    }));
+
+    expect(
+      googlechatMessageActions.describeMessageTool?.({ cfg: {} as never, accountId: "default" }),
+    ).toEqual({
+      actions: ["send", "upload-file"],
+    });
+    expect(
+      googlechatMessageActions.describeMessageTool?.({ cfg: {} as never, accountId: "work" }),
+    ).toEqual({
+      actions: ["send", "upload-file", "react", "reactions"],
+    });
+  });
+
+  it("sends messages with uploaded media through the resolved space", async () => {
+    resolveGoogleChatAccount.mockReturnValue({
+      credentialSource: "service-account",
+      config: { mediaMaxMb: 5 },
+    });
+    resolveGoogleChatOutboundSpace.mockResolvedValue("spaces/AAA");
+    getGoogleChatRuntime.mockReturnValue({
+      channel: {
+        media: {
+          fetchRemoteMedia: vi.fn(async () => ({
+            buffer: Buffer.from("remote-bytes"),
+            fileName: "remote.png",
+            contentType: "image/png",
+          })),
+        },
+      },
+    });
+    uploadGoogleChatAttachment.mockResolvedValue({
+      attachmentUploadToken: "token-1",
+    });
+    sendGoogleChatMessage.mockResolvedValue({
+      messageName: "spaces/AAA/messages/msg-1",
+    });
+
+    if (!googlechatMessageActions.handleAction) {
+      throw new Error("Expected googlechatMessageActions.handleAction to be defined");
+    }
+    const result = await googlechatMessageActions.handleAction({
+      action: "send",
+      params: {
+        to: "spaces/AAA",
+        message: "caption",
+        media: "https://example.com/file.png",
+        threadId: "thread-1",
+      },
+      cfg: {},
+      accountId: "default",
+    } as never);
+
+    expect(resolveGoogleChatOutboundSpace).toHaveBeenCalledWith(
+      expect.objectContaining({
+        target: "spaces/AAA",
+      }),
+    );
+    expect(uploadGoogleChatAttachment).toHaveBeenCalledWith(
+      expect.objectContaining({
+        space: "spaces/AAA",
+        filename: "remote.png",
+      }),
+    );
+    expect(sendGoogleChatMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        space: "spaces/AAA",
+        text: "caption",
+        thread: "thread-1",
+      }),
+    );
+    expect(result).toMatchObject({
+      details: {
+        ok: true,
+        to: "spaces/AAA",
+      },
+    });
+  });
+
+  it("routes upload-file through the same attachment upload path with filename override", async () => {
+    resolveGoogleChatAccount.mockReturnValue({
+      credentialSource: "service-account",
+      config: { mediaMaxMb: 5 },
+    });
+    resolveGoogleChatOutboundSpace.mockResolvedValue("spaces/BBB");
+    const localRoot = "/tmp/googlechat-action-test";
+    const localPath = path.join(localRoot, "local.md");
+    const readFile = vi.fn(async () => Buffer.from("local-bytes"));
+    getGoogleChatRuntime.mockReturnValue({
+      channel: {
+        media: {
+          fetchRemoteMedia: vi.fn(),
+        },
+      },
+    });
+    uploadGoogleChatAttachment.mockResolvedValue({
+      attachmentUploadToken: "token-2",
+    });
+    sendGoogleChatMessage.mockResolvedValue({
+      messageName: "spaces/BBB/messages/msg-2",
+    });
+
+    if (!googlechatMessageActions.handleAction) {
+      throw new Error("Expected googlechatMessageActions.handleAction to be defined");
+    }
+    const result = await googlechatMessageActions.handleAction({
+      action: "upload-file",
+      params: {
+        to: "spaces/BBB",
+        path: localPath,
+        message: "notes",
+        filename: "renamed.txt",
+      },
+      cfg: {},
+      accountId: "default",
+      mediaLocalRoots: [localRoot],
+      mediaReadFile: readFile,
+    } as never);
+
+    expect(readFile).toHaveBeenCalledWith(localPath);
+    expect(uploadGoogleChatAttachment).toHaveBeenCalledWith(
+      expect.objectContaining({
+        space: "spaces/BBB",
+        filename: "renamed.txt",
+        buffer: Buffer.from("local-bytes"),
+      }),
+    );
+    expect(sendGoogleChatMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        space: "spaces/BBB",
+        text: "notes",
+        attachments: [{ attachmentUploadToken: "token-2", contentName: "renamed.txt" }],
+      }),
+    );
+    expect(result).toMatchObject({
+      details: {
+        ok: true,
+        to: "spaces/BBB",
+      },
+    });
+  });
+
+  it("removes only matching app reactions on react remove", async () => {
+    resolveGoogleChatAccount.mockReturnValue({
+      credentialSource: "service-account",
+      config: { botUser: "users/app-bot" },
+    });
+    listGoogleChatReactions.mockResolvedValue([
+      {
+        name: "reactions/1",
+        emoji: { unicode: "👍" },
+        user: { name: "users/app" },
+      },
+      {
+        name: "reactions/2",
+        emoji: { unicode: "👍" },
+        user: { name: "users/app-bot" },
+      },
+      {
+        name: "reactions/3",
+        emoji: { unicode: "👍" },
+        user: { name: "users/other" },
+      },
+    ]);
+
+    if (!googlechatMessageActions.handleAction) {
+      throw new Error("Expected googlechatMessageActions.handleAction to be defined");
+    }
+    const result = await googlechatMessageActions.handleAction({
+      action: "react",
+      params: {
+        messageId: "spaces/AAA/messages/msg-1",
+        emoji: "👍",
+        remove: true,
+      },
+      cfg: {},
+      accountId: "default",
+    } as never);
+
+    expect(deleteGoogleChatReaction).toHaveBeenCalledTimes(2);
+    expect(deleteGoogleChatReaction).toHaveBeenNthCalledWith(1, {
+      account: expect.anything(),
+      reactionName: "reactions/1",
+    });
+    expect(deleteGoogleChatReaction).toHaveBeenNthCalledWith(2, {
+      account: expect.anything(),
+      reactionName: "reactions/2",
+    });
+    expect(result).toMatchObject({
+      details: {
+        ok: true,
+        removed: 2,
+      },
+    });
+  });
+});