@fastpix/fastpix-node 2.0.6 → 2.0.8

package/src/lib/http.ts

@@ -43,13 +43,13 @@ export type RequestErrorHook = (err: unknown, req: Request) => Awaitable<void>;
 export type ResponseHook = (res: Response, req: Request) => Awaitable<void>;
 
 export class HTTPClient {
-  private fetcher: Fetcher;
+  private readonly fetcher: Fetcher;
   private requestHooks: BeforeRequestHook[] = [];
   private requestErrorHooks: RequestErrorHook[] = [];
   private responseHooks: ResponseHook[] = [];
 
-  constructor(private options: HTTPClientOptions = {}) {
-    this.fetcher = options.fetcher || DEFAULT_FETCHER;
+  constructor(private readonly options: HTTPClientOptions = {}) {
+    this.fetcher = options.fetcher ?? DEFAULT_FETCHER;
   }
 
   async request(request: Request): Promise<Response> {
@@ -135,7 +135,7 @@ export class HTTPClient {
       throw new Error(`Invalid hook type: ${args[0]}`);
     }
 
-    const index = target.findIndex((v) => v === args[1]);
+    const index = target.indexOf(args[1]);
     if (index >= 0) {
       target.splice(index, 1);
     }
@@ -156,8 +156,12 @@ export class HTTPClient {
 export type StatusCodePredicate = number | string | (number | string)[];
 
 // A semicolon surrounded by optional whitespace characters is used to separate
-// segments in a media type string.
-const mediaParamSeparator = /\s*;\s*/g;
+// segments in a media type string. Splitting on the literal `;` and trimming
+// each segment avoids the super-linear backtracking of a `/\s*;\s*/` regex while
+// producing identical results for the (already trimmed) inputs used below.
+function splitMediaTypeSegments(value: string): string[] {
+  return value.split(";").map((segment) => segment.trim());
+}
 
 export function matchContentType(response: Response, pattern: string): boolean {
   // `*` is a special case which means anything is acceptable.
@@ -169,14 +173,14 @@ export function matchContentType(response: Response, pattern: string): boolean {
     response.headers.get("content-type")?.trim() || "application/octet-stream";
   contentType = contentType.toLowerCase();
 
-  const wantParts = pattern.toLowerCase().trim().split(mediaParamSeparator);
+  const wantParts = splitMediaTypeSegments(pattern.toLowerCase().trim());
   const [wantType = "", ...wantParams] = wantParts;
 
   if (wantType.split("/").length !== 2) {
     return false;
   }
 
-  const gotParts = contentType.split(mediaParamSeparator);
+  const gotParts = splitMediaTypeSegments(contentType);
   const [gotType = "", ...gotParams] = gotParts;
 
   const [type = "", subtype = ""] = gotType.split("/");
@@ -207,7 +211,7 @@ export function matchContentType(response: Response, pattern: string): boolean {
   return true;
 }
 
-const codeRangeRE = new RegExp("^[0-9]xx$", "i");
+const codeRangeRE = /^\dxx$/i;
 
 export function matchStatusCode(
   response: Response,

package/src/lib/matchers.ts

@@ -181,6 +181,95 @@ export type MatchFunc<T, E> = (
   options?: { resultKey?: string; extraFields?: Record<string, unknown> },
 ) => Promise<[result: Result<T, E>, raw: unknown]>;
 
+function selectMatcher<T, E>(
+  response: Response,
+  matchers: Array<Matcher<T, E>>,
+): Matcher<T, E> | undefined {
+  for (const match of matchers) {
+    const { codes } = match;
+    const ctpattern = "ctype" in match
+      ? match.ctype
+      : DEFAULT_CONTENT_TYPES[match.enc];
+    const matched = ctpattern
+      ? matchResponse(response, codes, ctpattern)
+      : matchStatusCode(response, codes);
+    if (matched) {
+      return match;
+    }
+  }
+  return undefined;
+}
+
+async function decodeResponseBody(
+  encoding: Encoding,
+  response: Response,
+): Promise<{ body: string; raw: unknown }> {
+  let body = "";
+  let raw: unknown;
+  switch (encoding) {
+    case "json":
+      body = await response.text();
+      raw = JSON.parse(body);
+      break;
+    case "jsonl":
+    case "stream":
+    case "sse":
+      raw = response.body;
+      break;
+    case "bytes":
+      raw = new Uint8Array(await response.arrayBuffer());
+      break;
+    case "text":
+    case "fail":
+      body = await response.text();
+      raw = body;
+      break;
+    case "nil":
+      body = await response.text();
+      raw = undefined;
+      break;
+    default:
+      encoding satisfies never;
+      throw new Error(`Unsupported response type: ${encoding}`);
+  }
+  return { body, raw };
+}
+
+function buildResponseData<T, E>(
+  matcher: ValueMatcher<T> | ErrorMatcher<E>,
+  raw: unknown,
+  context: {
+    request: Request;
+    response: Response;
+    body: string;
+    resultKey?: string | undefined;
+    extraFields?: Record<string, unknown> | undefined;
+  },
+): unknown {
+  const { request, response, body, resultKey, extraFields } = context;
+  const headers = matcher.hdrs
+    ? { Headers: unpackHeaders(response.headers) }
+    : null;
+
+  if ("err" in matcher) {
+    return {
+      ...extraFields,
+      ...headers,
+      ...(isPlainObject(raw) ? raw : null),
+      request$: request,
+      response$: response,
+      body$: body,
+    };
+  }
+  if (resultKey) {
+    return { ...extraFields, ...headers, [resultKey]: raw };
+  }
+  if (matcher.hdrs) {
+    return { ...extraFields, ...headers, ...(isPlainObject(raw) ? raw : null) };
+  }
+  return raw;
+}
+
 export function match<T, E>(
   ...matchers: Array<Matcher<T, E>>
 ): MatchFunc<T, E | FastpixDefaultError | ResponseValidationError> {
@@ -194,21 +283,7 @@ export function match<T, E>(
       raw: unknown,
     ]
   > {
-    let raw: unknown;
-    let matcher: Matcher<T, E> | undefined;
-    for (const match of matchers) {
-      const { codes } = match;
-      const ctpattern = "ctype" in match
-        ? match.ctype
-        : DEFAULT_CONTENT_TYPES[match.enc];
-      if (ctpattern && matchResponse(response, codes, ctpattern)) {
-        matcher = match;
-        break;
-      } else if (!ctpattern && matchStatusCode(response, codes)) {
-        matcher = match;
-        break;
-      }
-    }
+    const matcher = selectMatcher(response, matchers);
 
     if (!matcher) {
       return [{
@@ -218,44 +293,10 @@ export function match<T, E>(
           request,
           body: await response.text().catch(() => ""),
         }),
-      }, raw];
+      }, undefined];
     }
 
-    const encoding = matcher.enc;
-    let body = "";
-    switch (encoding) {
-      case "json":
-        body = await response.text();
-        raw = JSON.parse(body);
-        break;
-      case "jsonl":
-        raw = response.body;
-        break;
-      case "bytes":
-        raw = new Uint8Array(await response.arrayBuffer());
-        break;
-      case "stream":
-        raw = response.body;
-        break;
-      case "text":
-        body = await response.text();
-        raw = body;
-        break;
-      case "sse":
-        raw = response.body;
-        break;
-      case "nil":
-        body = await response.text();
-        raw = undefined;
-        break;
-      case "fail":
-        body = await response.text();
-        raw = body;
-        break;
-      default:
-        encoding satisfies never;
-        throw new Error(`Unsupported response type: ${encoding}`);
-    }
+    const { body, raw } = await decodeResponseBody(matcher.enc, response);
 
     if (matcher.enc === "fail") {
       return [{
@@ -268,33 +309,13 @@ export function match<T, E>(
       }, raw];
     }
 
-    const resultKey = matcher.key || options?.resultKey;
-    let data: unknown;
-
-    if ("err" in matcher) {
-      data = {
-        ...options?.extraFields,
-        ...(matcher.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
-        ...(isPlainObject(raw) ? raw : null),
-        request$: request,
-        response$: response,
-        body$: body,
-      };
-    } else if (resultKey) {
-      data = {
-        ...options?.extraFields,
-        ...(matcher.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
-        [resultKey]: raw,
-      };
-    } else if (matcher.hdrs) {
-      data = {
-        ...options?.extraFields,
-        ...(matcher.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
-        ...(isPlainObject(raw) ? raw : null),
-      };
-    } else {
-      data = raw;
-    }
+    const data = buildResponseData(matcher, raw, {
+      request,
+      response,
+      body,
+      resultKey: matcher.key || options?.resultKey,
+      extraFields: options?.extraFields,
+    });
 
     if ("err" in matcher) {
       const result = safeParseResponse(

package/src/lib/primitives.ts

@@ -129,7 +129,7 @@ export function compactMap<T>(
   const out: Record<string, T> = {};
 
   for (const [k, v] of Object.entries(values)) {
-    if (typeof v !== "undefined") {
+    if (v !== undefined) {
       out[k] = v;
     }
   }

package/src/lib/retries.ts

@@ -38,15 +38,16 @@ export class PermanentError extends Error {
 
   constructor(message: string, options?: { cause?: unknown }) {
     let msg = message;
-    if (options?.cause) {
-      msg += `: ${options.cause}`;
+    if (options?.cause != null) {
+      const { cause } = options;
+      msg += `: ${cause instanceof Error ? cause.toString() : JSON.stringify(cause)}`;
     }
 
     super(msg, options);
     this.name = "PermanentError";
     // In older runtimes, the cause field would not have been assigned through
     // the super() call.
-    if (typeof this.cause === "undefined") {
+    if (this.cause === undefined) {
       this.cause = options?.cause;
     }
 
@@ -78,18 +79,16 @@ export async function retry(
     statusCodes: string[];
   },
 ): Promise<Response> {
-  switch (options.config.strategy) {
-    case "backoff":
-      return retryBackoff(
-        wrapFetcher(fetchFn, {
-          statusCodes: options.statusCodes,
-          retryConnectionErrors: !!options.config.retryConnectionErrors,
-        }),
-        options.config.backoff ?? defaultBackoff,
-      );
-    default:
-      return await fetchFn();
+  if (options.config.strategy === "backoff") {
+    return retryBackoff(
+      wrapFetcher(fetchFn, {
+        statusCodes: options.statusCodes,
+        retryConnectionErrors: !!options.config.retryConnectionErrors,
+      }),
+      options.config.backoff ?? defaultBackoff,
+    );
   }
+  return await fetchFn();
 }
 
 function wrapFetcher(
@@ -127,7 +126,7 @@ function wrapFetcher(
   };
 }
 
-const codeRangeRE = new RegExp("^[0-9]xx$", "i");
+const codeRangeRE = /^\dxx$/i;
 
 function isRetryableResponse(res: Response, statusCodes: string[]): boolean {
   const actual = `${res.status}`;
@@ -151,45 +150,66 @@ function isRetryableResponse(res: Response, statusCodes: string[]): boolean {
   });
 }
 
+type RetryDecision =
+  | { kind: "wait"; delay: number }
+  | { kind: "return"; response: Response }
+  | { kind: "throw"; error: unknown };
+
+function nextRetryDecision(
+  err: unknown,
+  elapsed: number,
+  strategy: BackoffStrategy,
+  attempt: number,
+): RetryDecision {
+  if (err instanceof PermanentError) {
+    return { kind: "throw", error: err.cause };
+  }
+
+  if (elapsed > strategy.maxElapsedTime) {
+    return err instanceof TemporaryError
+      ? { kind: "return", response: err.response }
+      : { kind: "throw", error: err };
+  }
+
+  let retryInterval =
+    err instanceof TemporaryError
+      ? retryIntervalFromResponse(err.response)
+      : 0;
+
+  if (retryInterval <= 0) {
+    retryInterval =
+      strategy.initialInterval * Math.pow(attempt, strategy.exponent) +
+      // non-security use: random jitter added to retry backoff to avoid
+      // thundering-herd; cryptographic randomness is unnecessary here.
+      Math.random() * 1000; // NOSONAR(typescript:S2245)
+  }
+
+  return {
+    kind: "wait",
+    delay: Math.min(retryInterval, strategy.maxInterval),
+  };
+}
+
 async function retryBackoff(
   fn: () => Promise<Response>,
   strategy: BackoffStrategy,
 ): Promise<Response> {
-  const { maxElapsedTime, initialInterval, exponent, maxInterval } = strategy;
-
   const start = Date.now();
   let x = 0;
 
   while (true) {
     try {
-      const res = await fn();
-      return res;
+      return await fn();
     } catch (err: unknown) {
-      if (err instanceof PermanentError) {
-        throw err.cause;
+      const decision = nextRetryDecision(err, Date.now() - start, strategy, x);
+      if (decision.kind === "return") {
+        return decision.response;
       }
-      const elapsed = Date.now() - start;
-      if (elapsed > maxElapsedTime) {
-        if (err instanceof TemporaryError) {
-          return err.response;
-        }
-
-        throw err;
+      if (decision.kind === "throw") {
+        throw decision.error;
       }
 
-      let retryInterval = 0;
-      if (err instanceof TemporaryError) {
-        retryInterval = retryIntervalFromResponse(err.response);
-      }
-
-      if (retryInterval <= 0) {
-        retryInterval =
-          initialInterval * Math.pow(x, exponent) + Math.random() * 1000;
-      }
-
-      const d = Math.min(retryInterval, maxInterval);
-
-      await delay(d);
+      await delay(decision.delay);
       x++;
     }
   }

package/src/lib/schemas.ts

@@ -78,7 +78,7 @@ export function collectExtraKeys<
         }
 
         const v = val[key];
-        if (typeof v === "undefined") {
+        if (v === "undefined") {
           continue;
         }
 

package/src/lib/sdks.ts

@@ -77,8 +77,89 @@ const webWorkerLike = typeof gt === "object"
   && "importScripts" in gt
   && typeof gt["importScripts"] === "function";
 const isBrowserLike = webWorkerLike
-  || (typeof navigator !== "undefined" && "serviceWorker" in navigator)
-  || (typeof window === "object" && typeof window.document !== "undefined");
+  || ("navigator" in globalThis && "serviceWorker" in globalThis.navigator)
+  || ("window" in globalThis && "document" in globalThis.window);
+
+/**
+ * Reads the legacy `fetchOptions` field while it remains supported. The local
+ * type intentionally omits the `@deprecated` tag so internal reads don't surface
+ * deprecation warnings; consumers are still steered away from it via the public
+ * {@link RequestOptions} type.
+ */
+function getLegacyFetchOptions(
+  options: RequestOptions | undefined,
+): Omit<RequestInit, "method" | "body"> | undefined {
+  return (
+    options as
+      | { fetchOptions?: Omit<RequestInit, "method" | "body"> }
+      | undefined
+  )?.fetchOptions;
+}
+
+function buildQueryString(
+  query: string | undefined,
+  security: SecurityState | null,
+): string {
+  let finalQuery = query || "";
+
+  const secQuery: string[] = [];
+  for (const [k, v] of Object.entries(security?.queryParams || {})) {
+    const q = encodeForm(k, v, { charEncoding: "percent" });
+    if (q !== undefined) {
+      secQuery.push(q);
+    }
+  }
+  if (secQuery.length) {
+    finalQuery += `&${secQuery.join("&")}`;
+  }
+
+  return finalQuery;
+}
+
+function buildRequestHeaders(
+  conf: RequestConfig,
+  options: RequestOptions | undefined,
+  security: SecurityState | null,
+): Headers {
+  const headers = new Headers(conf.headers);
+
+  const username = security?.basic.username;
+  const password = security?.basic.password;
+  if (username != null || password != null) {
+    const encoded = stringToBase64([username || "", password || ""].join(":"));
+    headers.set("Authorization", `Basic ${encoded}`);
+  }
+
+  const securityHeaders = new Headers(security?.headers || {});
+  for (const [k, v] of securityHeaders) {
+    headers.set(k, v);
+  }
+
+  let cookie = headers.get("cookie") || "";
+  for (const [k, v] of Object.entries(security?.cookies || {})) {
+    cookie += `; ${k}=${v}`;
+  }
+  cookie = cookie.startsWith("; ") ? cookie.slice(2) : cookie;
+  headers.set("cookie", cookie);
+
+  const userHeaders = new Headers(
+    options?.headers ?? getLegacyFetchOptions(options)?.headers,
+  );
+  for (const [k, v] of userHeaders) {
+    headers.set(k, v);
+  }
+
+  // Only set user agent header in non-browser-like environments since CORS
+  // policy disallows setting it in browsers e.g. Chrome throws an error.
+  if (!isBrowserLike) {
+    headers.set(
+      conf.uaHeader ?? "user-agent",
+      conf.userAgent ?? SDK_METADATA.userAgent,
+    );
+  }
+
+  return headers;
+}
 
 export class ClientSDK {
   readonly #httpClient: HTTPClient;
@@ -105,12 +186,27 @@ export class ClientSDK {
 
     const url = serverURLFromOptions(options);
     if (url) {
-      url.pathname = url.pathname.replace(/\/+$/, "") + "/";
+      // Strip trailing slashes with a linear scan (avoids the super-linear
+      // backtracking of a `/\/+$/` regex), then ensure exactly one trailing "/".
+      const pathname = url.pathname;
+      let end = pathname.length;
+      while (end > 0 && pathname.codePointAt(end - 1) === 47 /* "/" */) {
+        end--;
+      }
+      url.pathname = pathname.slice(0, end) + "/";
     }
     this._baseURL = url;
     this.#httpClient = options.httpClient || defaultHttpClient;
 
-    this._options = { ...options, hooks: this.#hooks };
+    this._options = {
+      ...options,
+      // Resolve the webhook signing secret once, preferring an explicit option
+      // and falling back to the FASTPIX_WEBHOOK_SECRET env var. Kept separate
+      // from `security` (the API password) on purpose. Carried forward here so
+      // any cloned options (e.g. per-resource clients) inherit it.
+      webhookSecret: options.webhookSecret ?? env().FASTPIX_WEBHOOK_SECRET ?? null,
+      hooks: this.#hooks,
+    };
 
     this.#logger = this._options.debugLogger;
     if (!this.#logger && env().FASTPIX_DEBUG) {
@@ -123,7 +219,7 @@ export class ClientSDK {
     conf: RequestConfig,
     options?: RequestOptions,
   ): Result<Request, InvalidRequestError | UnexpectedClientError> {
-    const { method, path, query, headers: opHeaders, security } = conf;
+    const { method, path, query, security } = conf;
 
     const base = conf.baseURL ?? this._baseURL;
     if (!base) {
@@ -137,65 +233,16 @@ export class ClientSDK {
       reqURL.pathname += inputURL.pathname.replace(/^\/+/, "");
     }
 
-    let finalQuery = query || "";
-
-    const secQuery: string[] = [];
-    for (const [k, v] of Object.entries(security?.queryParams || {})) {
-      const q = encodeForm(k, v, { charEncoding: "percent" });
-      if (typeof q !== "undefined") {
-        secQuery.push(q);
-      }
-    }
-    if (secQuery.length) {
-      finalQuery += `&${secQuery.join("&")}`;
-    }
-
+    const finalQuery = buildQueryString(query, security ?? null);
     if (finalQuery) {
       const q = finalQuery.startsWith("&") ? finalQuery.slice(1) : finalQuery;
       reqURL.search = `?${q}`;
     }
 
-    const headers = new Headers(opHeaders);
-
-    const username = security?.basic.username;
-    const password = security?.basic.password;
-    if (username != null || password != null) {
-      const encoded = stringToBase64(
-        [username || "", password || ""].join(":"),
-      );
-      headers.set("Authorization", `Basic ${encoded}`);
-    }
-
-    const securityHeaders = new Headers(security?.headers || {});
-    for (const [k, v] of securityHeaders) {
-      headers.set(k, v);
-    }
-
-    let cookie = headers.get("cookie") || "";
-    for (const [k, v] of Object.entries(security?.cookies || {})) {
-      cookie += `; ${k}=${v}`;
-    }
-    cookie = cookie.startsWith("; ") ? cookie.slice(2) : cookie;
-    headers.set("cookie", cookie);
-
-    const userHeaders = new Headers(
-      options?.headers ?? options?.fetchOptions?.headers,
-    );
-    for (const [k, v] of userHeaders) {
-      headers.set(k, v);
-    }
-
-    // Only set user agent header in non-browser-like environments since CORS
-    // policy disallows setting it in browsers e.g. Chrome throws an error.
-    if (!isBrowserLike) {
-      headers.set(
-        conf.uaHeader ?? "user-agent",
-        conf.userAgent ?? SDK_METADATA.userAgent,
-      );
-    }
+    const headers = buildRequestHeaders(conf, options, security ?? null);
 
     const fetchOptions: Omit<RequestInit, "method" | "body"> = {
-      ...options?.fetchOptions,
+      ...getLegacyFetchOptions(options),
       ...options,
     };
     if (!fetchOptions?.signal && conf.timeoutMs && conf.timeoutMs > 0) {
@@ -309,9 +356,12 @@ export class ClientSDK {
   }
 }
 
-const jsonLikeContentTypeRE = /(application|text)\/.*?\+*json.*/;
+// Single greedy `.*` before the literal/word avoids the super-linear
+// backtracking of the previous `.*?\+*…` form while matching the same inputs
+// (these are only used with `.test()`, so the trailing `.*` was redundant).
+const jsonLikeContentTypeRE = /(application|text)\/.*json/;
 const jsonlLikeContentTypeRE =
-  /(application|text)\/(.*?\+*\bjsonl\b.*|.*?\+*\bx-ndjson\b.*)/;
+  /(application|text)\/(.*\bjsonl\b|.*\bx-ndjson\b)/;
 async function logRequest(logger: Logger | undefined, req: Request) {
   if (!logger) {
     return;

package/src/lib/security.ts

@@ -107,7 +107,7 @@ type SecurityInputOAuth2PasswordCredentials = {
 
 type SecurityInputCustom = {
   type: "http:custom";
-  value: any | null | undefined;
+  value: any;
   fieldName?: string;
 };
 
@@ -152,7 +152,7 @@ export function resolveSecurity(
       } else if (typeof o.value === "string") {
         return !!o.value;
       } else {
-        throw new Error(
+        throw new TypeError(
           `Unrecognized security type: ${o.type} (value type: ${typeof o
             .value})`,
         );

package/src/lib/url.ts

@@ -12,7 +12,7 @@ export function pathToFunc(
   pathPattern: string,
   options?: { charEncoding?: "percent" | "none" },
 ): (params?: Params) => string {
-  const paramRE = /\{([a-zA-Z0-9_][a-zA-Z0-9_-]*?)\}/g;
+  const paramRE = /\{(\w[\w-]*?)\}/g;
 
   return function buildURLPath(params: Record<string, unknown> = {}): string {
     return pathPattern.replace(paramRE, function (_, placeholder) {
@@ -22,7 +22,7 @@ export function pathToFunc(
 
       const value = params[placeholder];
       if (typeof value !== "string" && typeof value !== "number") {
-        throw new Error(
+        throw new TypeError(
           `Parameter '${placeholder}' must be a string or number`,
         );
       }