add apiClient option (#84)

Author: hsubox76

.changeset/small-cheetahs-itch.md

@@ -0,0 +1,5 @@
+---
+"@google/generative-ai": minor
+---
+
+Add `apiClient` configuration option to `RequestOptions`.

.github/workflows/test.yml

@@ -24,7 +24,9 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: ['18.x', '20.x']
+        # lock version 20 for now as 20.12.0 makes global fetch unstubbable
+        # until we can rewrite tests to stub some other way
+        node-version: ['18.x', '20.11.1']
     steps:
     - uses: actions/checkout@v4
     - name: Use Node.js

docs/reference/generative-ai.requestoptions.apiclient.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [RequestOptions](./generative-ai.requestoptions.md) &gt; [apiClient](./generative-ai.requestoptions.apiclient.md)
+
+## RequestOptions.apiClient property
+
+Additional attribution information to include in the x-goog-api-client header. Used by wrapper SDKs.
+
+**Signature:**
+
+```typescript
+apiClient?: string;
+```

docs/reference/generative-ai.requestoptions.md

@@ -16,6 +16,7 @@ export interface RequestOptions
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
+|  [apiClient?](./generative-ai.requestoptions.apiclient.md) |  | string | _(Optional)_ Additional attribution information to include in the x-goog-api-client header. Used by wrapper SDKs. |
 |  [apiVersion?](./generative-ai.requestoptions.apiversion.md) |  | string | _(Optional)_ Version of API endpoint to call (e.g. "v1" or "v1beta"). If not specified, defaults to latest stable version. |
 |  [baseUrl?](./generative-ai.requestoptions.baseurl.md) |  | string | _(Optional)_ Base endpoint url. Defaults to "https://generativelanguage.googleapis.com" |
 |  [timeout?](./generative-ai.requestoptions.timeout.md) |  | number | _(Optional)_ Request timeout in milliseconds. |

packages/main/src/requests/request.test.ts

@@ -119,7 +119,33 @@ describe("request methods", () => {
         ok: true,
       } as Response);
       const response = await makeRequest(fakeRequestUrl, "");
-      expect(fetchStub).to.be.calledOnce;
+      expect(fetchStub).to.be.calledWith(fakeRequestUrl.toString(), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-goog-api-client": "genai-js/__PACKAGE_VERSION__",
+          "x-goog-api-key": fakeRequestUrl.apiKey,
+        },
+        body: "",
+      });
+      expect(response.ok).to.be.true;
+    });
+    it("passes apiClient", async () => {
+      const fetchStub = stub(globalThis, "fetch").resolves({
+        ok: true,
+      } as Response);
+      const response = await makeRequest(fakeRequestUrl, "", {
+        apiClient: "client/version",
+      });
+      expect(fetchStub).to.be.calledWith(fakeRequestUrl.toString(), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-goog-api-client": "client/version genai-js/__PACKAGE_VERSION__",
+          "x-goog-api-key": fakeRequestUrl.apiKey,
+        },
+        body: "",
+      });
       expect(response.ok).to.be.true;
     });
     it("error with timeout", async () => {

packages/main/src/requests/request.ts

@@ -59,8 +59,13 @@ export class RequestUrl {
 /**
  * Simple, but may become more complex if we add more versions to log.
  */
-function getClientHeaders(): string {
-  return `${PACKAGE_LOG_HEADER}/${PACKAGE_VERSION}`;
+export function getClientHeaders(requestOptions: RequestOptions): string {
+  const clientHeaders = [];
+  if (requestOptions?.apiClient) {
+    clientHeaders.push(requestOptions.apiClient);
+  }
+  clientHeaders.push(`${PACKAGE_LOG_HEADER}/${PACKAGE_VERSION}`);
+  return clientHeaders.join(" ");
 }
 
 export async function makeRequest(
@@ -75,7 +80,7 @@ export async function makeRequest(
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "x-goog-api-client": getClientHeaders(),
+        "x-goog-api-client": getClientHeaders(requestOptions),
         "x-goog-api-key": url.apiKey,
       },
       body,

packages/main/types/requests.ts

@@ -116,6 +116,11 @@ export interface RequestOptions {
    * defaults to latest stable version.
    */
   apiVersion?: string;
+  /**
+   * Additional attribution information to include in the x-goog-api-client header.
+   * Used by wrapper SDKs.
+   */
+  apiClient?: string;
   /**
    * Base endpoint url. Defaults to "https://generativelanguage.googleapis.com"
    */