@phuetz/code-buddy 0.1.13 → 0.1.15

package/dist/channels/google-chat/index.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Google Chat Channel Adapter
+ *
+ * Google Chat integration via Google Workspace Chat API.
+ * Uses service account authentication for bot-to-space messaging.
+ *
+ * Requires:
+ * - A Google Cloud project with the Chat API enabled
+ * - A service account with Chat Bot scope
+ * - The service account JSON key file
+ *
+ * The adapter operates in two modes:
+ * 1. Webhook mode (push): Google Chat sends events to a configured endpoint
+ * 2. Pull mode: Polls for space activity via the REST API (limited, mainly for sending)
+ *
+ * Primary documentation: https://developers.google.com/workspace/chat/api/reference/rest
+ */
+import type { ChannelConfig, OutboundMessage, DeliveryResult } from '../index.js';
+import { BaseChannel } from '../index.js';
+/**
+ * Google Chat-specific configuration
+ */
+export interface GoogleChatConfig extends ChannelConfig {
+    type: 'google-chat';
+    /** Path to the service account JSON key file */
+    serviceAccountPath: string;
+    /** Default space ID (spaces/{spaceId}) to send messages to */
+    spaceId?: string;
+    /** Webhook URL that Google Chat sends events to (push mode) */
+    webhookUrl?: string;
+    /** Bearer token for verifying incoming webhooks */
+    verificationToken?: string;
+    /** Project number for push subscription (Pub/Sub) */
+    projectNumber?: string;
+}
+/**
+ * Google Chat space
+ */
+export interface GoogleChatSpace {
+    name: string;
+    type: 'ROOM' | 'DM' | 'TYPE_UNSPECIFIED';
+    displayName?: string;
+    singleUserBotDm?: boolean;
+    spaceThreadingState?: string;
+}
+/**
+ * Google Chat user
+ */
+export interface GoogleChatUser {
+    name: string;
+    displayName: string;
+    domainId?: string;
+    type: 'HUMAN' | 'BOT';
+    isAnonymous?: boolean;
+}
+/**
+ * Google Chat message
+ */
+export interface GoogleChatMessage {
+    name?: string;
+    sender?: GoogleChatUser;
+    createTime?: string;
+    text?: string;
+    formattedText?: string;
+    cards?: unknown[];
+    cardsV2?: unknown[];
+    annotations?: Array<{
+        type: string;
+        startIndex?: number;
+        length?: number;
+        userMention?: {
+            user: GoogleChatUser;
+            type: string;
+        };
+        slashCommand?: {
+            commandName: string;
+            commandId: string;
+        };
+    }>;
+    thread?: {
+        name: string;
+        threadKey?: string;
+    };
+    space?: GoogleChatSpace;
+    argumentText?: string;
+    attachment?: Array<{
+        name: string;
+        contentName: string;
+        contentType: string;
+        thumbnailUri?: string;
+        downloadUri?: string;
+        source?: string;
+        attachmentDataRef?: {
+            resourceName: string;
+        };
+    }>;
+    slashCommand?: {
+        commandId: string;
+    };
+    matchedUrl?: {
+        url: string;
+    };
+}
+/**
+ * Google Chat event (webhook payload)
+ */
+export interface GoogleChatEvent {
+    type: 'MESSAGE' | 'ADDED_TO_SPACE' | 'REMOVED_FROM_SPACE' | 'CARD_CLICKED';
+    eventTime: string;
+    token?: string;
+    message?: GoogleChatMessage;
+    user?: GoogleChatUser;
+    space?: GoogleChatSpace;
+    action?: {
+        actionMethodName: string;
+        parameters?: Array<{
+            key: string;
+            value: string;
+        }>;
+    };
+    configCompleteRedirectUrl?: string;
+    threadKey?: string;
+    common?: {
+        userLocale?: string;
+        hostApp?: string;
+        platform?: string;
+        timeZone?: {
+            id: string;
+            offset: number;
+        };
+    };
+}
+/**
+ * Google Chat channel using the Workspace Chat API
+ */
+export declare class GoogleChatChannel extends BaseChannel {
+    private serviceAccount;
+    private accessToken;
+    private tokenExpiry;
+    private spaceCache;
+    constructor(config: GoogleChatConfig);
+    private get gchatConfig();
+    /**
+     * Load the service account key from disk
+     */
+    private loadServiceAccount;
+    /**
+     * Create a signed JWT for the service account
+     */
+    private createJwt;
+    /**
+     * Exchange the signed JWT for a Google OAuth2 access token
+     */
+    private getAccessToken;
+    /**
+     * Make an authenticated request to the Google Chat API
+     */
+    private apiRequest;
+    /**
+     * Connect to Google Chat by validating the service account and
+     * verifying API access
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from Google Chat
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a message to a Google Chat space
+     */
+    send(message: OutboundMessage): Promise<DeliveryResult>;
+    /**
+     * Handle an incoming Google Chat webhook event.
+     * Call this from your HTTP server route handler.
+     *
+     * @param event - The parsed request body
+     * @param bearerToken - The Bearer token from the Authorization header (optional)
+     * @returns Response body to send back to Google Chat (can include a synchronous reply)
+     */
+    handleWebhook(event: GoogleChatEvent, bearerToken?: string): Promise<Record<string, unknown> | void>;
+    /**
+     * Handle MESSAGE event
+     */
+    private handleMessageEvent;
+    /**
+     * Handle CARD_CLICKED event (button press)
+     */
+    private handleCardClicked;
+    /**
+     * List spaces the bot has access to
+     */
+    listSpaces(): Promise<GoogleChatSpace[]>;
+    /**
+     * Get a specific space
+     */
+    getSpace(spaceName: string): Promise<GoogleChatSpace | null>;
+    /**
+     * Update a previously sent message
+     */
+    updateMessage(messageName: string, text: string): Promise<void>;
+    /**
+     * Delete a previously sent message
+     */
+    deleteMessage(messageName: string): Promise<void>;
+    /**
+     * Map MIME type to ContentType
+     */
+    private mimeToContentType;
+}
+export default GoogleChatChannel;