Add Fireflies AI connector

integrations/fireflies-conversations/README.md

@@ -0,0 +1,78 @@
+# Fireflies Conversations Integration
+
+This integration allows GitBook to ingest meeting transcripts from Fireflies to provide AI-suggested improvements to your documentation.
+
+## Features
+
+- **Bulk Transcript Import**: When first installed, the integration fetches recent transcripts from Fireflies (last 30 days)
+- **Real-time Webhook Ingestion**: Automatically ingests transcripts when transcription completes via webhooks
+- **Automatic Conversion**: Converts Fireflies transcripts into GitBook conversations format for analysis
+
+## Setup
+
+1. Install the integration in your GitBook organization
+2. Enter your Fireflies API key in the integration settings
+3. The integration will automatically start ingesting transcripts from the last 30 days
+
+## Webhook Setup (Optional)
+
+To enable real-time transcript ingestion when transcription completes:
+
+1. **Configure Webhook Secret**:
+   - In the GitBook integration settings, enter your Fireflies webhook secret
+   - You can find or generate this in your Fireflies dashboard: Settings → Developer Settings
+   - The webhook secret is used to verify that webhook requests are authentic
+
+2. **Configure Webhook URL in Fireflies**:
+   - Visit [Fireflies.ai dashboard settings](https://app.fireflies.ai/settings)
+   - Navigate to the Developer settings tab
+   - Enter your webhook URL: `https://[your-integration-endpoint]/webhook`
+   - The webhook URL can be found in your GitBook integration settings
+   - Save the webhook URL
+
+3. **Test the Webhook**:
+   - Upload an audio file through the Fireflies dashboard at [app.fireflies.ai/upload](https://app.fireflies.ai/upload)
+   - Once transcription completes, the webhook should trigger and the transcript will be automatically ingested into GitBook
+
+**Note**: Webhooks are only fired for meetings that you own (the `organizer_email`). For team-wide webhooks, you need the Enterprise tier with Super Admin role.
+
+## Getting Your Fireflies API Key
+
+1. Log in to your Fireflies account
+2. Navigate to Settings → Integrations → API
+3. Generate or copy your API key
+4. Paste the API key into the GitBook integration configuration
+
+## Development
+
+To develop and test this integration, you'll need a Fireflies API key:
+
+### 1. Get a Fireflies API Key
+
+1. Go to [Fireflies](https://fireflies.ai/) and log in to your account
+2. Navigate to Settings → Integrations → API
+3. Generate an API key if you don't have one
+
+### 2. Testing
+
+The integration uses the Fireflies GraphQL API to fetch transcripts. You can test the integration by:
+
+1. Setting up the integration with your API key
+2. Verifying that transcripts are fetched and converted to GitBook conversations
+3. Checking that the conversation parts are properly formatted with speaker information
+
+### 3. Webhook Testing
+
+To test webhook functionality:
+
+1. Set up the integration with your API key and webhook secret
+2. Configure the webhook URL in your Fireflies dashboard
+3. Upload an audio file or wait for a meeting to be transcribed
+4. Verify that the transcript is automatically ingested when transcription completes
+
+### 4. API Documentation
+
+For more information about the Fireflies APIs, see:
+- [Fireflies GraphQL API Documentation](https://docs.fireflies.ai/graphql-api/query/transcripts)
+- [Fireflies Webhooks Documentation](https://docs.fireflies.ai/graphql-api/webhooks)
+

integrations/fireflies-conversations/gitbook-manifest.yaml

@@ -0,0 +1,37 @@
+name: fireflies-conversations
+title: Fireflies Connector
+icon: ./assets/logo.png
+description: Automatically sync Fireflies transcripts to docs updates in GitBook.
+visibility: public
+script: ./src/index.ts
+previewImages:
+    - ./assets/hubspot-preview.png
+summary: |
+    # Overview
+
+    Connecting Fireflies to GitBook turns every meeting transcript into documentation intelligence. The integration ingests transcript data, spots recurring issues, and surfaces where your docs need to be clearer, more accurate, or more complete.
+
+    ## How it works
+
+    GitBook Agent analyzes incoming transcripts, identifies patterns, and highlights gaps in your documentation. When it finds issues, it opens proactive change requests with suggested edits, drafted improvements, and the context behind each recommendation. You can also @mention the AI agent or chat with it directly to speed up reviews and polish updates.
+
+    ## Configure
+
+    1. Add your Fireflies API key  
+       Install the GitBook app in your GitBook account, then open its settings and enter your Fireflies API key. This allows GitBook to pull transcripts and their conversation history while automatically stripping sensitive data.
+
+    2. Let the GitBook Agent learn  
+       GitBook analyzes each transcript to detect FAQs, outdated content, unclear explanations, missing troubleshooting steps, and opportunities to improve clarity.
+
+    3. Watch it open proactive change requests  
+       As patterns emerge, GitBook creates change requests with proposed edits, context from meeting transcripts, and a working draft written by the AI agent.
+
+    4. Refine with the AI agent  
+       Inside any change request, @mention the agent or open its chat panel to request rewrites, clarifications, or additions. You stay in control while the agent accelerates updates.
+scopes:
+    - conversations:ingest
+organization: gitbook
+configurations:
+    account:
+        componentId: config
+target: organization

integrations/fireflies-conversations/package.json

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

integrations/fireflies-conversations/src/client.ts

@@ -0,0 +1,71 @@
+import { ExposableError, Logger } from '@gitbook/runtime';
+import { FirefliesRuntimeContext } from './types';
+
+const logger = Logger('fireflies-conversations:client');
+
+/**
+ * Get the API key for Fireflies API calls.
+ */
+export function getFirefliesApiKey(context: FirefliesRuntimeContext): string {
+    const { installation } = context.environment;
+
+    if (!installation) {
+        throw new ExposableError('Installation not found');
+    }
+
+    const { api_key } = installation.configuration;
+    if (!api_key) {
+        throw new ExposableError(
+            'Fireflies API key not found. Please configure the API key in the integration settings.',
+        );
+    }
+
+    return api_key;
+}
+
+/**
+ * Make a GraphQL request to the Fireflies API.
+ */
+export async function firefliesGraphQLRequest<T = unknown>(
+    context: FirefliesRuntimeContext,
+    query: string,
+    variables?: Record<string, unknown>,
+): Promise<T> {
+    const apiKey = getFirefliesApiKey(context);
+
+    const response = await fetch('https://api.fireflies.ai/graphql', {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            query,
+            variables,
+        }),
+    });
+
+    if (!response.ok) {
+        const errorText = await response.text();
+        logger.error('Fireflies API request failed', {
+            status: response.status,
+            statusText: response.statusText,
+            error: errorText,
+        });
+        throw new Error(`Fireflies API request failed: ${response.status} ${response.statusText}`);
+    }
+
+    const result = (await response.json()) as T;
+
+    // Check for GraphQL errors
+    if (result && typeof result === 'object' && 'errors' in result) {
+        const errors = (result as { errors?: Array<{ message: string }> }).errors;
+        if (errors && errors.length > 0) {
+            const errorMessage = errors.map((e) => e.message).join(', ');
+            logger.error('Fireflies GraphQL errors', { errors });
+            throw new Error(`Fireflies GraphQL error: ${errorMessage}`);
+        }
+    }
+
+    return result;
+}

integrations/fireflies-conversations/src/config.tsx

@@ -0,0 +1,132 @@
+import { createComponent, InstallationConfigurationProps } from '@gitbook/runtime';
+import { FirefliesRuntimeContext, FirefliesRuntimeEnvironment } from './types';
+
+type FirefliesConfigState = {
+    api_key: string;
+    webhook_secret: string;
+};
+
+type FirefliesConfigAction = { action: 'save.config' };
+
+/**
+ * Configuration component for the Fireflies integration.
+ */
+export const configComponent = createComponent<
+    InstallationConfigurationProps<FirefliesRuntimeEnvironment>,
+    FirefliesConfigState,
+    FirefliesConfigAction,
+    FirefliesRuntimeContext
+>({
+    componentId: 'config',
+    initialState: (props) => {
+        const installation = props.installation;
+        return {
+            api_key: installation.configuration?.api_key || '',
+            webhook_secret: installation.configuration?.webhook_secret || '',
+        };
+    },
+    action: async (element, action, context) => {
+        switch (action.action) {
+            case 'save.config':
+                const { api, environment } = context;
+                const { installation } = environment;
+
+                if (!installation) {
+                    return { type: 'complete' };
+                }
+
+                const configurationBody = {
+                    ...installation.configuration,
+                    api_key: element.state.api_key,
+                    webhook_secret: element.state.webhook_secret,
+                };
+
+                await api.integrations.updateIntegrationInstallation(
+                    environment.integration.name,
+                    installation.id,
+                    {
+                        configuration: {
+                            ...configurationBody,
+                        },
+                    },
+                );
+
+                return { type: 'complete' };
+        }
+    },
+    render: async (element, context) => {
+        const { installation } = context.environment;
+        if (!installation) {
+            return null;
+        }
+
+        const hasApiKey = !!element.props.installation.configuration?.api_key;
+        const hasWebhookSecret = !!element.props.installation.configuration?.webhook_secret;
+
+        return (
+            <configuration>
+                <input
+                    label="Fireflies API Key"
+                    hint={
+                        'Enter your Fireflies API key. You can find this in your Fireflies account settings.'
+                    }
+                    element={
+                        <textinput state="api_key" placeholder="Enter your Fireflies API key" />
+                    }
+                />
+
+                <input
+                    label="Webhook Secret"
+                    hint={
+                        'Enter your Fireflies webhook secret for verifying webhook requests. You can find or generate this in Settings → Developer Settings in your Fireflies dashboard.'
+                    }
+                    element={
+                        <textinput state="webhook_secret" placeholder="Enter your webhook secret" />
+                    }
+                />
+
+                <input
+                    label="Webhook URL"
+                    hint={
+                        <text>
+                            Add this URL to the <text style="bold">Webhooks</text> section in your{' '}
+                            <text style="bold">Developer Settings</text> in your Fireflies dashboard
+                            at{' '}
+                            <link
+                                target={{
+                                    url: 'https://app.fireflies.ai/settings',
+                                }}
+                            >
+                                app.fireflies.ai/settings
+                            </link>
+                            .
+                        </text>
+                    }
+                    element={<codeblock content={`${installation.urls.publicEndpoint}/webhook`} />}
+                />
+
+                <button
+                    label={hasApiKey ? 'Update Configuration' : 'Save Configuration'}
+                    onPress={{
+                        action: 'save.config',
+                    }}
+                />
+
+                {hasApiKey ? (
+                    <hint>
+                        <text>
+                            The integration is configured and transcripts are being ingested.
+                            {hasWebhookSecret
+                                ? ' Webhook support is enabled for real-time transcript ingestion.'
+                                : ' To enable real-time webhook ingestion, add your webhook secret and configure the webhook URL in your Fireflies dashboard.'}
+                        </text>
+                    </hint>
+                ) : (
+                    <hint>
+                        <text>Please enter your Fireflies API key to enable the integration.</text>
+                    </hint>
+                )}
+            </configuration>
+        );
+    },
+});