@chat-adapter/gchat 4.0.0

package/dist/index.d.ts

@@ -0,0 +1,567 @@
+import { CardElement, BaseFormatConverter, Root, Adapter, ChatInstance, WebhookOptions, PostableMessage, RawMessage, EmojiValue, FetchOptions, Message, ThreadInfo, FormattedContent } from 'chat';
+import { google } from 'googleapis';
+
+/**
+ * Google Chat Card converter for cross-platform cards.
+ *
+ * Converts CardElement to Google Chat Card v2 format.
+ * @see https://developers.google.com/chat/api/reference/rest/v1/cards
+ */
+
+interface GoogleChatCard {
+    cardId?: string;
+    card: {
+        header?: GoogleChatCardHeader;
+        sections: GoogleChatCardSection[];
+    };
+}
+interface GoogleChatCardHeader {
+    title: string;
+    subtitle?: string;
+    imageUrl?: string;
+    imageType?: "CIRCLE" | "SQUARE";
+}
+interface GoogleChatCardSection {
+    header?: string;
+    widgets: GoogleChatWidget[];
+    collapsible?: boolean;
+}
+interface GoogleChatWidget {
+    textParagraph?: {
+        text: string;
+    };
+    image?: {
+        imageUrl: string;
+        altText?: string;
+    };
+    decoratedText?: {
+        topLabel?: string;
+        text: string;
+        bottomLabel?: string;
+        startIcon?: {
+            knownIcon?: string;
+        };
+    };
+    buttonList?: {
+        buttons: GoogleChatButton[];
+    };
+    divider?: Record<string, never>;
+}
+interface GoogleChatButton {
+    text: string;
+    onClick: {
+        action: {
+            function: string;
+            parameters: Array<{
+                key: string;
+                value: string;
+            }>;
+        };
+    };
+    color?: {
+        red: number;
+        green: number;
+        blue: number;
+    };
+}
+/**
+ * Convert a CardElement to Google Chat Card v2 format.
+ */
+declare function cardToGoogleCard(card: CardElement, cardId?: string): GoogleChatCard;
+/**
+ * Generate fallback text from a card element.
+ * Used when cards aren't supported.
+ */
+declare function cardToFallbackText(card: CardElement): string;
+
+/**
+ * Google Chat-specific format conversion using AST-based parsing.
+ *
+ * Google Chat supports a subset of text formatting:
+ * - Bold: *text*
+ * - Italic: _text_
+ * - Strikethrough: ~text~
+ * - Monospace: `text`
+ * - Code blocks: ```text```
+ * - Links are auto-detected
+ *
+ * Very similar to Slack's mrkdwn format.
+ */
+
+declare class GoogleChatFormatConverter extends BaseFormatConverter {
+    /**
+     * Render an AST to Google Chat format.
+     */
+    fromAst(ast: Root): string;
+    /**
+     * Parse Google Chat message into an AST.
+     */
+    toAst(gchatText: string): Root;
+    private nodeToGChat;
+}
+
+/**
+ * Google Workspace Events API integration for receiving all messages in a space.
+ *
+ * By default, Google Chat only sends webhooks for @mentions. To receive ALL messages
+ * in a space, you need to create a Workspace Events subscription that publishes to
+ * a Pub/Sub topic, which then pushes to your webhook endpoint.
+ *
+ * Setup flow:
+ * 1. Create a Pub/Sub topic in your GCP project
+ * 2. Create a Pub/Sub push subscription pointing to your /api/webhooks/gchat/pubsub endpoint
+ * 3. Call createSpaceSubscription() to subscribe to message events for a space
+ * 4. Handle Pub/Sub messages in your webhook with handlePubSubMessage()
+ */
+
+/** Options for creating a space subscription */
+interface CreateSpaceSubscriptionOptions {
+    /** The space name (e.g., "spaces/AAAA...") */
+    spaceName: string;
+    /** The Pub/Sub topic to receive events (e.g., "projects/my-project/topics/my-topic") */
+    pubsubTopic: string;
+    /** Optional TTL for the subscription in seconds (default: 1 day, max: 1 day for Chat) */
+    ttlSeconds?: number;
+}
+/** Result of creating a space subscription */
+interface SpaceSubscriptionResult {
+    /** The subscription resource name */
+    name: string;
+    /** When the subscription expires (ISO 8601) */
+    expireTime: string;
+}
+/** Pub/Sub push message wrapper (what Google sends to your endpoint) */
+interface PubSubPushMessage {
+    message: {
+        /** Base64 encoded event data */
+        data: string;
+        messageId: string;
+        publishTime: string;
+        attributes?: Record<string, string>;
+    };
+    subscription: string;
+}
+/** Google Chat reaction data */
+interface GoogleChatReaction {
+    /** Reaction resource name */
+    name: string;
+    /** The user who added/removed the reaction */
+    user?: {
+        name: string;
+        displayName?: string;
+        type?: string;
+    };
+    /** The emoji */
+    emoji?: {
+        unicode?: string;
+    };
+}
+/** Decoded Workspace Events notification payload */
+interface WorkspaceEventNotification {
+    /** The subscription that triggered this event */
+    subscription: string;
+    /** The resource being watched (e.g., "//chat.googleapis.com/spaces/AAAA") */
+    targetResource: string;
+    /** Event type (e.g., "google.workspace.chat.message.v1.created") */
+    eventType: string;
+    /** When the event occurred */
+    eventTime: string;
+    /** Space info */
+    space?: {
+        name: string;
+        type: string;
+    };
+    /** Present for message.created events */
+    message?: GoogleChatMessage;
+    /** Present for reaction.created/deleted events */
+    reaction?: GoogleChatReaction;
+}
+/** Service account credentials for authentication */
+interface ServiceAccountCredentials$1 {
+    client_email: string;
+    private_key: string;
+    project_id?: string;
+}
+/** Auth options - service account, ADC, or custom auth client */
+type WorkspaceEventsAuthOptions = {
+    credentials: ServiceAccountCredentials$1;
+    impersonateUser?: string;
+} | {
+    useApplicationDefaultCredentials: true;
+    impersonateUser?: string;
+} | {
+    auth: Parameters<typeof google.workspaceevents>[0]["auth"];
+};
+/**
+ * Create a Workspace Events subscription to receive all messages in a Chat space.
+ *
+ * Prerequisites:
+ * - Enable the "Google Workspace Events API" in your GCP project
+ * - Create a Pub/Sub topic and grant the Chat service account publish permissions
+ * - The calling user/service account needs permission to access the space
+ *
+ * @example
+ * ```typescript
+ * const result = await createSpaceSubscription({
+ *   spaceName: "spaces/AAAAxxxxxx",
+ *   pubsubTopic: "projects/my-project/topics/chat-events",
+ * }, {
+ *   credentials: {
+ *     client_email: "...",
+ *     private_key: "...",
+ *   }
+ * });
+ * ```
+ */
+declare function createSpaceSubscription(options: CreateSpaceSubscriptionOptions, auth: WorkspaceEventsAuthOptions): Promise<SpaceSubscriptionResult>;
+/**
+ * List active subscriptions for a target resource.
+ */
+declare function listSpaceSubscriptions(spaceName: string, auth: WorkspaceEventsAuthOptions): Promise<Array<{
+    name: string;
+    expireTime: string;
+    eventTypes: string[];
+}>>;
+/**
+ * Delete a Workspace Events subscription.
+ */
+declare function deleteSpaceSubscription(subscriptionName: string, auth: WorkspaceEventsAuthOptions): Promise<void>;
+/**
+ * Decode a Pub/Sub push message into a Workspace Event notification.
+ *
+ * The message uses CloudEvents format where event metadata is in attributes
+ * (ce-type, ce-source, ce-subject, ce-time) and the payload is base64 encoded.
+ *
+ * @example
+ * ```typescript
+ * // In your /api/webhooks/gchat/pubsub route:
+ * const body = await request.json();
+ * const event = decodePubSubMessage(body);
+ *
+ * if (event.eventType === "google.workspace.chat.message.v1.created") {
+ *   // Handle new message
+ *   console.log("New message:", event.message?.text);
+ * }
+ * ```
+ */
+declare function decodePubSubMessage(pushMessage: PubSubPushMessage): WorkspaceEventNotification;
+/**
+ * Verify a Pub/Sub push message is authentic.
+ * In production, you should verify the JWT token in the Authorization header.
+ *
+ * @see https://cloud.google.com/pubsub/docs/authenticate-push-subscriptions
+ */
+declare function verifyPubSubRequest(request: Request, _expectedAudience?: string): boolean;
+
+/** Service account credentials for JWT auth */
+interface ServiceAccountCredentials {
+    client_email: string;
+    private_key: string;
+    project_id?: string;
+}
+/** Base config options shared by all auth methods */
+interface GoogleChatAdapterBaseConfig {
+    /** Override bot username (optional) */
+    userName?: string;
+    /**
+     * Pub/Sub topic for receiving all messages via Workspace Events.
+     * When set, the adapter will automatically create subscriptions when added to a space.
+     * Format: "projects/my-project/topics/my-topic"
+     */
+    pubsubTopic?: string;
+    /**
+     * User email to impersonate for Workspace Events API calls.
+     * Required when using domain-wide delegation.
+     * This user must have access to the Chat spaces you want to subscribe to.
+     */
+    impersonateUser?: string;
+}
+/** Config using service account credentials (JSON key file) */
+interface GoogleChatAdapterServiceAccountConfig extends GoogleChatAdapterBaseConfig {
+    /** Service account credentials JSON */
+    credentials: ServiceAccountCredentials;
+    auth?: never;
+    useApplicationDefaultCredentials?: never;
+}
+/** Config using Application Default Credentials (ADC) or Workload Identity Federation */
+interface GoogleChatAdapterADCConfig extends GoogleChatAdapterBaseConfig {
+    /**
+     * Use Application Default Credentials.
+     * Works with:
+     * - GOOGLE_APPLICATION_CREDENTIALS env var pointing to a JSON key file
+     * - Workload Identity Federation (external_account JSON)
+     * - GCE/Cloud Run/Cloud Functions default service account
+     * - gcloud auth application-default login (local development)
+     */
+    useApplicationDefaultCredentials: true;
+    credentials?: never;
+    auth?: never;
+}
+/** Config using a custom auth client */
+interface GoogleChatAdapterCustomAuthConfig extends GoogleChatAdapterBaseConfig {
+    /** Custom auth client (JWT, OAuth2, GoogleAuth, etc.) */
+    auth: Parameters<typeof google.chat>[0]["auth"];
+    credentials?: never;
+    useApplicationDefaultCredentials?: never;
+}
+type GoogleChatAdapterConfig = GoogleChatAdapterServiceAccountConfig | GoogleChatAdapterADCConfig | GoogleChatAdapterCustomAuthConfig;
+/** Google Chat-specific thread ID data */
+interface GoogleChatThreadId {
+    spaceName: string;
+    threadName?: string;
+    /** Whether this is a DM space */
+    isDM?: boolean;
+}
+/** Google Chat message structure */
+interface GoogleChatMessage {
+    name: string;
+    sender: {
+        name: string;
+        displayName: string;
+        type: string;
+        email?: string;
+    };
+    text: string;
+    argumentText?: string;
+    formattedText?: string;
+    thread?: {
+        name: string;
+    };
+    space?: {
+        name: string;
+        type: string;
+        displayName?: string;
+    };
+    createTime: string;
+    annotations?: Array<{
+        type: string;
+        startIndex?: number;
+        length?: number;
+        userMention?: {
+            user: {
+                name: string;
+                displayName?: string;
+                type: string;
+            };
+            type: string;
+        };
+    }>;
+    attachment?: Array<{
+        name: string;
+        contentName: string;
+        contentType: string;
+        downloadUri?: string;
+    }>;
+}
+/** Google Chat space structure */
+interface GoogleChatSpace {
+    name: string;
+    type: string;
+    displayName?: string;
+    spaceThreadingState?: string;
+    /** Space type in newer API format: "SPACE", "GROUP_CHAT", "DIRECT_MESSAGE" */
+    spaceType?: string;
+    /** Whether this is a single-user DM with the bot */
+    singleUserBotDm?: boolean;
+}
+/** Google Chat user structure */
+interface GoogleChatUser {
+    name: string;
+    displayName: string;
+    type: string;
+    email?: string;
+}
+/**
+ * Google Workspace Add-ons event format.
+ * This is the format used when configuring the app via Google Cloud Console.
+ */
+interface GoogleChatEvent {
+    commonEventObject?: {
+        userLocale?: string;
+        hostApp?: string;
+        platform?: string;
+        /** The function name invoked (for card clicks) */
+        invokedFunction?: string;
+        /** Parameters passed to the function */
+        parameters?: Record<string, string>;
+    };
+    chat?: {
+        user?: GoogleChatUser;
+        eventTime?: string;
+        messagePayload?: {
+            space: GoogleChatSpace;
+            message: GoogleChatMessage;
+        };
+        /** Present when the bot is added to a space */
+        addedToSpacePayload?: {
+            space: GoogleChatSpace;
+        };
+        /** Present when the bot is removed from a space */
+        removedFromSpacePayload?: {
+            space: GoogleChatSpace;
+        };
+        /** Present when a card button is clicked */
+        buttonClickedPayload?: {
+            space: GoogleChatSpace;
+            message: GoogleChatMessage;
+            user: GoogleChatUser;
+        };
+    };
+}
+declare class GoogleChatAdapter implements Adapter<GoogleChatThreadId, unknown> {
+    readonly name = "gchat";
+    readonly userName: string;
+    /** Bot's user ID (e.g., "users/123...") - learned from annotations */
+    botUserId?: string;
+    private chatApi;
+    private chat;
+    private state;
+    private logger;
+    private formatConverter;
+    private pubsubTopic?;
+    private credentials?;
+    private useADC;
+    /** Custom auth client (e.g., Vercel OIDC) */
+    private customAuth?;
+    /** Auth client for making authenticated requests */
+    private authClient;
+    /** User email to impersonate for Workspace Events API (domain-wide delegation) */
+    private impersonateUser?;
+    /** In-progress subscription creations to prevent duplicate requests */
+    private pendingSubscriptions;
+    /** Chat API client with impersonation for user-context operations (DMs, etc.) */
+    private impersonatedChatApi?;
+    constructor(config: GoogleChatAdapterConfig);
+    initialize(chat: ChatInstance): Promise<void>;
+    /**
+     * Called when a thread is subscribed to.
+     * Ensures the space has a Workspace Events subscription so we receive all messages.
+     */
+    onThreadSubscribe(threadId: string): Promise<void>;
+    /**
+     * Ensure a Workspace Events subscription exists for a space.
+     * Creates one if it doesn't exist or is about to expire.
+     */
+    private ensureSpaceSubscription;
+    /**
+     * Create a Workspace Events subscription and cache the result.
+     */
+    private createSpaceSubscriptionWithCache;
+    /**
+     * Check if a subscription already exists for this space.
+     */
+    private findExistingSubscription;
+    /**
+     * Get auth options for Workspace Events API calls.
+     */
+    private getAuthOptions;
+    handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    /**
+     * Handle Pub/Sub push messages from Workspace Events subscriptions.
+     * These contain all messages in a space, not just @mentions.
+     */
+    private handlePubSubMessage;
+    /**
+     * Handle message events received via Pub/Sub (Workspace Events).
+     */
+    private handlePubSubMessageEvent;
+    /**
+     * Handle reaction events received via Pub/Sub (Workspace Events).
+     * Fetches the message to get thread context for proper reply threading.
+     */
+    private handlePubSubReactionEvent;
+    /**
+     * Parse a Pub/Sub message into the standard Message format.
+     * Resolves user display names from cache since Pub/Sub messages don't include them.
+     */
+    private parsePubSubMessage;
+    /**
+     * Handle bot being added to a space - create Workspace Events subscription.
+     */
+    private handleAddedToSpace;
+    /**
+     * Handle card button clicks.
+     * Google Chat sends action data via commonEventObject.invokedFunction and parameters.
+     */
+    private handleCardClick;
+    /**
+     * Handle direct webhook message events (Add-ons format).
+     */
+    private handleMessageEvent;
+    private parseGoogleChatMessage;
+    postMessage(threadId: string, message: PostableMessage): Promise<RawMessage<unknown>>;
+    /**
+     * Extract card element from a PostableMessage if present.
+     */
+    private extractCard;
+    /**
+     * Extract files from a PostableMessage if present.
+     */
+    private extractFiles;
+    /**
+     * Create an Attachment object from a Google Chat attachment.
+     */
+    private createAttachment;
+    editMessage(threadId: string, messageId: string, message: PostableMessage): Promise<RawMessage<unknown>>;
+    deleteMessage(_threadId: string, messageId: string): Promise<void>;
+    addReaction(_threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    removeReaction(_threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    startTyping(_threadId: string): Promise<void>;
+    /**
+     * Open a direct message conversation with a user.
+     * Returns a thread ID that can be used to post messages.
+     *
+     * For Google Chat, this first tries to find an existing DM space with the user.
+     * If no DM exists, it creates one using spaces.setup.
+     *
+     * @param userId - The user's resource name (e.g., "users/123456")
+     */
+    openDM(userId: string): Promise<string>;
+    fetchMessages(threadId: string, options?: FetchOptions): Promise<Message<unknown>[]>;
+    fetchThread(threadId: string): Promise<ThreadInfo>;
+    encodeThreadId(platformData: GoogleChatThreadId): string;
+    /**
+     * Check if a thread is a direct message conversation.
+     * Checks for the :dm marker in the thread ID which is set when
+     * processing DM messages or opening DMs.
+     */
+    isDM(threadId: string): boolean;
+    decodeThreadId(threadId: string): GoogleChatThreadId;
+    parseMessage(raw: unknown): Message<unknown>;
+    renderFormatted(content: FormattedContent): string;
+    /**
+     * Normalize bot mentions in message text.
+     * Google Chat uses the bot's display name (e.g., "@Chat SDK Demo") but the
+     * Chat SDK expects "@{userName}" format. This method replaces bot mentions
+     * with the adapter's userName so mention detection works properly.
+     * Also learns the bot's user ID from annotations for isMe detection.
+     */
+    private normalizeBotMentions;
+    /**
+     * Check if a message is from this bot.
+     *
+     * Bot user ID is learned dynamically from message annotations when the bot
+     * is @mentioned. Until we learn the ID, we cannot reliably determine isMe.
+     *
+     * This is safer than the previous approach of assuming all BOT messages are
+     * from self, which would incorrectly filter messages from other bots in
+     * multi-bot spaces (especially via Pub/Sub).
+     */
+    private isMessageFromSelf;
+    /**
+     * Cache user info for later lookup (e.g., when processing Pub/Sub messages).
+     */
+    private cacheUserInfo;
+    /**
+     * Get cached user info.
+     */
+    private getCachedUserInfo;
+    /**
+     * Resolve user display name, using cache if available.
+     */
+    private resolveUserDisplayName;
+    private handleGoogleChatError;
+}
+declare function createGoogleChatAdapter(config: GoogleChatAdapterConfig): GoogleChatAdapter;
+
+export { type CreateSpaceSubscriptionOptions, GoogleChatAdapter, type GoogleChatAdapterADCConfig, type GoogleChatAdapterBaseConfig, type GoogleChatAdapterConfig, type GoogleChatAdapterCustomAuthConfig, type GoogleChatAdapterServiceAccountConfig, type GoogleChatEvent, GoogleChatFormatConverter, type GoogleChatMessage, type GoogleChatSpace, type GoogleChatThreadId, type GoogleChatUser, type PubSubPushMessage, type ServiceAccountCredentials, type SpaceSubscriptionResult, type WorkspaceEventNotification, type WorkspaceEventsAuthOptions, cardToFallbackText, cardToGoogleCard, createGoogleChatAdapter, createSpaceSubscription, decodePubSubMessage, deleteSpaceSubscription, listSpaceSubscriptions, verifyPubSubRequest };