@roarkanalytics/sdk 2.21.1 → 2.22.0

package/src/internal/uploads.ts

@@ -1,11 +1,29 @@
 import { type RequestOptions } from './request-options';
 import type { FilePropertyBag, Fetch } from './builtin-types';
-import { isFsReadStreamLike, type FsReadStreamLike } from './shims';
 import type { Roark } from '../client';
-import './polyfill/file.node.js';
+import { ReadableStreamFrom } from './shims';
 
-type BlobLikePart = string | ArrayBuffer | ArrayBufferView | BlobLike | DataView;
-type BlobPart = string | ArrayBuffer | ArrayBufferView | Blob | DataView;
+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;
+}
+
+export const checkFileSupport = () => {
+  if (typeof File === 'undefined') {
+    const { process } = globalThis as any;
+    const isOldNode =
+      typeof process?.versions?.node === 'string' && parseInt(process.versions.node.split('.')) < 20;
+    throw new Error(
+      '`File` is not defined as a global, which is required for file uploads.' +
+        (isOldNode ?
+          " Update to Node 20 LTS or newer, or set `globalThis.File` to `import('node:buffer').File`."
+        : ''),
+    );
+  }
+};
 
 /**
  * Typically, this is a native "File" class.
@@ -16,188 +34,38 @@ type BlobPart = string | ArrayBuffer | ArrayBufferView | Blob | DataView;
  * For convenience, you can also pass a fetch Response, or in Node,
  * the result of fs.createReadStream().
  */
-export type Uploadable = FileLike | ResponseLike | FsReadStreamLike;
-
-/**
- * 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;
-}
-declare var FileClass: {
-  prototype: FileLike;
-  new (fileBits: BlobPart[], fileName: string, options?: FilePropertyBag): FileLike;
-};
-
-/**
- * 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';
-
-const isUploadable = (value: any): value is Uploadable => {
-  return isFileLike(value) || isResponseLike(value) || isFsReadStreamLike(value);
-};
-
-type ToFileInput = Uploadable | Exclude<BlobLikePart, string> | AsyncIterable<BlobLikePart>;
+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 and so that we don't
- * accidentally rely on a global `File` type in our annotations.
+ * for environments that don't define a global `File` yet.
  */
-function makeFile(fileBits: BlobPart[], fileName: string, options?: FilePropertyBag): FileLike {
-  const File = (globalThis as any).File as typeof FileClass | undefined;
-  if (typeof File === 'undefined') {
-    throw new Error('`File` is not defined as a global which is required for file uploads');
-  }
-
-  return new File(fileBits, fileName, options);
+export function makeFile(
+  fileBits: BlobPart[],
+  fileName: string | undefined,
+  options?: FilePropertyBag,
+): File {
+  checkFileSupport();
+  return new File(fileBits as any, fileName ?? 'unknown_file', options);
 }
 
-/**
- * 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<FileLike> {
-  // 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)) {
-    const File = (globalThis as any).File as typeof FileClass | undefined;
-    if (File && value instanceof File) {
-      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() ?? 'unknown_file';
-
-    return makeFile(await getBytes(blob), name, options);
-  }
-
-  const parts = await getBytes(value);
-
-  name ||= getName(value) ?? 'unknown_file';
-
-  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);
-}
-
-export async function getBytes(
-  value: Uploadable | 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 (
-    isAsyncIterableIterator(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(', ')}]`;
-}
-
-function getName(value: unknown): string | undefined {
+export function getName(value: any): string | undefined {
   return (
-    (typeof value === 'object' &&
-      value !== null &&
-      (('name' in value && String(value.name)) ||
-        ('filename' in value && String(value.filename)) ||
-        ('path' in value && String(value.path).split(/[\\/]/).pop()))) ||
-    undefined
+    (
+      (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
   );
 }
 
-const isAsyncIterableIterator = (value: any): value is AsyncIterableIterator<unknown> =>
+export const isAsyncIterable = (value: any): value is AsyncIterable<any> =>
   value != null && typeof value === 'object' && typeof value[Symbol.asyncIterator] === 'function';
 
 /**
@@ -222,7 +90,7 @@ export const multipartFormRequestOptions = async (
   return { ...opts, body: await createForm(opts.body, fetch) };
 };
 
-const supportsFormDataMap = 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
@@ -268,6 +136,15 @@ export const createForm = async <T = Record<string, unknown>>(
   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: unknown) => 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);
@@ -290,9 +167,12 @@ const addFormValue = async (form: FormData, key: string, value: unknown): Promis
   // TODO: make nested formats configurable
   if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
     form.append(key, String(value));
-  } else if (isUploadable(value)) {
-    const file = await toFile(value);
-    form.append(key, file as any);
+  } 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') {

package/src/internal/utils/base64.ts

@@ -1,18 +1,19 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { RoarkError } from '../../error';
+import { RoarkError } from '../../core/error';
+import { encodeUTF8 } from './bytes';
 
 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 data === 'string') {
+    data = encodeUTF8(data);
+  }
+
   if (typeof btoa !== 'undefined') {
     return btoa(String.fromCharCode.apply(null, data as any));
   }
@@ -22,15 +23,17 @@ export const toBase64 = (data: string | Uint8Array | null | undefined): string =
 
 export const fromBase64 = (str: string): Uint8Array => {
   if (typeof (globalThis as any).Buffer !== 'undefined') {
-    return new Uint8Array((globalThis as any).Buffer.from(str, 'base64'));
+    const buf = (globalThis as any).Buffer.from(str, 'base64');
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
   }
 
   if (typeof atob !== 'undefined') {
-    return new Uint8Array(
-      atob(str)
-        .split('')
-        .map((c) => c.charCodeAt(0)),
-    );
+    const bstr = atob(str);
+    const buf = new Uint8Array(bstr.length);
+    for (let i = 0; i < bstr.length; i++) {
+      buf[i] = bstr.charCodeAt(i);
+    }
+    return buf;
   }
 
   throw new RoarkError('Cannot decode base64 string; Expected `Buffer` or `atob` to be defined');

package/src/internal/utils/bytes.ts

@@ -0,0 +1,32 @@
+export function concatBytes(buffers: Uint8Array[]): Uint8Array {
+  let length = 0;
+  for (const buffer of buffers) {
+    length += buffer.length;
+  }
+  const output = new Uint8Array(length);
+  let index = 0;
+  for (const buffer of buffers) {
+    output.set(buffer, index);
+    index += buffer.length;
+  }
+
+  return output;
+}
+
+let encodeUTF8_: (str: string) => Uint8Array;
+export function encodeUTF8(str: string) {
+  let encoder;
+  return (
+    encodeUTF8_ ??
+    ((encoder = new (globalThis as any).TextEncoder()), (encodeUTF8_ = encoder.encode.bind(encoder)))
+  )(str);
+}
+
+let decodeUTF8_: (bytes: Uint8Array) => string;
+export function decodeUTF8(bytes: Uint8Array) {
+  let decoder;
+  return (
+    decodeUTF8_ ??
+    ((decoder = new (globalThis as any).TextDecoder()), (decodeUTF8_ = decoder.decode.bind(decoder)))
+  )(bytes);
+}

package/src/internal/utils/log.ts

@@ -1,7 +1,17 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import type { LogLevel, Logger } from '../../client';
+import { hasOwn } from './values';
 import { type Roark } 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,
@@ -11,39 +21,106 @@ const levelNumbers = {
   debug: 500,
 };
 
+export const parseLogLevel = (
+  maybeLevel: string | undefined,
+  sourceName: string,
+  client: Roark,
+): 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 logFn(logger: Logger | undefined, clientLevel: LogLevel | undefined, level: keyof Logger) {
-  if (!logger || levelNumbers[level] > levelNumbers[clientLevel!]!) {
+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[level].bind(logger);
+    return logger[fnLevel].bind(logger);
   }
 }
 
-let lastLogger: { deref(): Logger } | undefined;
-let lastLevel: LogLevel | undefined;
-let lastLevelLogger: Logger;
+const noopLogger = {
+  error: noop,
+  warn: noop,
+  info: noop,
+  debug: noop,
+};
+
+let cachedLoggers = /* @__PURE__ */ new WeakMap<Logger, [LogLevel, Logger]>();
+
+export function loggerFor(client: Roark): Logger {
+  const logger = client.logger;
+  const logLevel = client.logLevel ?? 'off';
+  if (!logger) {
+    return noopLogger;
+  }
 
-export function logger(client: Roark): Logger {
-  let { logger, logLevel: clientLevel } = client;
-  if (lastLevel === clientLevel && (logger === lastLogger || logger === lastLogger?.deref())) {
-    return lastLevelLogger;
+  const cachedLogger = cachedLoggers.get(logger);
+  if (cachedLogger && cachedLogger[0] === logLevel) {
+    return cachedLogger[1];
   }
+
   const levelLogger = {
-    error: logFn(logger, clientLevel, 'error'),
-    warn: logFn(logger, clientLevel, 'warn'),
-    info: logFn(logger, clientLevel, 'info'),
-    debug: logFn(logger, clientLevel, 'debug'),
+    error: makeLogFn('error', logger, logLevel),
+    warn: makeLogFn('warn', logger, logLevel),
+    info: makeLogFn('info', logger, logLevel),
+    debug: makeLogFn('debug', logger, logLevel),
   };
-  const { WeakRef } = globalThis as any;
-  lastLogger =
-    logger ?
-      WeakRef ? new WeakRef(logger)
-      : { deref: () => logger }
-    : undefined;
-  lastLevel = clientLevel;
-  lastLevelLogger = levelLogger;
+
+  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,88 @@
+import { RoarkError } 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);
+}
+
+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;
+      }
+      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 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,
+        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) => {
+        const spaces = ' '.repeat(segment.start - lastEnd);
+        const arrows = '^'.repeat(segment.length);
+        lastEnd = segment.start + segment.length;
+        return acc + spaces + arrows;
+      }, '');
+
+      throw new RoarkError(
+        `Path parameters result in path with invalid segments:\n${invalidSegments
+          .map((e) => e.error)
+          .join('\n')}\n${path}\n${underline}`,
+      );
+    }
+
+    return path;
+  };
+
+/**
+ * URI-encodes path params and ensures no unsafe /./ or /../ path segments are introduced.
+ */
+export const path = /* @__PURE__ */ createPathTagFunction(encodeURIPath);

package/src/internal/utils/uuid.ts

@@ -1,13 +1,17 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { crypto } from '../polyfill/crypto.node';
-
 /**
  * https://stackoverflow.com/a/2117523
  */
-export function uuid4() {
-  if (crypto.randomUUID) return crypto.randomUUID();
+export let uuid4 = function () {
+  const { crypto } = globalThis as any;
+  if (crypto?.randomUUID) {
+    uuid4 = crypto.randomUUID.bind(crypto);
+    return crypto.randomUUID();
+  }
+  const u8 = new Uint8Array(1);
+  const randomByte = crypto ? () => crypto.getRandomValues(u8)[0]! : () => (Math.random() * 0xff) & 0xff;
   return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, (c) =>
-    (+c ^ (crypto.getRandomValues(new Uint8Array(1))[0]! & (15 >> (+c / 4)))).toString(16),
+    (+c ^ (randomByte() & (15 >> (+c / 4)))).toString(16),
   );
-}
+};