release: 1.2.2 (#59)

* chore(client): improve path param validation

* chore: add docs to RequestOptions type

* chore: make some internal functions async

* release: 1.2.2

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.2.1"
+  ".": "1.2.2"
 }

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.2.2 (2025-07-10)
+
+Full Changelog: [v1.2.1...v1.2.2](https://github.com/GRID-is/api-sdk-ts/compare/v1.2.1...v1.2.2)
+
+### Chores
+
+* add docs to RequestOptions type ([a197e2f](https://github.com/GRID-is/api-sdk-ts/commit/a197e2f7d9053be0bb303005ef5da2b620cd21a2))
+* **client:** improve path param validation ([e6d7ff7](https://github.com/GRID-is/api-sdk-ts/commit/e6d7ff72a2de23b52636a752093ba9362543d58a))
+* make some internal functions async ([4f16312](https://github.com/GRID-is/api-sdk-ts/commit/4f163129b3d74e9662e609a9e0191bc2778ec659))
+
 ## 1.2.1 (2025-06-28)
 
 Full Changelog: [v1.2.0...v1.2.1](https://github.com/GRID-is/api-sdk-ts/compare/v1.2.0...v1.2.1)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grid-is/api",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "The official TypeScript library for the Grid API",
   "author": "Grid <info@grid.is>",
   "types": "dist/index.d.ts",

src/client.ts

@@ -73,6 +73,8 @@ export interface ClientOptions {
    *
    * 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.
+   *
+   * @unit milliseconds
    */
   timeout?: number | undefined;
   /**
@@ -198,7 +200,7 @@ export class Grid {
    * Create a new client instance re-using the same options given to the current client with optional overriding.
    */
   withOptions(options: Partial<ClientOptions>): this {
-    return new (this.constructor as any as new (props: ClientOptions) => typeof this)({
+    const client = new (this.constructor as any as new (props: ClientOptions) => typeof this)({
       ...this._options,
       baseURL: this.baseURL,
       maxRetries: this.maxRetries,
@@ -210,6 +212,7 @@ export class Grid {
       apiKey: this.apiKey,
       ...options,
     });
+    return client;
   }
 
   /**
@@ -227,7 +230,7 @@ export class Grid {
     return;
   }
 
-  protected authHeaders(opts: FinalRequestOptions): NullableHeaders | undefined {
+  protected async authHeaders(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
     return buildHeaders([{ Authorization: `Bearer ${this.apiKey}` }]);
   }
 
@@ -359,7 +362,9 @@ export class Grid {
 
     await this.prepareOptions(options);
 
-    const { req, url, timeout } = this.buildRequest(options, { retryCount: maxRetries - retriesRemaining });
+    const { req, url, timeout } = await this.buildRequest(options, {
+      retryCount: maxRetries - retriesRemaining,
+    });
 
     await this.prepareRequest(req, { url, options });
 
@@ -437,7 +442,7 @@ export class Grid {
     } with status ${response.status} in ${headersTime - startTime}ms`;
 
     if (!response.ok) {
-      const shouldRetry = this.shouldRetry(response);
+      const shouldRetry = await this.shouldRetry(response);
       if (retriesRemaining && shouldRetry) {
         const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
 
@@ -555,7 +560,7 @@ export class Grid {
     }
   }
 
-  private shouldRetry(response: Response): boolean {
+  private async shouldRetry(response: Response): Promise<boolean> {
     // Note this is not a standard header.
     const shouldRetryHeader = response.headers.get('x-should-retry');
 
@@ -632,18 +637,18 @@ export class Grid {
     return sleepSeconds * jitter * 1000;
   }
 
-  buildRequest(
+  async buildRequest(
     inputOptions: FinalRequestOptions,
     { retryCount = 0 }: { retryCount?: number } = {},
-  ): { req: FinalizedRequestInit; url: string; timeout: number } {
+  ): Promise<{ req: FinalizedRequestInit; url: string; timeout: number }> {
     const options = { ...inputOptions };
     const { method, path, query, defaultBaseURL } = options;
 
     const url = this.buildURL(path!, query as Record<string, unknown>, defaultBaseURL);
     if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
     options.timeout = options.timeout ?? this.timeout;
     const { bodyHeaders, body } = this.buildBody({ options });
-    const reqHeaders = this.buildHeaders({ options: inputOptions, method, bodyHeaders, retryCount });
+    const reqHeaders = await this.buildHeaders({ options: inputOptions, method, bodyHeaders, retryCount });
 
     const req: FinalizedRequestInit = {
       method,
@@ -659,7 +664,7 @@ export class Grid {
     return { req, url, timeout: options.timeout };
   }
 
-  private buildHeaders({
+  private async buildHeaders({
     options,
     method,
     bodyHeaders,
@@ -669,7 +674,7 @@ export class Grid {
     method: HTTPMethod;
     bodyHeaders: HeadersLike;
     retryCount: number;
-  }): Headers {
+  }): Promise<Headers> {
     let idempotencyHeaders: HeadersLike = {};
     if (this.idempotencyHeader && method !== 'get') {
       if (!options.idempotencyKey) options.idempotencyKey = this.defaultIdempotencyKey();
@@ -686,7 +691,7 @@ export class Grid {
         ...getPlatformHeaders(),
         'X-Client-Name': 'api-sdk',
       },
-      this.authHeaders(options),
+      await this.authHeaders(options),
       this._options.defaultHeaders,
       bodyHeaders,
       options.headers,

src/internal/request-options.ts

@@ -9,17 +9,70 @@ import { type HeadersLike } from './headers';
 export type FinalRequestOptions = RequestOptions & { method: HTTPMethod; path: string };
 
 export type RequestOptions = {
+  /**
+   * The HTTP method for the request (e.g., 'get', 'post', 'put', 'delete').
+   */
   method?: HTTPMethod;
+
+  /**
+   * The URL path for the request.
+   *
+   * @example "/v1/foo"
+   */
   path?: string;
+
+  /**
+   * Query parameters to include in the request URL.
+   */
   query?: object | undefined | null;
+
+  /**
+   * The request body. Can be a string, JSON object, FormData, or other supported types.
+   */
   body?: unknown;
+
+  /**
+   * HTTP headers to include with the request. Can be a Headers object, plain object, or array of tuples.
+   */
   headers?: HeadersLike;
+
+  /**
+   * 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;
+
   stream?: boolean | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * @unit milliseconds
+   */
   timeout?: number;
+
+  /**
+   * Additional `RequestInit` options to be passed to the underlying `fetch` call.
+   * These options will be merged with the client's default fetch options.
+   */
   fetchOptions?: MergedRequestInit;
+
+  /**
+   * An AbortSignal that can be used to cancel the request.
+   */
   signal?: AbortSignal | undefined | null;
+
+  /**
+   * A unique key for this request to enable idempotency.
+   */
   idempotencyKey?: string;
+
+  /**
+   * Override the default base URL for this specific request.
+   */
   defaultBaseURL?: string | undefined;
 
   __binaryResponse?: boolean | undefined;

src/internal/uploads.ts

@@ -90,7 +90,7 @@ export const multipartFormRequestOptions = async (
   return { ...opts, body: await createForm(opts.body, fetch) };
 };
 
-const supportsFormDataMap = /** @__PURE__ */ new WeakMap<Fetch, Promise<boolean>>();
+const supportsFormDataMap = /* @__PURE__ */ new WeakMap<Fetch, Promise<boolean>>();
 
 /**
  * node-fetch doesn't support the global FormData object in recent node versions. Instead of sending

src/internal/utils/log.ts

@@ -58,7 +58,7 @@ const noopLogger = {
   debug: noop,
 };
 
-let cachedLoggers = /** @__PURE__ */ new WeakMap<Logger, [LogLevel, Logger]>();
+let cachedLoggers = /* @__PURE__ */ new WeakMap<Logger, [LogLevel, Logger]>();
 
 export function loggerFor(client: Grid): Logger {
   const logger = client.logger;

src/internal/utils/path.ts

@@ -12,25 +12,43 @@ export function encodeURIPath(str: string) {
   return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
 }
 
+const EMPTY = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null));
+
 export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
   function path(statics: readonly string[], ...params: readonly unknown[]): string {
     // If there are no params, no processing is needed.
     if (statics.length === 1) return statics[0]!;
 
     let postPath = false;
+    const invalidSegments = [];
     const path = statics.reduce((previousValue, currentValue, index) => {
       if (/[?#]/.test(currentValue)) {
         postPath = true;
       }
-      return (
-        previousValue +
-        currentValue +
-        (index === params.length ? '' : (postPath ? encodeURIComponent : pathEncoder)(String(params[index])))
-      );
+      const value = params[index];
+      let encoded = (postPath ? encodeURIComponent : pathEncoder)('' + value);
+      if (
+        index !== params.length &&
+        (value == null ||
+          (typeof value === 'object' &&
+            // handle values from other realms
+            value.toString ===
+              Object.getPrototypeOf(Object.getPrototypeOf((value as any).hasOwnProperty ?? EMPTY) ?? EMPTY)
+                ?.toString))
+      ) {
+        encoded = value + '';
+        invalidSegments.push({
+          start: previousValue.length + currentValue.length,
+          length: encoded.length,
+          error: `Value of type ${Object.prototype.toString
+            .call(value)
+            .slice(8, -1)} is not a valid path parameter`,
+        });
+      }
+      return previousValue + currentValue + (index === params.length ? '' : encoded);
     }, '');
 
     const pathOnly = path.split(/[?#]/, 1)[0]!;
-    const invalidSegments = [];
     const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
     let match;
 
@@ -39,9 +57,12 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
       invalidSegments.push({
         start: match.index,
         length: match[0].length,
+        error: `Value "${match[0]}" can\'t be safely passed as a path parameter`,
       });
     }
 
+    invalidSegments.sort((a, b) => a.start - b.start);
+
     if (invalidSegments.length > 0) {
       let lastEnd = 0;
       const underline = invalidSegments.reduce((acc, segment) => {
@@ -51,7 +72,11 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
         return acc + spaces + arrows;
       }, '');
 
-      throw new GridError(`Path parameters result in path with invalid segments:\n${path}\n${underline}`);
+      throw new GridError(
+        `Path parameters result in path with invalid segments:\n${invalidSegments
+          .map((e) => e.error)
+          .join('\n')}\n${path}\n${underline}`,
+      );
     }
 
     return path;

src/version.ts

@@ -1 +1 @@
-export const VERSION = '1.2.1'; // x-release-please-version
+export const VERSION = '1.2.2'; // x-release-please-version