feat: support API versioning

Author: jacobbednarz

src/core.ts

@@ -170,6 +170,7 @@ export class APIPromise<T> extends Promise<T> {
 
 export abstract class APIClient {
   baseURL: string;
+  apiVersion: string;
   maxRetries: number;
   timeout: number;
   httpAgent: Agent | undefined;
@@ -179,18 +180,21 @@ export abstract class APIClient {
 
   constructor({
     baseURL,
+    apiVersion,
     maxRetries = 2,
     timeout = 60000, // 1 minute
     httpAgent,
     fetch: overriddenFetch,
   }: {
     baseURL: string;
+    apiVersion: string;
     maxRetries?: number | undefined;
     timeout: number | undefined;
     httpAgent: Agent | undefined;
     fetch: Fetch | undefined;
   }) {
     this.baseURL = baseURL;
+    this.apiVersion = apiVersion;
     this.maxRetries = validatePositiveInteger('maxRetries', maxRetries);
     this.timeout = validatePositiveInteger('timeout', timeout);
     this.httpAgent = httpAgent;
@@ -215,6 +219,7 @@ export abstract class APIClient {
       Accept: 'application/json',
       'Content-Type': 'application/json',
       'User-Agent': this.getUserAgent(),
+      'api-version': this.getAPIVerson(),
       ...getPlatformHeaders(),
       ...this.authHeaders(opts),
     };
@@ -225,7 +230,7 @@ export abstract class APIClient {
   /**
    * Override this to add your own headers validation:
    */
-  protected validateHeaders(headers: Headers, customHeaders: Headers) {}
+  protected validateHeaders(headers: Headers, customHeaders: Headers) { }
 
   protected defaultIdempotencyKey(): string {
     return `stainless-node-retry-${uuid4()}`;
@@ -260,10 +265,10 @@ export abstract class APIClient {
       Promise.resolve(opts).then(async (opts) => {
         const body =
           opts && isBlobLike(opts?.body) ? new DataView(await opts.body.arrayBuffer())
-          : opts?.body instanceof DataView ? opts.body
-          : opts?.body instanceof ArrayBuffer ? new DataView(opts.body)
-          : opts && ArrayBuffer.isView(opts?.body) ? new DataView(opts.body.buffer)
-          : opts?.body;
+            : opts?.body instanceof DataView ? opts.body
+              : opts?.body instanceof ArrayBuffer ? new DataView(opts.body)
+                : opts && ArrayBuffer.isView(opts?.body) ? new DataView(opts.body.buffer)
+                  : opts?.body;
         return { method, path, ...opts, body };
       }),
     );
@@ -305,9 +310,9 @@ export abstract class APIClient {
     const body =
       ArrayBuffer.isView(options.body) || (options.__binaryRequest && typeof options.body === 'string') ?
         options.body
-      : isMultipartBody(options.body) ? options.body.body
-      : options.body ? JSON.stringify(options.body, null, 2)
-      : null;
+        : isMultipartBody(options.body) ? options.body.body
+          : options.body ? JSON.stringify(options.body, null, 2)
+            : null;
     const contentLength = this.calculateContentLength(body);
 
     const url = this.buildURL(path!, query);
@@ -396,7 +401,7 @@ export abstract class APIClient {
   /**
    * Used as a callback for mutating the given `FinalRequestOptions` object.
    */
-  protected async prepareOptions(options: FinalRequestOptions): Promise<void> {}
+  protected async prepareOptions(options: FinalRequestOptions): Promise<void> { }
 
   /**
    * Used as a callback for mutating the given `RequestInit` object.
@@ -407,14 +412,14 @@ export abstract class APIClient {
   protected async prepareRequest(
     request: RequestInit,
     { url, options }: { url: string; options: FinalRequestOptions },
-  ): Promise<void> {}
+  ): Promise<void> { }
 
   protected parseHeaders(headers: HeadersInit | null | undefined): Record<string, string> {
     return (
       !headers ? {}
-      : Symbol.iterator in headers ?
-        Object.fromEntries(Array.from(headers as Iterable<string[]>).map((header) => [...header]))
-      : { ...(headers as any as Record<string, string>) }
+        : Symbol.iterator in headers ?
+          Object.fromEntries(Array.from(headers as Iterable<string[]>).map((header) => [...header]))
+          : { ...(headers as any as Record<string, string>) }
     );
   }
 
@@ -507,7 +512,7 @@ export abstract class APIClient {
     const url =
       isAbsoluteURL(path) ?
         new URL(path)
-      : new URL(this.baseURL + (this.baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
+        : new URL(this.baseURL + (this.baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
     if (!isEmptyObj(defaultQuery)) {
@@ -646,6 +651,10 @@ export abstract class APIClient {
   private getUserAgent(): string {
     return `${this.constructor.name}/JS ${VERSION}`;
   }
+
+  private getAPIVerson(): string {
+    return this.apiVersion;
+  }
 }
 
 export type PageInfo = { url: URL } | { params: Record<string, unknown> | null };
@@ -728,9 +737,9 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
  *    }
  */
 export class PagePromise<
-    PageClass extends AbstractPage<Item>,
-    Item = ReturnType<PageClass['getPaginatedItems']>[number],
-  >
+  PageClass extends AbstractPage<Item>,
+  Item = ReturnType<PageClass['getPaginatedItems']>[number],
+>
   extends APIPromise<PageClass>
   implements AsyncIterable<Item>
 {
@@ -1030,7 +1039,7 @@ export const castToError = (err: any): Error => {
   if (typeof err === 'object' && err !== null) {
     try {
       return new Error(JSON.stringify(err));
-    } catch {}
+    } catch { }
   }
   return new Error(err);
 };

src/index.ts

@@ -141,6 +141,11 @@ export interface ClientOptions {
    */
   baseURL?: string | null | undefined;
 
+  /**
+   * Define the API version to target for the requests, e.g., "2025-01-01"
+   */
+  apiVersion?: string | null;
+
   /**
    * The maximum amount of time (in milliseconds) that the client should wait for a response
    * from the server before timing out a single request.
@@ -210,6 +215,7 @@ export class Cloudflare extends Core.APIClient {
    * @param {string | null | undefined} [opts.apiEmail=process.env['CLOUDFLARE_EMAIL'] ?? null]
    * @param {string | null | undefined} [opts.userServiceKey=process.env['CLOUDFLARE_API_USER_SERVICE_KEY'] ?? null]
    * @param {string} [opts.baseURL=process.env['CLOUDFLARE_BASE_URL'] ?? https://api.cloudflare.com/client/v4] - Override the default base URL for the API.
+   * @param {string | null} [opts.apiVersion] - Define the version to target for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
    * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
@@ -219,6 +225,7 @@ export class Cloudflare extends Core.APIClient {
    */
   constructor({
     baseURL = Core.readEnv('CLOUDFLARE_BASE_URL'),
+    apiVersion = null,
     apiToken = Core.readEnv('CLOUDFLARE_API_TOKEN') ?? null,
     apiKey = Core.readEnv('CLOUDFLARE_API_KEY') ?? null,
     apiEmail = Core.readEnv('CLOUDFLARE_EMAIL') ?? null,
@@ -232,10 +239,12 @@ export class Cloudflare extends Core.APIClient {
       userServiceKey,
       ...opts,
       baseURL: baseURL || `https://api.cloudflare.com/client/v4`,
+      apiVersion: apiVersion || new Date().toISOString().slice(0, 10),
     };
 
     super({
       baseURL: options.baseURL!,
+      apiVersion: options.apiVersion!,
       timeout: options.timeout ?? 60000 /* 1 minute */,
       httpAgent: options.httpAgent,
       maxRetries: options.maxRetries,