docs(client): improve documentation for client options

src/index.ts

@@ -12,12 +12,53 @@ type Config = {
    * Defaults to process.env["ANTHROPIC_API_KEY"]. Set it to null if you want to send unauthenticated requests.
    */
   apiKey?: string | null;
+
+  /**
+   * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+   */
   baseURL?: string;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+   * much longer than this timeout before the promise succeeds or fails.
+   */
   timeout?: number;
+
+  /**
+   * An HTTP agent used to manage HTTP(S) connections.
+   *
+   * If not provided, an agent will be constructed by default in the Node.js environment,
+   * otherwise no agent is used.
+   */
   httpAgent?: Agent;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
   maxRetries?: number;
+
+  /**
+   * Default headers to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * header to `undefined` or `null` in request options.
+   */
   defaultHeaders?: Core.Headers;
+
+  /**
+   * Default query parameters to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * param to `undefined` in request options.
+   */
   defaultQuery?: Core.DefaultQuery;
+
   authToken?: string | null;
 };
 

tests/index.test.ts

@@ -17,11 +17,35 @@ describe('instantiate client', () => {
     process.env = env;
   });
 
-  test('defaultHeaders are passed through', () => {
-    const client = new Anthropic({ defaultHeaders: { 'X-My-Default-Header': '2' }, apiKey: 'my api key' });
+  describe('defaultHeaders', () => {
+    const client = new Anthropic({
+      baseURL: 'http://localhost:5000/',
+      defaultHeaders: { 'X-My-Default-Header': '2' },
+      apiKey: 'my api key',
+    });
+
+    test('they are used in the request', () => {
+      const { req } = client.buildRequest({ path: '/foo', method: 'post' });
+      expect((req.headers as Headers)['X-My-Default-Header']).toEqual('2');
+    });
+
+    test('can be overriden with `undefined`', () => {
+      const { req } = client.buildRequest({
+        path: '/foo',
+        method: 'post',
+        headers: { 'X-My-Default-Header': undefined },
+      });
+      expect((req.headers as Headers)['X-My-Default-Header']).toBeUndefined();
+    });
 
-    const { req } = client.buildRequest({ path: '/foo', method: 'post' });
-    expect((req.headers as Headers)['X-My-Default-Header']).toEqual('2');
+    test('can be overriden with `null`', () => {
+      const { req } = client.buildRequest({
+        path: '/foo',
+        method: 'post',
+        headers: { 'X-My-Default-Header': null },
+      });
+      expect((req.headers as Headers)['X-My-Default-Header']).toBeUndefined();
+    });
   });
 
   describe('defaultQuery', () => {