@mercury-fw/channel-google-chat 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @mercury-fw/channel-google-chat
 
+## 0.1.3
+
+### Patch Changes
+
+- 5e09c69: - README: a section on connecting a new app to a Chat app that already exists (finding the service account and the subscription, creating a key, `mfw google-chat set-key`).
+  - README: how to list and delete the keys the old instances left behind, before the service account reaches its limit of 10.
+  - README: `--project` on the `keys create` command of the setup.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -35,6 +35,7 @@ channels: [googleChatChannel],
   - [6. Configure the consent screen (Cloud Console)](#6-configure-the-consent-screen-cloud-console)
   - [7. Configure the Chat app (Cloud Console)](#7-configure-the-chat-app-cloud-console)
   - [8. Start and try it](#8-start-and-try-it)
+- [Connecting an app to an existing Chat app](#connecting-an-app-to-an-existing-chat-app)
 - [When the subscription disappears](#when-the-subscription-disappears)
 
 ## Setting up the Chat app
@@ -45,7 +46,7 @@ Everything goes through `gcloud` except two pages of Cloud Console (steps 6 and
 
 - a Google Workspace Business or Enterprise account: Chat apps don't exist for personal Gmail accounts;
 - `gcloud` logged in with that account (`gcloud auth login <you@company.com>`), allowed to create projects and link a billing account;
-- the app with its dependencies installed (`bun install`), for `bunx mfw` in step 5.
+- the app with its dependencies installed (`bun install`), for `mfw` in step 5.
 
 ### 1. Name things
 
@@ -100,7 +101,7 @@ gcloud pubsub subscriptions add-iam-policy-binding "$SUBSCRIPTION" \
   --project="$PROJECT_ID" \
   --member="serviceAccount:${SA_EMAIL}" \
   --role="roles/pubsub.subscriber"
-gcloud iam service-accounts keys create key.json --iam-account="$SA_EMAIL"
+gcloud iam service-accounts keys create key.json --iam-account="$SA_EMAIL" --project="$PROJECT_ID"
 ```
 
 A service account takes a few seconds to become visible to the rest of Google Cloud: if the binding fails saying the account doesn't exist, wait a moment and run it again.
@@ -108,7 +109,7 @@ A service account takes a few seconds to become visible to the rest of Google Cl
 Then, from the app's folder, write the key and the subscription into its `.env` with the app's own CLI, and delete the key file. The command replaces the lines `mfw create` left empty (or an older key), puts the private key on one line the way the channel reads it, and never prints it:
 
 ```bash
-bunx mfw google-chat set-key key.json --subscription "projects/${PROJECT_ID}/subscriptions/${SUBSCRIPTION}"
+mfw google-chat set-key key.json --subscription "projects/${PROJECT_ID}/subscriptions/${SUBSCRIPTION}"
 rm key.json
 ```
 
@@ -139,14 +140,50 @@ Click **Save**. The field names here come from Google's own Pub/Sub quickstart;
 
 ### 8. Start and try it
 
-Start the app (`bunx mfw start`) and check that the channel came up without errors:
+Start the app (`mfw start`) and check that the channel came up without errors:
 
 ```bash
-bunx mfw logs mercury
+mfw logs mercury
 ```
 
 `[channel] google-chat started` with no `pubsub stream error` after it means Mercury is pulling from the subscription. Then, in Google Chat, start a new chat and search the app's name (it shows up only for the people and groups in **Visibility**), or add it to a space; write to it and it answers.
 
+## Connecting an app to an existing Chat app
+
+When the Chat app is already set up and the Mercury instance behind it changes (the app scaffolded again, or moved to another machine), the new app only needs a key of the service account and the subscription's name in its `.env`. It replaces the old instance, it doesn't run next to it: stop the old one first, two instances on one subscription split the conversations between them.
+
+If you don't have the project's id at hand, `gcloud projects list` shows it; then the service account and the subscription:
+
+```bash
+PROJECT_ID=<the project's id>
+gcloud iam service-accounts list --project="$PROJECT_ID"
+gcloud pubsub subscriptions list --project="$PROJECT_ID" --format="value(name)"
+```
+
+```bash
+SA_EMAIL=<the EMAIL column of the service account Mercury runs as>
+SUBSCRIPTION=<the part after subscriptions/>
+```
+
+Then, from the new app's folder, create a key, write it into the `.env` with the subscription, and delete the key file:
+
+```bash
+gcloud iam service-accounts keys create key.json --iam-account="$SA_EMAIL" --project="$PROJECT_ID"
+mfw google-chat set-key key.json --subscription "projects/${PROJECT_ID}/subscriptions/${SUBSCRIPTION}"
+rm key.json
+```
+
+The old instance's key stays valid until you delete it, and a service account holds at most 10 keys, after which `keys create` fails. List them and delete the ones no instance uses anymore:
+
+```bash
+gcloud iam service-accounts keys list --iam-account="$SA_EMAIL" --project="$PROJECT_ID" --managed-by=user
+gcloud iam service-accounts keys delete <KEY_ID> --iam-account="$SA_EMAIL" --project="$PROJECT_ID"
+```
+
+The key the new app uses is the one with the latest `CREATED_AT`.
+
+Start it and check it as in [step 8](#8-start-and-try-it).
+
 ## When the subscription disappears
 
 A subscription created before `--expiration-period=never` was in step 4 still has the default policy, and Pub/Sub deletes it after 31 days without a pull. The channel then logs `NOT_FOUND` on the subscription, while the topic, the service account and the Chat app's configuration are all still there.
@@ -177,7 +214,7 @@ gcloud pubsub subscriptions add-iam-policy-binding "$SUBSCRIPTION" \
   --role="roles/pubsub.subscriber"
 ```
 
-Then restart the app (`bunx mfw restart`). The messages sent while the subscription was missing are lost, though: Pub/Sub keeps messages only for a subscription that exists.
+Then restart the app (`mfw restart`). The messages sent while the subscription was missing are lost, though: Pub/Sub keeps messages only for a subscription that exists.
 
 If the topic is gone too, redo steps 3 to 5 and, in step 7, paste the new topic in **Connection settings**.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-google-chat",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -34,9 +34,9 @@
     "@mercury-fw/channel-types": ">=0.24.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.28.1",
+    "@mercury-fw/channel-types": "0.29.2",
     "@mercury-fw/typescript-config": "*",
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"
   }
 }