@nirvana-labs/nirvana 0.9.0 → 0.10.0

package/src/internal/to-file.ts

@@ -0,0 +1,152 @@
+import { type File, getFile } from './shims/file';
+import { BlobPart, getName, makeFile, isAsyncIterable } from './uploads';
+import type { FilePropertyBag } from './builtin-types';
+
+type BlobLikePart = string | ArrayBuffer | ArrayBufferView | BlobLike | DataView;
+
+/**
+ * Intended to match DOM Blob, node-fetch Blob, node:buffer Blob, etc.
+ * Don't add arrayBuffer here, node-fetch doesn't have it
+ */
+interface BlobLike {
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/size) */
+  readonly size: number;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/type) */
+  readonly type: string;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/text) */
+  text(): Promise<string>;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/slice) */
+  slice(start?: number, end?: number): BlobLike;
+}
+
+/**
+ * This check adds the arrayBuffer() method type because it is available and used at runtime
+ */
+const isBlobLike = (value: any): value is BlobLike & { arrayBuffer(): Promise<ArrayBuffer> } =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.size === 'number' &&
+  typeof value.type === 'string' &&
+  typeof value.text === 'function' &&
+  typeof value.slice === 'function' &&
+  typeof value.arrayBuffer === 'function';
+
+/**
+ * Intended to match DOM File, node:buffer File, undici File, etc.
+ */
+interface FileLike extends BlobLike {
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/lastModified) */
+  readonly lastModified: number;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/name) */
+  readonly name?: string | undefined;
+}
+
+/**
+ * This check adds the arrayBuffer() method type because it is available and used at runtime
+ */
+const isFileLike = (value: any): value is FileLike & { arrayBuffer(): Promise<ArrayBuffer> } =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.name === 'string' &&
+  typeof value.lastModified === 'number' &&
+  isBlobLike(value);
+
+/**
+ * Intended to match DOM Response, node-fetch Response, undici Response, etc.
+ */
+export interface ResponseLike {
+  url: string;
+  blob(): Promise<BlobLike>;
+}
+
+const isResponseLike = (value: any): value is ResponseLike =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.url === 'string' &&
+  typeof value.blob === 'function';
+
+export type ToFileInput =
+  | FileLike
+  | ResponseLike
+  | Exclude<BlobLikePart, string>
+  | AsyncIterable<BlobLikePart>;
+
+/**
+ * Helper for creating a {@link File} to pass to an SDK upload method from a variety of different data formats
+ * @param value the raw content of the file.  Can be an {@link Uploadable}, {@link BlobLikePart}, or {@link AsyncIterable} of {@link BlobLikePart}s
+ * @param {string=} name the name of the file. If omitted, toFile will try to determine a file name from bits if possible
+ * @param {Object=} options additional properties
+ * @param {string=} options.type the MIME type of the content
+ * @param {number=} options.lastModified the last modified timestamp
+ * @returns a {@link File} with the given properties
+ */
+export async function toFile(
+  value: ToFileInput | PromiseLike<ToFileInput>,
+  name?: string | null | undefined,
+  options?: FilePropertyBag | undefined,
+): Promise<File> {
+  // If it's a promise, resolve it.
+  value = await value;
+
+  // If we've been given a `File` we don't need to do anything
+  if (isFileLike(value)) {
+    if (value instanceof getFile()) {
+      return value;
+    }
+    return makeFile([await value.arrayBuffer()], value.name);
+  }
+
+  if (isResponseLike(value)) {
+    const blob = await value.blob();
+    name ||= new URL(value.url).pathname.split(/[\\/]/).pop();
+
+    return makeFile(await getBytes(blob), name, options);
+  }
+
+  const parts = await getBytes(value);
+
+  name ||= getName(value);
+
+  if (!options?.type) {
+    const type = parts.find((part) => typeof part === 'object' && 'type' in part && part.type);
+    if (typeof type === 'string') {
+      options = { ...options, type };
+    }
+  }
+
+  return makeFile(parts, name, options);
+}
+
+async function getBytes(value: BlobLikePart | AsyncIterable<BlobLikePart>): Promise<Array<BlobPart>> {
+  let parts: Array<BlobPart> = [];
+  if (
+    typeof value === 'string' ||
+    ArrayBuffer.isView(value) || // includes Uint8Array, Buffer, etc.
+    value instanceof ArrayBuffer
+  ) {
+    parts.push(value);
+  } else if (isBlobLike(value)) {
+    parts.push(value instanceof Blob ? value : await value.arrayBuffer());
+  } else if (
+    isAsyncIterable(value) // includes Readable, ReadableStream, etc.
+  ) {
+    for await (const chunk of value) {
+      parts.push(...(await getBytes(chunk as BlobLikePart))); // TODO, consider validating?
+    }
+  } else {
+    const constructor = value?.constructor?.name;
+    throw new Error(
+      `Unexpected data type: ${typeof value}${
+        constructor ? `; constructor: ${constructor}` : ''
+      }${propsForError(value)}`,
+    );
+  }
+
+  return parts;
+}
+
+function propsForError(value: unknown): string {
+  if (typeof value !== 'object' || value === null) return '';
+  const props = Object.getOwnPropertyNames(value);
+  return `; props: [${props.map((p) => `"${p}"`).join(', ')}]`;
+}

package/src/internal/types.ts

@@ -0,0 +1,92 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export type PromiseOrValue<T> = T | Promise<T>;
+export type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+
+export type KeysEnum<T> = { [P in keyof Required<T>]: true };
+
+export type FinalizedRequestInit = RequestInit & { headers: Headers };
+
+type NotAny<T> = [unknown] extends [T] ? never : T;
+
+/**
+ * Some environments overload the global fetch function, and Parameters<T> only gets the last signature.
+ */
+type OverloadedParameters<T> =
+  T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+      (...args: infer C): unknown;
+      (...args: infer D): unknown;
+    }
+  ) ?
+    A | B | C | D
+  : T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+      (...args: infer C): unknown;
+    }
+  ) ?
+    A | B | C
+  : T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+    }
+  ) ?
+    A | B
+  : T extends (...args: infer A) => unknown ? A
+  : never;
+
+/* eslint-disable */
+/**
+ * These imports attempt to get types from a parent package's dependencies.
+ * Unresolved bare specifiers can trigger [automatic type acquisition][1] in some projects, which
+ * would cause typescript to show types not present at runtime. To avoid this, we import
+ * directly from parent node_modules folders.
+ *
+ * We need to check multiple levels because we don't know what directory structure we'll be in.
+ * For example, pnpm generates directories like this:
+ * ```
+ * node_modules
+ * ├── .pnpm
+ * │   └── pkg@1.0.0
+ * │       └── node_modules
+ * │           └── pkg
+ * │               └── internal
+ * │                   └── types.d.ts
+ * ├── pkg -> .pnpm/pkg@1.0.0/node_modules/pkg
+ * └── undici
+ * ```
+ *
+ * [1]: https://www.typescriptlang.org/tsconfig/#typeAcquisition
+ */
+/** @ts-ignore For users with \@types/node */
+type UndiciTypesRequestInit = NotAny<import('../node_modules/undici-types').RequestInit> | NotAny<import('../../node_modules/undici-types').RequestInit> | NotAny<import('../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici-types').RequestInit>;
+/** @ts-ignore For users with undici */
+type UndiciRequestInit = NotAny<import('../node_modules/undici').RequestInit> | NotAny<import('../../node_modules/undici').RequestInit> | NotAny<import('../../../node_modules/undici').RequestInit> | NotAny<import('../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici').RequestInit>;
+/** @ts-ignore For users with \@types/bun */
+type BunRequestInit = globalThis.FetchRequestInit;
+/** @ts-ignore For users with node-fetch */
+type NodeFetchRequestInit = NotAny<import('../node_modules/node-fetch').RequestInit> | NotAny<import('../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/node-fetch').RequestInit>;
+/** @ts-ignore For users who use Deno */
+type FetchRequestInit = NonNullable<OverloadedParameters<typeof fetch>[1]>;
+/* eslint-enable */
+
+type RequestInits =
+  | NotAny<UndiciTypesRequestInit>
+  | NotAny<UndiciRequestInit>
+  | NotAny<BunRequestInit>
+  | NotAny<NodeFetchRequestInit>
+  | NotAny<RequestInit>
+  | NotAny<FetchRequestInit>;
+
+/**
+ * This type contains `RequestInit` options that may be available on the current runtime,
+ * including per-platform extensions like `dispatcher`, `agent`, `client`, etc.
+ */
+export type MergedRequestInit = RequestInits &
+  /** We don't include these in the types as they'll be overridden for every request. */
+  Partial<Record<'body' | 'headers' | 'method' | 'signal', never>>;

package/src/internal/uploads.ts

@@ -0,0 +1,175 @@
+import { type RequestOptions } from './request-options';
+import type { FilePropertyBag, Fetch } from './builtin-types';
+import type { NirvanaLabs } from '../client';
+import { type File, getFile } from './shims/file';
+import { ReadableStreamFrom } from './shims';
+
+export type BlobPart = string | ArrayBuffer | ArrayBufferView | Blob | DataView;
+type FsReadStream = AsyncIterable<Uint8Array> & { path: string | { toString(): string } };
+
+// https://github.com/oven-sh/bun/issues/5980
+interface BunFile extends Blob {
+  readonly name?: string | undefined;
+}
+
+/**
+ * Typically, this is a native "File" class.
+ *
+ * We provide the {@link toFile} utility to convert a variety of objects
+ * into the File class.
+ *
+ * For convenience, you can also pass a fetch Response, or in Node,
+ * the result of fs.createReadStream().
+ */
+export type Uploadable = File | Response | FsReadStream | BunFile;
+
+/**
+ * Construct a `File` instance. This is used to ensure a helpful error is thrown
+ * for environments that don't define a global `File` yet.
+ */
+export function makeFile(
+  fileBits: BlobPart[],
+  fileName: string | undefined,
+  options?: FilePropertyBag,
+): File {
+  const File = getFile();
+  return new File(fileBits as any, fileName ?? 'unknown_file', options);
+}
+
+export function getName(value: any): string | undefined {
+  return (
+    (
+      (typeof value === 'object' &&
+        value !== null &&
+        (('name' in value && value.name && String(value.name)) ||
+          ('url' in value && value.url && String(value.url)) ||
+          ('filename' in value && value.filename && String(value.filename)) ||
+          ('path' in value && value.path && String(value.path)))) ||
+      ''
+    )
+      .split(/[\\/]/)
+      .pop() || undefined
+  );
+}
+
+export const isAsyncIterable = (value: any): value is AsyncIterable<any> =>
+  value != null && typeof value === 'object' && typeof value[Symbol.asyncIterator] === 'function';
+
+/**
+ * Returns a multipart/form-data request if any part of the given request body contains a File / Blob value.
+ * Otherwise returns the request as is.
+ */
+export const maybeMultipartFormRequestOptions = async (
+  opts: RequestOptions,
+  fetch: NirvanaLabs | Fetch,
+): Promise<RequestOptions> => {
+  if (!hasUploadableValue(opts.body)) return opts;
+
+  return { ...opts, body: await createForm(opts.body, fetch) };
+};
+
+type MultipartFormRequestOptions = Omit<RequestOptions, 'body'> & { body: unknown };
+
+export const multipartFormRequestOptions = async (
+  opts: MultipartFormRequestOptions,
+  fetch: NirvanaLabs | Fetch,
+): Promise<RequestOptions> => {
+  return { ...opts, body: await createForm(opts.body, fetch) };
+};
+
+const supportsFormDataMap = new WeakMap<Fetch, Promise<boolean>>();
+
+/**
+ * node-fetch doesn't support the global FormData object in recent node versions. Instead of sending
+ * properly-encoded form data, it just stringifies the object, resulting in a request body of "[object FormData]".
+ * This function detects if the fetch function provided supports the global FormData object to avoid
+ * confusing error messages later on.
+ */
+function supportsFormData(fetchObject: NirvanaLabs | Fetch): Promise<boolean> {
+  const fetch: Fetch = typeof fetchObject === 'function' ? fetchObject : (fetchObject as any).fetch;
+  const cached = supportsFormDataMap.get(fetch);
+  if (cached) return cached;
+  const promise = (async () => {
+    try {
+      const FetchResponse = (
+        'Response' in fetch ?
+          fetch.Response
+        : (await fetch('data:,')).constructor) as typeof Response;
+      const data = new FormData();
+      if (data.toString() === (await new FetchResponse(data).text())) {
+        return false;
+      }
+      return true;
+    } catch {
+      // avoid false negatives
+      return true;
+    }
+  })();
+  supportsFormDataMap.set(fetch, promise);
+  return promise;
+}
+
+export const createForm = async <T = Record<string, unknown>>(
+  body: T | undefined,
+  fetch: NirvanaLabs | Fetch,
+): Promise<FormData> => {
+  if (!(await supportsFormData(fetch))) {
+    throw new TypeError(
+      'The provided fetch function does not support file uploads with the current global FormData class.',
+    );
+  }
+  const form = new FormData();
+  await Promise.all(Object.entries(body || {}).map(([key, value]) => addFormValue(form, key, value)));
+  return form;
+};
+
+// We check for Blob not File because Bun.File doesn't inherit from File,
+// but they both inherit from Blob and have a `name` property at runtime.
+const isNamedBlob = (value: object) =>
+  value instanceof getFile() || (value instanceof Blob && 'name' in value);
+
+const isUploadable = (value: unknown) =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value instanceof Response || isAsyncIterable(value) || isNamedBlob(value));
+
+const hasUploadableValue = (value: unknown): boolean => {
+  if (isUploadable(value)) return true;
+  if (Array.isArray(value)) return value.some(hasUploadableValue);
+  if (value && typeof value === 'object') {
+    for (const k in value) {
+      if (hasUploadableValue((value as any)[k])) return true;
+    }
+  }
+  return false;
+};
+
+const addFormValue = async (form: FormData, key: string, value: unknown): Promise<void> => {
+  if (value === undefined) return;
+  if (value == null) {
+    throw new TypeError(
+      `Received null for "${key}"; to pass null in FormData, you must use the string 'null'`,
+    );
+  }
+
+  // TODO: make nested formats configurable
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    form.append(key, String(value));
+  } else if (value instanceof Response) {
+    form.append(key, makeFile([await value.blob()], getName(value)));
+  } else if (isAsyncIterable(value)) {
+    form.append(key, makeFile([await new Response(ReadableStreamFrom(value)).blob()], getName(value)));
+  } else if (isNamedBlob(value)) {
+    form.append(key, value, getName(value));
+  } else if (Array.isArray(value)) {
+    await Promise.all(value.map((entry) => addFormValue(form, key + '[]', entry)));
+  } else if (typeof value === 'object') {
+    await Promise.all(
+      Object.entries(value).map(([name, prop]) => addFormValue(form, `${key}[${name}]`, prop)),
+    );
+  } else {
+    throw new TypeError(
+      `Invalid value given to form, expected a string, number, boolean, object, Array, File or Blob but got ${value} instead`,
+    );
+  }
+};

package/src/internal/utils/base64.ts

@@ -0,0 +1,37 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { NirvanaLabsError } from '../../core/error';
+
+export const toBase64 = (data: string | Uint8Array | null | undefined): string => {
+  if (!data) return '';
+
+  if (typeof data === 'string') {
+    data = new (globalThis as any).TextEncoder().encode(data);
+  }
+
+  if (typeof (globalThis as any).Buffer !== 'undefined') {
+    return (globalThis as any).Buffer.from(data).toString('base64');
+  }
+
+  if (typeof btoa !== 'undefined') {
+    return btoa(String.fromCharCode.apply(null, data as any));
+  }
+
+  throw new NirvanaLabsError('Cannot generate base64 string; Expected `Buffer` or `btoa` to be defined');
+};
+
+export const fromBase64 = (str: string): Uint8Array => {
+  if (typeof (globalThis as any).Buffer !== 'undefined') {
+    return new Uint8Array((globalThis as any).Buffer.from(str, 'base64'));
+  }
+
+  if (typeof atob !== 'undefined') {
+    return new Uint8Array(
+      atob(str)
+        .split('')
+        .map((c) => c.charCodeAt(0)),
+    );
+  }
+
+  throw new NirvanaLabsError('Cannot decode base64 string; Expected `Buffer` or `atob` to be defined');
+};

package/src/internal/utils/env.ts

@@ -0,0 +1,18 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+/**
+ * Read an environment variable.
+ *
+ * Trims beginning and trailing whitespace.
+ *
+ * Will return undefined if the environment variable doesn't exist or cannot be accessed.
+ */
+export const readEnv = (env: string): string | undefined => {
+  if (typeof (globalThis as any).process !== 'undefined') {
+    return (globalThis as any).process.env?.[env]?.trim() ?? undefined;
+  }
+  if (typeof (globalThis as any).Deno !== 'undefined') {
+    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+  }
+  return undefined;
+};

package/src/internal/utils/log.ts

@@ -0,0 +1,126 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { hasOwn } from './values';
+import { type NirvanaLabs } from '../../client';
+import { RequestOptions } from '../request-options';
+
+type LogFn = (message: string, ...rest: unknown[]) => void;
+export type Logger = {
+  error: LogFn;
+  warn: LogFn;
+  info: LogFn;
+  debug: LogFn;
+};
+export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug';
+
+const levelNumbers = {
+  off: 0,
+  error: 200,
+  warn: 300,
+  info: 400,
+  debug: 500,
+};
+
+export const parseLogLevel = (
+  maybeLevel: string | undefined,
+  sourceName: string,
+  client: NirvanaLabs,
+): LogLevel | undefined => {
+  if (!maybeLevel) {
+    return undefined;
+  }
+  if (hasOwn(levelNumbers, maybeLevel)) {
+    return maybeLevel;
+  }
+  loggerFor(client).warn(
+    `${sourceName} was set to ${JSON.stringify(maybeLevel)}, expected one of ${JSON.stringify(
+      Object.keys(levelNumbers),
+    )}`,
+  );
+  return undefined;
+};
+
+function noop() {}
+
+function makeLogFn(fnLevel: keyof Logger, logger: Logger | undefined, logLevel: LogLevel) {
+  if (!logger || levelNumbers[fnLevel] > levelNumbers[logLevel]) {
+    return noop;
+  } else {
+    // Don't wrap logger functions, we want the stacktrace intact!
+    return logger[fnLevel].bind(logger);
+  }
+}
+
+const noopLogger = {
+  error: noop,
+  warn: noop,
+  info: noop,
+  debug: noop,
+};
+
+let cachedLoggers = new WeakMap<Logger, [LogLevel, Logger]>();
+
+export function loggerFor(client: NirvanaLabs): Logger {
+  const logger = client.logger;
+  const logLevel = client.logLevel ?? 'off';
+  if (!logger) {
+    return noopLogger;
+  }
+
+  const cachedLogger = cachedLoggers.get(logger);
+  if (cachedLogger && cachedLogger[0] === logLevel) {
+    return cachedLogger[1];
+  }
+
+  const levelLogger = {
+    error: makeLogFn('error', logger, logLevel),
+    warn: makeLogFn('warn', logger, logLevel),
+    info: makeLogFn('info', logger, logLevel),
+    debug: makeLogFn('debug', logger, logLevel),
+  };
+
+  cachedLoggers.set(logger, [logLevel, levelLogger]);
+
+  return levelLogger;
+}
+
+export const formatRequestDetails = (details: {
+  options?: RequestOptions | undefined;
+  headers?: Headers | Record<string, string> | undefined;
+  retryOfRequestLogID?: string | undefined;
+  retryOf?: string | undefined;
+  url?: string | undefined;
+  status?: number | undefined;
+  method?: string | undefined;
+  durationMs?: number | undefined;
+  message?: unknown;
+  body?: unknown;
+}) => {
+  if (details.options) {
+    details.options = { ...details.options };
+    delete details.options['headers']; // redundant + leaks internals
+  }
+  if (details.headers) {
+    details.headers = Object.fromEntries(
+      (details.headers instanceof Headers ? [...details.headers] : Object.entries(details.headers)).map(
+        ([name, value]) => [
+          name,
+          (
+            name.toLowerCase() === 'authorization' ||
+            name.toLowerCase() === 'cookie' ||
+            name.toLowerCase() === 'set-cookie'
+          ) ?
+            '***'
+          : value,
+        ],
+      ),
+    );
+  }
+  if ('retryOfRequestLogID' in details) {
+    if (details.retryOfRequestLogID) {
+      details.retryOf = details.retryOfRequestLogID;
+    }
+    delete details.retryOfRequestLogID;
+  }
+  return details;
+};

package/src/internal/utils/path.ts

@@ -0,0 +1,65 @@
+import { NirvanaLabsError } from '../../core/error';
+
+/**
+ * Percent-encode everything that isn't safe to have in a path without encoding safe chars.
+ *
+ * Taken from https://datatracker.ietf.org/doc/html/rfc3986#section-3.3:
+ * > unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
+ * > sub-delims  = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+ * > pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
+ */
+export function encodeURIPath(str: string) {
+  return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
+}
+
+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 path = statics.reduce((previousValue, currentValue, index) => {
+      if (/[?#]/.test(currentValue)) {
+        postPath = true;
+      }
+      return (
+        previousValue +
+        currentValue +
+        (index === params.length ? '' : (postPath ? encodeURIComponent : pathEncoder)(String(params[index])))
+      );
+    }, '');
+
+    const pathOnly = path.split(/[?#]/, 1)[0]!;
+    const invalidSegments = [];
+    const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
+    let match;
+
+    // Find all invalid segments
+    while ((match = invalidSegmentPattern.exec(pathOnly)) !== null) {
+      invalidSegments.push({
+        start: match.index,
+        length: match[0].length,
+      });
+    }
+
+    if (invalidSegments.length > 0) {
+      let lastEnd = 0;
+      const underline = invalidSegments.reduce((acc, segment) => {
+        const spaces = ' '.repeat(segment.start - lastEnd);
+        const arrows = '^'.repeat(segment.length);
+        lastEnd = segment.start + segment.length;
+        return acc + spaces + arrows;
+      }, '');
+
+      throw new NirvanaLabsError(
+        `Path parameters result in path with invalid segments:\n${path}\n${underline}`,
+      );
+    }
+
+    return path;
+  };
+
+/**
+ * URI-encodes path params and ensures no unsafe /./ or /../ path segments are introduced.
+ */
+export const path = createPathTagFunction(encodeURIPath);

package/src/internal/utils/sleep.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));