@chat-adapter/gchat 4.1.0 → 4.3.0

package/README.md

@@ -40,37 +40,155 @@ chat.onNewMention(async (thread, message) => {
 
 *Either `credentials` or `useADC: true` is required.
 
-## Setup
+## Environment Variables
 
-### 1. Create a Google Cloud Project
+```bash
+GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}
 
-1. Go to [Google Cloud Console](https://console.cloud.google.com)
-2. Create a new project or select existing
-3. Enable the **Google Chat API**
+# Optional: for receiving ALL messages, not just @mentions
+GOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project/topics/chat-events
+GOOGLE_CHAT_IMPERSONATE_USER=admin@yourdomain.com
+```
 
-### 2. Create a Service Account
+## Google Chat Setup
 
-1. Go to IAM & Admin → Service Accounts
-2. Create a new service account
-3. Download the JSON key file
-4. Set as `GOOGLE_CHAT_CREDENTIALS` environment variable
+### 1. Create a GCP Project
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Click the project dropdown → **New Project**
+3. Enter project name and click **Create**
+
+### 2. Enable Required APIs
 
-### 3. Configure Chat App
+1. Go to **APIs & Services** → **Library**
+2. Search and enable:
+   - **Google Chat API**
+   - **Google Workspace Events API** (for receiving all messages)
+   - **Cloud Pub/Sub API** (for receiving all messages)
 
-1. Go to [Google Chat API Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)
-2. Configure your app:
-   - App name and avatar
-   - HTTP endpoint URL for webhooks
-   - Enable interactive features
+### 3. Create a Service Account
 
-### 4. (Optional) Pub/Sub for Workspace Events
+1. Go to **IAM & Admin** → **Service Accounts**
+2. Click **Create Service Account**
+3. Enter name and description
+4. Click **Create and Continue**
+5. Skip the optional steps, click **Done**
 
-For reaction events, you need Workspace Events via Pub/Sub:
+### 4. Create Service Account Key
 
-1. Enable **Pub/Sub API** and **Workspace Events API**
-2. Create a Pub/Sub topic
-3. Set `pubsubTopic` in adapter options
-4. Configure subscription to your webhook endpoint
+> **Note**: If your organization has the `iam.disableServiceAccountKeyCreation` constraint enabled, you'll need to:
+> 1. Go to **IAM & Admin** → **Organization Policies**
+> 2. Find `iam.disableServiceAccountKeyCreation`
+> 3. Click **Manage Policy** → **Override parent's policy**
+> 4. Set to **Not enforced** (or add an exception for your project)
+
+1. Click on your service account
+2. Go to **Keys** tab
+3. Click **Add Key** → **Create new key**
+4. Select **JSON** and click **Create**
+5. Save the downloaded file
+6. Copy the entire JSON content → `GOOGLE_CHAT_CREDENTIALS` (as a single line)
+
+### 5. Configure Google Chat App
+
+1. Go to [console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)
+2. Click **Configuration**
+3. Fill in:
+   - **App name**: Your bot's display name
+   - **Avatar URL**: URL to your bot's avatar image
+   - **Description**: What your bot does
+   - **Interactive features**:
+     - Enable **Receive 1:1 messages**
+     - Enable **Join spaces and group conversations**
+   - **Connection settings**: Select **App URL**
+   - **App URL**: `https://your-domain.com/api/webhooks/gchat`
+   - **Visibility**: Choose who can discover and install your app
+4. Click **Save**
+
+**Important for button clicks**: The same App URL receives both message events and interactive events (card button clicks). Google Chat sends CARD_CLICKED events to this URL when users click buttons in cards.
+
+### 6. Add Bot to a Space
+
+1. Open Google Chat
+2. Create or open a Space
+3. Click the space name → **Manage apps & integrations** (or **Apps & integrations**)
+4. Click **Add apps**
+5. Search for your app name
+6. Click **Add**
+
+## (Optional) Pub/Sub for All Messages
+
+By default, Google Chat only sends webhooks for @mentions. To receive ALL messages in a space (for conversation context), you need to set up Workspace Events with Pub/Sub.
+
+### 1. Create Pub/Sub Topic
+
+1. Go to **Pub/Sub** → **Topics**
+2. Click **Create Topic**
+3. Enter topic ID (e.g., `chat-events`)
+4. Uncheck **Add a default subscription**
+5. Click **Create**
+6. Copy the full topic name → `GOOGLE_CHAT_PUBSUB_TOPIC`
+   - Format: `projects/your-project-id/topics/chat-events`
+
+### 2. Grant Chat Service Account Access
+
+> **Note**: If your organization has the `iam.allowedPolicyMemberDomains` constraint, you may need to temporarily relax it or use the console workaround below.
+
+1. Go to your Pub/Sub topic
+2. Click **Permissions** tab (or **Show Info Panel** → **Permissions**)
+3. Click **Add Principal**
+4. Enter: `chat-api-push@system.gserviceaccount.com`
+5. Select role: **Pub/Sub Publisher**
+6. Click **Save**
+
+**If you get a policy error**, try via Cloud Console:
+1. Go to **Pub/Sub** → **Topics**
+2. Check the box next to your topic
+3. Click **Permissions** in the info panel
+4. Click **Add Principal**
+5. Add `chat-api-push@system.gserviceaccount.com` with **Pub/Sub Publisher** role
+
+### 3. Create Push Subscription
+
+1. Go to **Pub/Sub** → **Subscriptions**
+2. Click **Create Subscription**
+3. Enter subscription ID (e.g., `chat-messages-push`)
+4. Select your topic
+5. **Delivery type**: Push
+6. **Endpoint URL**: `https://your-domain.com/api/webhooks/gchat`
+7. Click **Create**
+
+### 4. Enable Domain-Wide Delegation
+
+To create Workspace Events subscriptions and initiate DMs, you need domain-wide delegation:
+
+**Step 1: Enable delegation on the Service Account (GCP Console)**
+
+1. Go to [IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
+2. Click on your service account
+3. Go to **Details** tab
+4. Check **Enable Google Workspace Domain-wide Delegation**
+5. Click **Save**
+6. Go to **Advanced settings** (or click on the service account again)
+7. Copy the **Client ID** - this is a **numeric ID** (e.g., `123456789012345678901`), NOT the email address
+
+**Step 2: Authorize the Client ID (Google Admin Console)**
+
+1. Go to [Google Admin Console](https://admin.google.com)
+2. Go to **Security** → **Access and data control** → **API controls**
+3. Click **Manage Domain Wide Delegation**
+4. Click **Add new**
+5. Enter:
+   - **Client ID**: The numeric ID from Step 1 (e.g., `123456789012345678901`)
+   - **OAuth Scopes** (all on one line, comma-separated):
+     ```
+     https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.spaces.create
+     ```
+6. Click **Authorize**
+
+**Step 3: Set environment variable**
+
+Set `GOOGLE_CHAT_IMPERSONATE_USER` to an admin user email in your domain (e.g., `admin@yourdomain.com`). This user will be impersonated when creating DM spaces and Workspace Events subscriptions.
 
 ## Features
 
@@ -88,6 +206,40 @@ For reaction events, you need Workspace Events via Pub/Sub:
 - **Typing indicators**: Not supported by Google Chat API
 - **Adding reactions**: Requires domain-wide delegation (appears from impersonated user, not bot)
 
+## Troubleshooting
+
+### No webhook received
+- Verify the App URL is correct in Google Chat configuration
+- Check that the Chat API is enabled
+- Ensure the service account has the necessary permissions
+
+### Pub/Sub not working
+- Verify `chat-api-push@system.gserviceaccount.com` has Pub/Sub Publisher role
+- Check that the push subscription URL is correct
+- Verify domain-wide delegation is configured with correct scopes
+- Check `GOOGLE_CHAT_IMPERSONATE_USER` is a valid admin email
+
+### "Permission denied" for Workspace Events
+- Ensure domain-wide delegation is configured
+- Verify the OAuth scopes are exactly as specified
+- Check that the impersonated user has access to the spaces
+
+### "Insufficient Permission" for DMs (openDM)
+- DMs require domain-wide delegation with `chat.spaces` and `chat.spaces.create` scopes
+- Add these scopes to your domain-wide delegation configuration in Google Admin Console
+- Set `GOOGLE_CHAT_IMPERSONATE_USER` to an admin email in your domain
+- Scope changes can take up to 24 hours to propagate
+
+### "unauthorized_client" error
+- The Client ID is not registered in Google Admin Console
+- Or domain-wide delegation is not enabled on the service account
+
+### Button clicks (CARD_CLICKED) not received
+- Verify "Interactive features" is enabled in the Google Chat app configuration
+- Check that the App URL is correctly set and accessible
+- Button clicks go to the same webhook URL as messages
+- Ensure your button elements have valid `id` attributes (these become the `actionId`)
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,6 +1,17 @@
-import { CardElement, BaseFormatConverter, Root, Adapter, ChatInstance, WebhookOptions, AdapterPostableMessage, RawMessage, EmojiValue, FetchOptions, Message, ThreadInfo, FormattedContent } from 'chat';
+import { CardElement, BaseFormatConverter, Root, Logger, Adapter, ChatInstance, WebhookOptions, AdapterPostableMessage, RawMessage, EmojiValue, FetchOptions, FetchResult, ThreadInfo, Message, FormattedContent } from 'chat';
 import { google } from 'googleapis';
 
+/**
+ * Thread ID encoding/decoding utilities for Google Chat adapter.
+ */
+/** Google Chat-specific thread ID data */
+interface GoogleChatThreadId {
+    spaceName: string;
+    threadName?: string;
+    /** Whether this is a DM space */
+    isDM?: boolean;
+}
+
 /**
  * Google Chat Card converter for cross-platform cards.
  *
@@ -273,6 +284,8 @@ interface ServiceAccountCredentials {
 }
 /** Base config options shared by all auth methods */
 interface GoogleChatAdapterBaseConfig {
+    /** Logger instance for error reporting */
+    logger: Logger;
     /** Override bot username (optional) */
     userName?: string;
     /**
@@ -323,13 +336,7 @@ interface GoogleChatAdapterCustomAuthConfig extends GoogleChatAdapterBaseConfig
     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;
@@ -451,6 +458,8 @@ declare class GoogleChatAdapter implements Adapter<GoogleChatThreadId, unknown>
     private impersonatedChatApi?;
     /** HTTP endpoint URL for button click actions */
     private endpointUrl?;
+    /** User info cache for display name lookups - initialized later in initialize() */
+    private userInfoCache;
     constructor(config: GoogleChatAdapterConfig);
     initialize(chat: ChatInstance): Promise<void>;
     /**
@@ -511,14 +520,6 @@ declare class GoogleChatAdapter implements Adapter<GoogleChatThreadId, unknown>
     private handleMessageEvent;
     private parseGoogleChatMessage;
     postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<unknown>>;
-    /**
-     * Extract card element from a message if present.
-     */
-    private extractCard;
-    /**
-     * Extract files from a message if present.
-     */
-    private extractFiles;
     /**
      * Create an Attachment object from a Google Chat attachment.
      */
@@ -538,13 +539,34 @@ declare class GoogleChatAdapter implements Adapter<GoogleChatThreadId, unknown>
      * @param userId - The user's resource name (e.g., "users/123456")
      */
     openDM(userId: string): Promise<string>;
-    fetchMessages(threadId: string, options?: FetchOptions): Promise<Message<unknown>[]>;
+    fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<unknown>>;
+    /**
+     * Fetch messages in backward direction (most recent first).
+     * GChat API defaults to createTime ASC (oldest first), so we request DESC
+     * to get the most recent messages, then reverse for chronological order within page.
+     */
+    private fetchMessagesBackward;
+    /**
+     * Fetch messages in forward direction (oldest first).
+     *
+     * GChat API defaults to createTime ASC (oldest first), which is what we want.
+     * For forward pagination, we:
+     * 1. If no cursor: Fetch ALL messages (already in chronological order)
+     * 2. If cursor: Cursor is a message name, skip to after that message
+     *
+     * Note: This is less efficient than backward for large message histories,
+     * as it requires fetching all messages to find the cursor position.
+     */
+    private fetchMessagesForward;
+    /**
+     * Parse a message from the list API into the standard Message format.
+     * Resolves user display names and properly determines isMe.
+     */
+    private parseGChatListMessage;
     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;
@@ -569,18 +591,6 @@ declare class GoogleChatAdapter implements Adapter<GoogleChatThreadId, unknown>
      * 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;