paperclip-plugin-google-chat 0.1.0

package/dist/google-chat.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Google Chat outbound client + pure formatting helpers.
+ *
+ * Outbound delivery uses Google Chat **incoming webhooks**: an HTTPS POST of a
+ * message resource to a per-space URL. The simplest body is `{ text }`; richer
+ * messages use Cards v2 (`cardsV2`). We keep the HTTP call behind a small
+ * `HttpFetch` seam so the formatters and routing can be unit-tested without the
+ * Paperclip SDK runtime.
+ *
+ * Docs: https://developers.google.com/workspace/chat/quickstart/webhooks
+ */
+/** Minimal fetch shape compatible with `ctx.http.fetch` and the global `fetch`. */
+export type HttpFetch = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+export type RouteKey = "default" | "approvals" | "errors" | "digest";
+export interface GoogleChatMessage {
+    text?: string;
+    cardsV2?: unknown[];
+    /** Thread key for grouping replies in a space. */
+    threadKey?: string;
+}
+/**
+ * POST a message to a Google Chat space via its incoming-webhook URL.
+ * Returns the parsed result; throws on transport failure so callers can log.
+ */
+export declare function postToWebhook(fetchImpl: HttpFetch, webhookUrl: string, message: GoogleChatMessage): Promise<{
+    ok: boolean;
+    status: number;
+    body: string;
+}>;
+/** Append query params without clobbering existing ones. Exported for tests. */
+export declare function appendQuery(url: string, params: Record<string, string>): string;
+/** Google Chat supports a limited Markdown: *bold*, _italic_, `code`. */
+export declare function bold(s: string): string;
+export declare function link(text: string, url: string): string;
+export interface IssueLike {
+    id?: string;
+    title?: string;
+    status?: string;
+    url?: string;
+}
+export declare function formatIssueCreated(issue: IssueLike): string;
+export declare function formatIssueCompleted(issue: IssueLike): string;
+export declare function formatApprovalRequested(issue: IssueLike): string;
+export declare function formatAgentRunFailed(agentName: string, errorMsg: string): string;
+export declare function formatBriefing(title: string | undefined, body: string): string;

package/dist/google-chat.js

@@ -0,0 +1,72 @@
+/**
+ * Google Chat outbound client + pure formatting helpers.
+ *
+ * Outbound delivery uses Google Chat **incoming webhooks**: an HTTPS POST of a
+ * message resource to a per-space URL. The simplest body is `{ text }`; richer
+ * messages use Cards v2 (`cardsV2`). We keep the HTTP call behind a small
+ * `HttpFetch` seam so the formatters and routing can be unit-tested without the
+ * Paperclip SDK runtime.
+ *
+ * Docs: https://developers.google.com/workspace/chat/quickstart/webhooks
+ */
+/**
+ * POST a message to a Google Chat space via its incoming-webhook URL.
+ * Returns the parsed result; throws on transport failure so callers can log.
+ */
+export async function postToWebhook(fetchImpl, webhookUrl, message) {
+    if (!webhookUrl)
+        throw new Error("postToWebhook: empty webhook URL");
+    const body = {};
+    if (message.text)
+        body.text = message.text;
+    if (message.cardsV2)
+        body.cardsV2 = message.cardsV2;
+    const url = message.threadKey
+        ? appendQuery(webhookUrl, { threadKey: message.threadKey, messageReplyOption: "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD" })
+        : webhookUrl;
+    const res = await fetchImpl(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json; charset=UTF-8" },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    return { ok: res.ok, status: res.status, body: text };
+}
+/** Append query params without clobbering existing ones. Exported for tests. */
+export function appendQuery(url, params) {
+    const sep = url.includes("?") ? "&" : "?";
+    const qs = Object.entries(params)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .join("&");
+    return `${url}${sep}${qs}`;
+}
+// --- Pure formatters (unit-tested) -----------------------------------------
+/** Google Chat supports a limited Markdown: *bold*, _italic_, `code`. */
+export function bold(s) {
+    return `*${s}*`;
+}
+export function link(text, url) {
+    // Google Chat renders <url|text> as a hyperlink.
+    return `<${url}|${text}>`;
+}
+export function formatIssueCreated(issue) {
+    const title = issue.title ?? "(untitled)";
+    const head = issue.url ? link(`🆕 ${title}`, issue.url) : `🆕 ${title}`;
+    return `${head}\nNew issue created${issue.status ? ` · ${issue.status}` : ""}`;
+}
+export function formatIssueCompleted(issue) {
+    const title = issue.title ?? "(untitled)";
+    const head = issue.url ? link(`✅ ${title}`, issue.url) : `✅ ${title}`;
+    return `${head}\nIssue completed`;
+}
+export function formatApprovalRequested(issue) {
+    const title = issue.title ?? "(untitled)";
+    const head = issue.url ? link(`⏳ ${title}`, issue.url) : `⏳ ${title}`;
+    return `${bold("Approval needed")}\n${head}`;
+}
+export function formatAgentRunFailed(agentName, errorMsg) {
+    return `${bold("⚠️ Agent run failed")}\n${agentName}: ${errorMsg}`;
+}
+export function formatBriefing(title, body) {
+    return title ? `${bold(title)}\n${body}` : body;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export { default as worker } from "./worker.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export { default as worker } from "./worker.js";

package/dist/manifest.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Paperclip plugin manifest (apiVersion 1). Declares the capability grants the
+ * host enforces and the surfaces the worker registers. Keep capabilities minimal —
+ * the host blocks any API call whose capability is not declared here.
+ */
+declare const manifest: {
+    readonly id: "google-chat";
+    readonly apiVersion: 1;
+    readonly version: "0.1.0";
+    readonly displayName: "Google Chat";
+    readonly description: "Bidirectional Google Chat bridge: posts issue/agent/approval notifications to spaces and drives Paperclip from Chat slash commands.";
+    readonly author: "Measured Assets";
+    readonly categories: readonly ["connector", "automation"];
+    readonly capabilities: readonly ["companies.read", "projects.read", "issues.read", "issues.create", "issues.update", "issue.comments.read", "issue.comments.create", "agents.read", "agents.invoke", "agent.sessions.create", "agent.sessions.send", "goals.read", "events.subscribe", "jobs.schedule", "http.outbound", "secrets.read-ref", "webhooks.receive", "agent.tools.register", "activity.log.write", "plugin.state.read", "plugin.state.write", "instance.settings.register"];
+    readonly entrypoints: {
+        readonly worker: "./dist/worker.js";
+    };
+    readonly instanceConfigSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly defaultWebhookUrlRef: {
+                readonly type: "string";
+                readonly title: "Default space webhook (secret ref)";
+                readonly description: "Secret reference to a Google Chat incoming-webhook URL. Create the secret in Paperclip, paste the returned UUID here.";
+            };
+            readonly approvalsWebhookUrlRef: {
+                readonly type: "string";
+                readonly title: "Approvals space webhook (secret ref)";
+            };
+            readonly errorsWebhookUrlRef: {
+                readonly type: "string";
+                readonly title: "Errors space webhook (secret ref)";
+            };
+            readonly digestWebhookUrlRef: {
+                readonly type: "string";
+                readonly title: "Digest space webhook (secret ref)";
+            };
+            readonly serviceAccountKeyRef: {
+                readonly type: "string";
+                readonly title: "Service-account key (secret ref, optional)";
+                readonly description: "Only required for the Chat REST API (threaded replies). Webhook-only mode leaves this blank.";
+            };
+            readonly notifyOnIssueCreated: {
+                readonly type: "boolean";
+                readonly title: "Notify on issue created";
+                readonly default: false;
+            };
+            readonly notifyOnIssueCompleted: {
+                readonly type: "boolean";
+                readonly title: "Notify on issue completed";
+                readonly default: true;
+            };
+            readonly notifyOnApprovalRequested: {
+                readonly type: "boolean";
+                readonly title: "Notify on approval requested";
+                readonly default: true;
+            };
+            readonly notifyOnAgentRunFailed: {
+                readonly type: "boolean";
+                readonly title: "Notify on agent run failed";
+                readonly default: true;
+            };
+            readonly useCards: {
+                readonly type: "boolean";
+                readonly title: "Use Cards v2 formatting";
+                readonly default: false;
+            };
+            readonly enableCommands: {
+                readonly type: "boolean";
+                readonly title: "Enable inbound slash commands";
+                readonly default: true;
+            };
+            readonly verificationTokenRef: {
+                readonly type: "string";
+                readonly title: "Verification token (secret ref)";
+            };
+            readonly allowedSpaceIds: {
+                readonly type: "array";
+                readonly title: "Allowed space IDs";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly allowedUserEmails: {
+                readonly type: "array";
+                readonly title: "Allowed user emails";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly digestMode: {
+                readonly type: "boolean";
+                readonly title: "Enable daily digest";
+                readonly default: false;
+            };
+            readonly dailyDigestTime: {
+                readonly type: "string";
+                readonly title: "Daily digest time (HH:MM)";
+                readonly default: "08:00";
+            };
+        };
+    };
+    readonly webhooks: readonly [{
+        readonly endpointKey: "chat-events";
+        readonly displayName: "Google Chat events";
+        readonly description: "Configure your Google Chat app's HTTP endpoint to POST events here (MESSAGE, ADDED_TO_SPACE, CARD_CLICKED).";
+    }];
+    readonly jobs: readonly [{
+        readonly key: "daily-digest";
+        readonly displayName: "Daily digest";
+        readonly description: "Posts a once-daily summary to the digest space when digestMode is enabled.";
+        readonly schedule: "0 * * * *";
+    }];
+    readonly tools: readonly [{
+        readonly name: "post_to_google_chat";
+        readonly displayName: "Post to Google Chat";
+        readonly description: "Post a plain-text or Markdown message to a configured Google Chat space.";
+        readonly parametersSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly text: {
+                    readonly type: "string";
+                    readonly description: "Message body (Google Chat Markdown supported).";
+                };
+                readonly space: {
+                    readonly type: "string";
+                    readonly description: "Optional routing key: default | approvals | errors | digest. Defaults to 'default'.";
+                };
+            };
+            readonly required: readonly ["text"];
+        };
+    }, {
+        readonly name: "escalate_to_human";
+        readonly displayName: "Escalate to human (Google Chat)";
+        readonly description: "Post an escalation message to the approvals space and ask a human to respond.";
+        readonly parametersSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly message: {
+                    readonly type: "string";
+                };
+                readonly issueId: {
+                    readonly type: "string";
+                    readonly description: "Optional Paperclip issue id for context.";
+                };
+            };
+            readonly required: readonly ["message"];
+        };
+    }, {
+        readonly name: "send_briefing";
+        readonly displayName: "Send briefing (Google Chat)";
+        readonly description: "Post a formatted briefing/report to the digest space (used by scheduled briefing routines).";
+        readonly parametersSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                };
+                readonly body: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["body"];
+        };
+    }];
+};
+export default manifest;

package/dist/manifest.js

@@ -0,0 +1,110 @@
+import { INSTANCE_CONFIG_SCHEMA } from "./config.js";
+import { JOB_KEYS, PLUGIN_ID, PLUGIN_VERSION, TOOL_NAMES, WEBHOOK_KEYS } from "./constants.js";
+/**
+ * Paperclip plugin manifest (apiVersion 1). Declares the capability grants the
+ * host enforces and the surfaces the worker registers. Keep capabilities minimal —
+ * the host blocks any API call whose capability is not declared here.
+ */
+const manifest = {
+    id: PLUGIN_ID,
+    apiVersion: 1,
+    version: PLUGIN_VERSION,
+    displayName: "Google Chat",
+    description: "Bidirectional Google Chat bridge: posts issue/agent/approval notifications to spaces and drives Paperclip from Chat slash commands.",
+    author: "Measured Assets",
+    categories: ["connector", "automation"],
+    capabilities: [
+        // read domain state for notifications + command responses
+        "companies.read",
+        "projects.read",
+        "issues.read",
+        "issues.create",
+        "issues.update",
+        "issue.comments.read",
+        "issue.comments.create",
+        "agents.read",
+        "agents.invoke",
+        "agent.sessions.create",
+        "agent.sessions.send",
+        "goals.read",
+        // outbound: event subscription + scheduled digest + HTTP to Google + secret refs
+        "events.subscribe",
+        "jobs.schedule",
+        "http.outbound",
+        "secrets.read-ref",
+        // inbound: receive Google Chat app events
+        "webhooks.receive",
+        // agents can proactively push to Chat
+        "agent.tools.register",
+        // misc
+        "activity.log.write",
+        "plugin.state.read",
+        "plugin.state.write",
+        "instance.settings.register",
+    ],
+    entrypoints: {
+        worker: "./dist/worker.js",
+    },
+    instanceConfigSchema: INSTANCE_CONFIG_SCHEMA,
+    webhooks: [
+        {
+            endpointKey: WEBHOOK_KEYS.chatEvents,
+            displayName: "Google Chat events",
+            description: "Configure your Google Chat app's HTTP endpoint to POST events here (MESSAGE, ADDED_TO_SPACE, CARD_CLICKED).",
+        },
+    ],
+    jobs: [
+        {
+            key: JOB_KEYS.dailyDigest,
+            displayName: "Daily digest",
+            description: "Posts a once-daily summary to the digest space when digestMode is enabled.",
+            // Hourly tick; the handler self-gates to the configured HH:MM.
+            schedule: "0 * * * *",
+        },
+    ],
+    tools: [
+        {
+            name: TOOL_NAMES.postMessage,
+            displayName: "Post to Google Chat",
+            description: "Post a plain-text or Markdown message to a configured Google Chat space.",
+            parametersSchema: {
+                type: "object",
+                properties: {
+                    text: { type: "string", description: "Message body (Google Chat Markdown supported)." },
+                    space: {
+                        type: "string",
+                        description: "Optional routing key: default | approvals | errors | digest. Defaults to 'default'.",
+                    },
+                },
+                required: ["text"],
+            },
+        },
+        {
+            name: TOOL_NAMES.escalateToHuman,
+            displayName: "Escalate to human (Google Chat)",
+            description: "Post an escalation message to the approvals space and ask a human to respond.",
+            parametersSchema: {
+                type: "object",
+                properties: {
+                    message: { type: "string" },
+                    issueId: { type: "string", description: "Optional Paperclip issue id for context." },
+                },
+                required: ["message"],
+            },
+        },
+        {
+            name: TOOL_NAMES.sendBriefing,
+            displayName: "Send briefing (Google Chat)",
+            description: "Post a formatted briefing/report to the digest space (used by scheduled briefing routines).",
+            parametersSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string" },
+                    body: { type: "string" },
+                },
+                required: ["body"],
+            },
+        },
+    ],
+};
+export default manifest;

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Agent-callable tools. Registered in the worker so agents can proactively push to
+ * Google Chat (e.g. a daily-briefing routine calling `send_briefing`, or an agent
+ * escalating to a human). Each handler returns a `ToolResult` ({ content | error }).
+ */
+import { type GoogleChatMessage, type RouteKey } from "./google-chat.js";
+/** Posts a message to a routed space; returns delivery status. */
+export type PostFn = (routeKey: RouteKey, message: GoogleChatMessage) => Promise<{
+    ok: boolean;
+    status: number;
+    body: string;
+}>;
+interface ToolResultLike {
+    content?: string;
+    data?: unknown;
+    error?: string;
+}
+interface ToolsHost {
+    tools: {
+        register(name: string, declaration: {
+            displayName: string;
+            description: string;
+            parametersSchema: unknown;
+        }, fn: (params: unknown, runCtx: unknown) => Promise<ToolResultLike>): void;
+    };
+}
+export declare function registerTools(ctx: ToolsHost, post: PostFn): void;
+export {};

package/dist/tools.js

@@ -0,0 +1,71 @@
+/**
+ * Agent-callable tools. Registered in the worker so agents can proactively push to
+ * Google Chat (e.g. a daily-briefing routine calling `send_briefing`, or an agent
+ * escalating to a human). Each handler returns a `ToolResult` ({ content | error }).
+ */
+import { TOOL_NAMES } from "./constants.js";
+import { formatBriefing } from "./google-chat.js";
+export function registerTools(ctx, post) {
+    ctx.tools.register(TOOL_NAMES.postMessage, {
+        displayName: "Post to Google Chat",
+        description: "Post a plain-text or Markdown message to a configured Google Chat space.",
+        parametersSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string" },
+                space: { type: "string", description: "default | approvals | errors | digest" },
+            },
+            required: ["text"],
+        },
+    }, async (params) => {
+        const p = (params ?? {});
+        if (!p.text)
+            return { error: "text is required" };
+        const route = normalizeRoute(p.space);
+        const res = await post(route, { text: p.text });
+        return res.ok
+            ? { content: `Posted to the ${route} space.` }
+            : { error: `Google Chat post failed (HTTP ${res.status}): ${res.body.slice(0, 200)}` };
+    });
+    ctx.tools.register(TOOL_NAMES.escalateToHuman, {
+        displayName: "Escalate to human (Google Chat)",
+        description: "Post an escalation to the approvals space and ask a human to respond.",
+        parametersSchema: {
+            type: "object",
+            properties: { message: { type: "string" }, issueId: { type: "string" } },
+            required: ["message"],
+        },
+    }, async (params) => {
+        const p = (params ?? {});
+        if (!p.message)
+            return { error: "message is required" };
+        const suffix = p.issueId ? `\n_issue: ${p.issueId}_` : "";
+        const res = await post("approvals", { text: `🙋 *Escalation*\n${p.message}${suffix}` });
+        return res.ok ? { content: "Escalation posted to the approvals space." } : { error: `Post failed (HTTP ${res.status}).` };
+    });
+    ctx.tools.register(TOOL_NAMES.sendBriefing, {
+        displayName: "Send briefing (Google Chat)",
+        description: "Post a formatted briefing/report to the digest space.",
+        parametersSchema: {
+            type: "object",
+            properties: { title: { type: "string" }, body: { type: "string" } },
+            required: ["body"],
+        },
+    }, async (params) => {
+        const p = (params ?? {});
+        if (!p.body)
+            return { error: "body is required" };
+        const res = await post("digest", { text: formatBriefing(p.title, p.body) });
+        return res.ok ? { content: "Briefing posted to the digest space." } : { error: `Post failed (HTTP ${res.status}).` };
+    });
+}
+function normalizeRoute(space) {
+    switch (space) {
+        case "approvals":
+        case "errors":
+        case "digest":
+            return space;
+        default:
+            return "default";
+    }
+}

package/dist/worker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Google Chat plugin worker — wires the SDK seams together:
+ *
+ *  - setup()      registers domain-event subscriptions, the daily-digest job, and
+ *                 the agent tools.
+ *  - onWebhook()  receives Google Chat app events and routes slash commands.
+ *  - outbound     resolves a per-route incoming-webhook URL from a secret ref and
+ *                 POSTs the message via `ctx.http.fetch`.
+ *
+ * The pure logic (formatting, parsing, routing) lives in sibling modules and is
+ * unit-tested; this file is the thin SDK-facing shell.
+ */
+declare const plugin: import("@paperclipai/plugin-sdk").PaperclipPlugin;
+export default plugin;