Allow passing a custom user-agent to the API client and use one per i…

…ntegration (#364)

* Allow passing an user-agent to the API client

* Use a custom user-agent for integrations

* Change name

* Lint

* Pass userAgent everywhere

.changeset/curvy-bobcats-explain.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/runtime': minor
+'@gitbook/api': minor
+---
+
+Allow passing a `userAgent` to the API client (`@gitbook/api`) and set a default user-agent for all integrations

integrations/github-entities/src/utils.ts

@@ -43,6 +43,7 @@ export async function authenticateAsIntegrationInstallation(
     return {
         ...context,
         api: new GitBookAPI({
+            userAgent: context.api.userAgent,
             endpoint: context.environment.apiEndpoint,
             authToken: token,
         }),
@@ -55,6 +56,7 @@ export async function authenticateAsIntegration(
     return {
         ...context,
         api: new GitBookAPI({
+            userAgent: context.api.userAgent,
             endpoint: context.environment.apiEndpoint,
             authToken: context.environment.apiTokens.integration,
         }),

integrations/github/src/tasks.ts

@@ -77,6 +77,7 @@ export async function handleImportDispatchForSpaces(
                 const installationContext: GithubRuntimeContext = {
                     ...context,
                     api: new GitBookAPI({
+                        userAgent: context.api.userAgent,
                         endpoint: context.environment.apiEndpoint,
                         authToken: installationAPIToken.token,
                     }),

integrations/gitlab/src/tasks.ts

@@ -77,6 +77,7 @@ export async function handleImportDispatchForSpaces(
                 const installationContext: GitLabRuntimeContext = {
                     ...context,
                     api: new GitBookAPI({
+                        userAgent: context.api.userAgent,
                         endpoint: context.environment.apiEndpoint,
                         authToken: installationAPIToken.token,
                     }),

packages/api/build.sh

@@ -36,4 +36,4 @@ esbuild ./src/index.ts --bundle --platform=node --format=esm --outfile=./dist/in
 
 # Finally we build the TypeScript declaration files
 echo "Generating public types from code..."
-tsc --project tsconfig.json --declaration --allowJs --emitDeclarationOnly --outDir ./dist/
+tsc --project tsconfig.json --declaration --allowJs --emitDeclarationOnly --outDir ./dist/ --rootDir ./src

packages/api/src/index.ts

@@ -1,3 +1,6 @@
+// @ts-ignore - Ignore the error "'rootDir' is expected to contain all source files" because
+// we need to control root to avoid ./dist/src and only have ./dist
+import { name, version } from '../package.json';
 import { Api } from './client';
 import { GitBookAPIError } from './GitBookAPIError';
 
@@ -27,6 +30,11 @@ export class GitBookAPI extends Api<{
      */
     public readonly authToken: string | undefined;
 
+    /**
+     * User agent used by the API client.
+     */
+    public readonly userAgent: string;
+
     constructor(
         options: {
             /**
@@ -35,13 +43,23 @@ export class GitBookAPI extends Api<{
              */
             endpoint?: string;
 
+            /**
+             * User agent to use.
+             * It'll default to the package name and version.
+             */
+            userAgent?: string;
+
             /**
              * Authentication token to use.
              */
             authToken?: string;
         } = {}
     ) {
-        const { endpoint = GITBOOK_DEFAULT_ENDPOINT, authToken } = options;
+        const {
+            endpoint = GITBOOK_DEFAULT_ENDPOINT,
+            authToken,
+            userAgent = `${name}/${version}`,
+        } = options;
 
         super({
             baseUrl: `${endpoint}/v1`,
@@ -50,6 +68,7 @@ export class GitBookAPI extends Api<{
                     return {
                         headers: {
                             Authorization: `Bearer ${securityData.authToken}`,
+                            'User-Agent': userAgent,
                         },
                     };
                 }
@@ -88,6 +107,7 @@ export class GitBookAPI extends Api<{
         });
 
         this.endpoint = endpoint;
+        this.userAgent = userAgent;
         this.authToken = authToken;
         this.setSecurityData({ authToken });
     }
@@ -107,6 +127,7 @@ export class GitBookAPI extends Api<{
 
         return new GitBookAPI({
             endpoint: this.endpoint,
+            userAgent: this.userAgent,
             authToken: installationToken.token,
         });
     }

packages/api/tsconfig.json

@@ -1,12 +1,16 @@
 {
     "extends": "@gitbook/tsconfig/base.json",
-    "include": ["src/**/*"],
+    "include": [
+        "./src/**/*"
+    ],
     "rootDir": "./src",
     "compilerOptions": {
         "baseUrl": "./src",
         // This is not strictly true, as the API is being run in a CloudFlare worker (so not
         // the DOM). However, swagger-typescript-api generated types that depend on things in
         // the DOM lib like FormData and Response.
-        "lib": ["DOM"]
+        "lib": [
+            "DOM"
+        ]
     }
-}
+}

packages/cli/src/remote.ts

@@ -1,7 +1,10 @@
 import { GitBookAPI } from '@gitbook/api';
 
+import { name, version } from '../package.json';
 import { getConfigValue, setConfigValue } from './config';
 
+const userAgent = `${name}/${version}`;
+
 /**
  * Get an authenticated API client.
  */
@@ -15,6 +18,7 @@ export async function getAPIClient(requireAuth: boolean = true): Promise<GitBook
     }
 
     return new GitBookAPI({
+        userAgent,
         endpoint: getConfigValue('endpoint'),
         authToken,
     });
@@ -27,6 +31,7 @@ export async function authenticate(endpoint: string, authToken: string): Promise
     console.log(`Authenticating with ${endpoint}...`);
 
     const api = new GitBookAPI({
+        userAgent,
         endpoint,
         authToken,
     });