Zendesk and Intercom integrations for Docs Agents (#836)

* Start

* Auth and configuration

* Implement auth

* Create or update webhook

* Start ingestion of tickets

* Dont push empty conversations

* Set url for conversations

* Handle webhooks

* Migrate to latest version of CF runtime

* Start intercom

* Cleanup

* Format

* Fix TS error

* Format

* Fix check command

* Improve check to use test env

* Fix check not running in env

* Publish as v2

* Fix webhook and team listing

* Fix request

* Format

* Add config for staging

* Update configs

* Install op

* Auth 1password

* Update descriptions

* Test it with credentials

* Try running signin

* Try again

* Fix env

Author: SamyPesse

.github/composite/setup-1password-op/action.yaml

@@ -0,0 +1,20 @@
+name: Setup 1Password CLI
+description: Install 1Password CLI
+inputs:
+    OP_SERVICE_ACCOUNT_TOKEN:
+        description: Service account token for 1Password
+        required: true
+runs:
+    using: 'composite'
+    steps:
+        - name: Install 1Password CLI
+          shell: bash
+          run: curl -sSfo op.zip
+              https://cache.agilebits.com/dist/1P/op2/pkg/v2.31.1/op_linux_amd64_v2.31.1.zip
+              && unzip -od /usr/local/bin/ op.zip
+              && rm op.zip
+        - name: Setup 1Password CLI
+          shell: bash
+          run: op user get --me
+          env:
+              OP_SERVICE_ACCOUNT_TOKEN: ${{ inputs.OP_SERVICE_ACCOUNT_TOKEN }}

.github/workflows/production.yaml

@@ -25,6 +25,10 @@ jobs:
               uses: oven-sh/setup-bun@v2
               with:
                   bun-version-file: 'package.json'
+            - name: Setup 1Password CLI
+              uses: ./.github/composite/setup-1password-op
+              with:
+                  OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
             - name: Install dependencies
               run: bun install --frozen-lockfile
 
@@ -42,6 +46,7 @@ jobs:
                   GITBOOK_TOKEN: ${{ secrets.GITBOOK_PROD_API_TOKEN }}
                   GITBOOK_ENDPOINT: https://api.gitbook.com
                   GITBOOK_ORGANIZATION: gitbook
+                  OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
                   # GitHub Files
                   UNFURL_GITHUB_CLIENT_ID: ${{ secrets.UNFURL_GITHUB_CLIENT_ID }}
                   UNFURL_GITHUB_CLIENT_SECRET: ${{ secrets.UNFURL_GITHUB_CLIENT_SECRET }}

.github/workflows/release.yaml

@@ -46,6 +46,10 @@ jobs:
               uses: oven-sh/setup-bun@v2
               with:
                   bun-version-file: 'package.json'
+            - name: Setup 1Password CLI
+              uses: ./.github/composite/setup-1password-op
+              with:
+                  OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
             - name: Install dependencies
               run: bun install --frozen-lockfile
             - name: Publish all integrations assets to staging
@@ -60,6 +64,7 @@ jobs:
                   GITBOOK_TOKEN: ${{ secrets.GITBOOK_STAGING_API_TOKEN }}
                   GITBOOK_ENDPOINT: https://api.gitbook-staging.com
                   GITBOOK_ORGANIZATION: gitbookio
+                  OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
                   # GitHub Files
                   UNFURL_GITHUB_CLIENT_ID: ${{ secrets.UNFURL_GITHUB_CLIENT_ID }}
                   UNFURL_GITHUB_CLIENT_SECRET: ${{ secrets.UNFURL_GITHUB_CLIENT_SECRET }}

.github/workflows/test.yaml

@@ -70,11 +70,16 @@ jobs:
               uses: oven-sh/setup-bun@v2
               with:
                   bun-version-file: 'package.json'
+            - name: Setup 1Password CLI
+              uses: ./.github/composite/setup-1password-op
+              with:
+                  OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
             - name: Install dependencies
               run: bun install --frozen-lockfile
             - name: Check
               run: bun run check
               env:
+                  OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
                   # GitHub Files
                   UNFURL_GITHUB_CLIENT_ID: ${{ secrets.UNFURL_GITHUB_CLIENT_ID }}
                   UNFURL_GITHUB_CLIENT_SECRET: ${{ secrets.UNFURL_GITHUB_CLIENT_SECRET }}

bun.lock

@@ -0,0 +1,16 @@
+# Intercom Conversations Integration
+
+This integration allows the users to ingest closed support conversations from Intercom into GitBook.
+
+## Setup Instructions for development
+
+1. Create an Intercom OAuth application at https://app.intercom.com/a/apps/_/developer-hub
+2. Set `https://<integration-domain>/v1/integrations/intercom-conversations/integration/oauth` as the redirect URL
+3. Get the client ID and secret
+   It is recommended to store them in 1Password
+4. Set `https://<integration-domain>/v1/integrations/intercom-conversations/integration/webhook` as the webhook URL
+   1. Go to https://app.intercom.com/a/apps/_/developer-hub/webhooks
+   2. Create a new webhook
+   3. Set the webhook URL to `https://<integration-domain>/v1/integrations/intercom-conversations/integration/webhook`
+   4. Select the "Conversation closed" event type
+   5. Save the webhook

integrations/intercom-conversations/README.md

@@ -0,0 +1,34 @@
+name: intercom-conversations
+title: Intercom Connector
+icon: ./assets/icon.png
+description: Ingest Intercom support conversations into GitBook for auto-improvements.
+visibility: public
+script: ./src/index.ts
+summary: |
+    # Overview
+
+    Automatically get AI-suggested change requests for your docs based on Intercom support conversations.
+scopes:
+    - conversations:ingest
+organization: gitbook
+configurations:
+    account:
+        componentId: config
+secrets:
+    CLIENT_ID: ${{ env.INTERCOM_CLIENT_ID }}
+    CLIENT_SECRET: ${{ env.INTERCOM_CLIENT_SECRET }}
+target: organization
+envs:
+    test:
+        secrets:
+            CLIENT_ID: ${{ "op://gitbook-integrations/intercomConversationsStaging/CLIENT_ID" }}
+            CLIENT_SECRET: ${{ "op://gitbook-integrations/intercomConversationsStaging/CLIENT_SECRET" }}
+    staging:
+        secrets:
+            CLIENT_ID: ${{ "op://gitbook-integrations/intercomConversationsStaging/CLIENT_ID" }}
+            CLIENT_SECRET: ${{ "op://gitbook-integrations/intercomConversationsStaging/CLIENT_SECRET" }}
+    dev-samy:
+        organization: 27dLEczo4lLcYIQhRuxg
+        secrets:
+            CLIENT_ID: ${{ "op://gitbook-integrations/IntercomDevSamyConversations/CLIENT_ID" }}
+            CLIENT_SECRET: ${{ "op://gitbook-integrations/IntercomDevSamyConversations/CLIENT_SECRET" }}

integrations/intercom-conversations/assets/icon.png

@@ -0,0 +1,20 @@
+{
+    "name": "@gitbook/integration-intercom-conversations",
+    "version": "0.0.1",
+    "private": true,
+    "dependencies": {
+        "@gitbook/runtime": "*",
+        "@gitbook/api": "*",
+        "p-map": "^7.0.3",
+        "intercom-client": "^6.3.0"
+    },
+    "devDependencies": {
+        "@gitbook/cli": "workspace:*",
+        "@gitbook/tsconfig": "workspace:*"
+    },
+    "scripts": {
+        "typecheck": "tsc --noEmit",
+        "check": "gitbook check",
+        "publish-integrations-staging": "gitbook publish ."
+    }
+}

integrations/intercom-conversations/gitbook-manifest.yaml

@@ -0,0 +1,41 @@
+import { IntercomClient } from 'intercom-client';
+import { IntercomRuntimeContext } from './types';
+import { ExposableError, getOAuthToken, OAuthConfig } from '@gitbook/runtime';
+
+/**
+ * Get the OAuth configuration for the Intercom integration.
+ */
+export function getIntercomOAuthConfig(context: IntercomRuntimeContext) {
+    const config: OAuthConfig = {
+        redirectURL: `${context.environment.integration.urls.publicEndpoint}/oauth`,
+        clientId: context.environment.secrets.CLIENT_ID,
+        clientSecret: context.environment.secrets.CLIENT_SECRET,
+        scopes: ['conversations.read'],
+        authorizeURL: () => 'https://app.intercom.com/oauth',
+        accessTokenURL: () => 'https://api.intercom.io/auth/eagle/token',
+    };
+
+    return config;
+}
+
+/**
+ * Initialize an Intercom API client for a given installation.
+ */
+export async function getIntercomClient(context: IntercomRuntimeContext) {
+    const { installation } = context.environment;
+
+    if (!installation) {
+        throw new Error('Installation not found');
+    }
+
+    const { oauth_credentials } = installation.configuration;
+    if (!oauth_credentials) {
+        throw new Error('Intercom OAuth credentials not found');
+    }
+
+    const token = await getOAuthToken(oauth_credentials, getIntercomOAuthConfig(context), context);
+
+    return new IntercomClient({
+        token,
+    });
+}