@chat-adapter/gchat 4.13.1 → 4.13.3

package/README.md

@@ -1,6 +1,9 @@
 # @chat-adapter/gchat
 
-Google Chat adapter for the [chat](https://github.com/vercel-labs/chat) SDK.
+[![npm version](https://img.shields.io/npm/v/@chat-adapter/gchat)](https://www.npmjs.com/package/@chat-adapter/gchat)
+[![npm downloads](https://img.shields.io/npm/dm/@chat-adapter/gchat)](https://www.npmjs.com/package/@chat-adapter/gchat)
+
+Google Chat adapter for [Chat SDK](https://chat-sdk.dev/docs). Supports service account authentication with optional Pub/Sub for receiving all messages.
 
 ## Installation
 
@@ -14,7 +17,7 @@ npm install chat @chat-adapter/gchat
 import { Chat } from "chat";
 import { createGoogleChatAdapter } from "@chat-adapter/gchat";
 
-const chat = new Chat({
+const bot = new Chat({
   userName: "mybot",
   adapters: {
     gchat: createGoogleChatAdapter({
@@ -23,222 +26,14 @@ const chat = new Chat({
   },
 });
 
-// Handle @mentions
-chat.onNewMention(async (thread, message) => {
+bot.onNewMention(async (thread, message) => {
   await thread.post("Hello from Google Chat!");
 });
 ```
 
-## Configuration
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `credentials` | Yes* | Service account credentials JSON |
-| `useADC` | No | Use Application Default Credentials instead |
-| `pubsubTopic` | No | Pub/Sub topic for Workspace Events |
-| `impersonateUser` | No | User email for domain-wide delegation |
-
-*Either `credentials` or `useADC: true` is required.
-
-## Environment Variables
-
-```bash
-GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}
-
-# 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
-```
-
-## Google Chat Setup
-
-### 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
-
-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)
-
-### 3. Create a Service Account
-
-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**
-
-### 4. Create Service Account Key
-
-> **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
-
-- Message posting and editing
-- Thread subscriptions
-- Reaction events (via Workspace Events)
-- File attachments
-- Rich cards (Google Chat Cards)
-- Action callbacks (card buttons)
-- Direct messages
-- Space management
-
-## Limitations
-
-- **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
+## Documentation
 
-### 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`)
+Full setup instructions, configuration reference, and features at [chat-sdk.dev/docs/adapters/gchat](https://chat-sdk.dev/docs/adapters/gchat).
 
 ## License
 

package/dist/index.d.ts

@@ -6,10 +6,10 @@ import { google } from 'googleapis';
  */
 /** Google Chat-specific thread ID data */
 interface GoogleChatThreadId {
-    spaceName: string;
-    threadName?: string;
     /** Whether this is a DM space */
     isDM?: boolean;
+    spaceName: string;
+    threadName?: string;
 }
 
 /**
@@ -20,30 +20,26 @@ interface GoogleChatThreadId {
  */
 
 interface GoogleChatCard {
-    cardId?: string;
     card: {
         header?: GoogleChatCardHeader;
         sections: GoogleChatCardSection[];
     };
+    cardId?: string;
 }
 interface GoogleChatCardHeader {
-    title: string;
-    subtitle?: string;
-    imageUrl?: string;
     imageType?: "CIRCLE" | "SQUARE";
+    imageUrl?: string;
+    subtitle?: string;
+    title: string;
 }
 interface GoogleChatCardSection {
+    collapsible?: boolean;
     header?: string;
     widgets: GoogleChatWidget[];
-    collapsible?: boolean;
 }
 interface GoogleChatWidget {
-    textParagraph?: {
-        text: string;
-    };
-    image?: {
-        imageUrl: string;
-        altText?: string;
+    buttonList?: {
+        buttons: (GoogleChatButton | GoogleChatLinkButton)[];
     };
     decoratedText?: {
         topLabel?: string;
@@ -53,13 +49,21 @@ interface GoogleChatWidget {
             knownIcon?: string;
         };
     };
-    buttonList?: {
-        buttons: (GoogleChatButton | GoogleChatLinkButton)[];
-    };
     divider?: Record<string, never>;
+    image?: {
+        imageUrl: string;
+        altText?: string;
+    };
+    textParagraph?: {
+        text: string;
+    };
 }
 interface GoogleChatButton {
-    text: string;
+    color?: {
+        red: number;
+        green: number;
+        blue: number;
+    };
     onClick: {
         action: {
             function: string;
@@ -69,24 +73,20 @@ interface GoogleChatButton {
             }>;
         };
     };
+    text: string;
+}
+interface GoogleChatLinkButton {
     color?: {
         red: number;
         green: number;
         blue: number;
     };
-}
-interface GoogleChatLinkButton {
-    text: string;
     onClick: {
         openLink: {
             url: string;
         };
     };
-    color?: {
-        red: number;
-        green: number;
-        blue: number;
-    };
+    text: string;
 }
 /**
  * Options for card conversion.
@@ -152,19 +152,19 @@ declare class GoogleChatFormatConverter extends BaseFormatConverter {
 
 /** 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;
+    /** The space name (e.g., "spaces/AAAA...") */
+    spaceName: 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;
+    /** The subscription resource name */
+    name: string;
 }
 /** Pub/Sub push message wrapper (what Google sends to your endpoint) */
 interface PubSubPushMessage {
@@ -179,6 +179,10 @@ interface PubSubPushMessage {
 }
 /** Google Chat reaction data */
 interface GoogleChatReaction {
+    /** The emoji */
+    emoji?: {
+        unicode?: string;
+    };
     /** Reaction resource name */
     name: string;
     /** The user who added/removed the reaction */
@@ -187,30 +191,26 @@ interface GoogleChatReaction {
         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;
+    /** Event type (e.g., "google.workspace.chat.message.v1.created") */
+    eventType: string;
+    /** Present for message.created events */
+    message?: GoogleChatMessage;
+    /** Present for reaction.created/deleted events */
+    reaction?: GoogleChatReaction;
     /** Space info */
     space?: {
         name: string;
         type: string;
     };
-    /** Present for message.created events */
-    message?: GoogleChatMessage;
-    /** Present for reaction.created/deleted events */
-    reaction?: GoogleChatReaction;
+    /** The subscription that triggered this event */
+    subscription: string;
+    /** The resource being watched (e.g., "//chat.googleapis.com/spaces/AAAA") */
+    targetResource: string;
 }
 /** Service account credentials for authentication */
 interface ServiceAccountCredentials$1 {
@@ -297,38 +297,40 @@ 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;
     /**
-     * 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"
+     * HTTP endpoint URL for button click actions.
+     * Required for HTTP endpoint apps - button clicks will be routed to this URL.
+     * Should be the full URL of your webhook endpoint (e.g., "https://your-app.vercel.app/api/webhooks/gchat")
      */
-    pubsubTopic?: string;
+    endpointUrl?: 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;
+    /** Logger instance for error reporting */
+    logger: Logger;
     /**
-     * HTTP endpoint URL for button click actions.
-     * Required for HTTP endpoint apps - button clicks will be routed to this URL.
-     * Should be the full URL of your webhook endpoint (e.g., "https://your-app.vercel.app/api/webhooks/gchat")
+     * 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"
      */
-    endpointUrl?: string;
+    pubsubTopic?: string;
+    /** Override bot username (optional) */
+    userName?: string;
 }
 /** Config using service account credentials (JSON key file) */
 interface GoogleChatAdapterServiceAccountConfig extends GoogleChatAdapterBaseConfig {
+    auth?: never;
     /** Service account credentials JSON */
     credentials: ServiceAccountCredentials;
-    auth?: never;
     useApplicationDefaultCredentials?: never;
 }
 /** Config using Application Default Credentials (ADC) or Workload Identity Federation */
 interface GoogleChatAdapterADCConfig extends GoogleChatAdapterBaseConfig {
+    auth?: never;
+    credentials?: never;
     /**
      * Use Application Default Credentials.
      * Works with:
@@ -338,8 +340,6 @@ interface GoogleChatAdapterADCConfig extends GoogleChatAdapterBaseConfig {
      * - gcloud auth application-default login (local development)
      */
     useApplicationDefaultCredentials: true;
-    credentials?: never;
-    auth?: never;
 }
 /** Config using a custom auth client */
 interface GoogleChatAdapterCustomAuthConfig extends GoogleChatAdapterBaseConfig {
@@ -352,25 +352,6 @@ type GoogleChatAdapterConfig = GoogleChatAdapterServiceAccountConfig | GoogleCha
 
 /** 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;
@@ -384,45 +365,55 @@ interface GoogleChatMessage {
             type: string;
         };
     }>;
+    argumentText?: string;
     attachment?: Array<{
         name: string;
         contentName: string;
         contentType: string;
         downloadUri?: string;
     }>;
+    createTime: string;
+    formattedText?: string;
+    name: string;
+    sender: {
+        name: string;
+        displayName: string;
+        type: string;
+        email?: string;
+    };
+    space?: {
+        name: string;
+        type: string;
+        displayName?: string;
+    };
+    text: string;
+    thread?: {
+        name: string;
+    };
 }
 /** Google Chat space structure */
 interface GoogleChatSpace {
-    name: string;
-    type: string;
     displayName?: string;
+    name: string;
+    /** Whether this is a single-user DM with the bot */
+    singleUserBotDm?: boolean;
     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;
+    type: string;
 }
 /** Google Chat user structure */
 interface GoogleChatUser {
-    name: string;
     displayName: string;
-    type: string;
     email?: string;
+    name: string;
+    type: 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;
@@ -445,30 +436,39 @@ interface GoogleChatEvent {
             user: GoogleChatUser;
         };
     };
+    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>;
+    };
 }
 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 readonly chatApi;
     private chat;
     private state;
-    private logger;
-    private formatConverter;
-    private pubsubTopic?;
-    private credentials?;
-    private useADC;
+    private readonly logger;
+    private readonly formatConverter;
+    private readonly pubsubTopic?;
+    private readonly credentials?;
+    private readonly useADC;
     /** Custom auth client (e.g., Vercel OIDC) */
-    private customAuth?;
+    private readonly customAuth?;
     /** Auth client for making authenticated requests */
-    private authClient;
+    private readonly authClient;
     /** User email to impersonate for Workspace Events API (domain-wide delegation) */
-    private impersonateUser?;
+    private readonly impersonateUser?;
     /** In-progress subscription creations to prevent duplicate requests */
-    private pendingSubscriptions;
+    private readonly pendingSubscriptions;
     /** Chat API client with impersonation for user-context operations (DMs, etc.) */
-    private impersonatedChatApi?;
+    private readonly impersonatedChatApi?;
     /** HTTP endpoint URL for button click actions */
     private endpointUrl?;
     /** User info cache for display name lookups - initialized later in initialize() */