@vercel/sdk 1.0.0-canary.10

package/src/lib/matchers.ts

@@ -0,0 +1,322 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SDKError } from "../models/errors/sdkerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { Result } from "../types/fp.js";
+import { matchResponse, matchStatusCode, StatusCodePredicate } from "./http.js";
+import { isPlainObject } from "./is-plain-object.js";
+import { safeParse } from "./schemas.js";
+
+export type Encoding =
+  | "json"
+  | "text"
+  | "bytes"
+  | "stream"
+  | "sse"
+  | "nil"
+  | "fail";
+
+const DEFAULT_CONTENT_TYPES: Record<Encoding, string> = {
+  json: "application/json",
+  text: "text/plain",
+  bytes: "application/octet-stream",
+  stream: "application/octet-stream",
+  sse: "text/event-stream",
+  nil: "*",
+  fail: "*",
+};
+
+type Schema<T> = { parse(raw: unknown): T };
+
+type MatchOptions = {
+  ctype?: string;
+  hdrs?: boolean;
+  key?: string;
+  sseSentinel?: string;
+};
+
+export type ValueMatcher<V> = MatchOptions & {
+  enc: Encoding;
+  codes: StatusCodePredicate;
+  schema: Schema<V>;
+};
+
+export type ErrorMatcher<E> = MatchOptions & {
+  enc: Encoding;
+  codes: StatusCodePredicate;
+  schema: Schema<E>;
+  err: true;
+};
+
+export type FailMatcher = {
+  enc: "fail";
+  codes: StatusCodePredicate;
+};
+
+export type Matcher<T, E> = ValueMatcher<T> | ErrorMatcher<E> | FailMatcher;
+
+export function jsonErr<E>(
+  codes: StatusCodePredicate,
+  schema: Schema<E>,
+  options?: MatchOptions,
+): ErrorMatcher<E> {
+  return { ...options, err: true, enc: "json", codes, schema };
+}
+export function json<T>(
+  codes: StatusCodePredicate,
+  schema: Schema<T>,
+  options?: MatchOptions,
+): ValueMatcher<T> {
+  return { ...options, enc: "json", codes, schema };
+}
+
+export function textErr<E>(
+  codes: StatusCodePredicate,
+  schema: Schema<E>,
+  options?: MatchOptions,
+): ErrorMatcher<E> {
+  return { ...options, err: true, enc: "text", codes, schema };
+}
+export function text<T>(
+  codes: StatusCodePredicate,
+  schema: Schema<T>,
+  options?: MatchOptions,
+): ValueMatcher<T> {
+  return { ...options, enc: "text", codes, schema };
+}
+
+export function bytesErr<E>(
+  codes: StatusCodePredicate,
+  schema: Schema<E>,
+  options?: MatchOptions,
+): ErrorMatcher<E> {
+  return { ...options, err: true, enc: "bytes", codes, schema };
+}
+export function bytes<T>(
+  codes: StatusCodePredicate,
+  schema: Schema<T>,
+  options?: MatchOptions,
+): ValueMatcher<T> {
+  return { ...options, enc: "bytes", codes, schema };
+}
+
+export function streamErr<E>(
+  codes: StatusCodePredicate,
+  schema: Schema<E>,
+  options?: MatchOptions,
+): ErrorMatcher<E> {
+  return { ...options, err: true, enc: "stream", codes, schema };
+}
+export function stream<T>(
+  codes: StatusCodePredicate,
+  schema: Schema<T>,
+  options?: MatchOptions,
+): ValueMatcher<T> {
+  return { ...options, enc: "stream", codes, schema };
+}
+
+export function sseErr<E>(
+  codes: StatusCodePredicate,
+  schema: Schema<E>,
+  options?: MatchOptions,
+): ErrorMatcher<E> {
+  return { ...options, err: true, enc: "sse", codes, schema };
+}
+export function sse<T>(
+  codes: StatusCodePredicate,
+  schema: Schema<T>,
+  options?: MatchOptions,
+): ValueMatcher<T> {
+  return { ...options, enc: "sse", codes, schema };
+}
+
+export function nilErr<E>(
+  codes: StatusCodePredicate,
+  schema: Schema<E>,
+  options?: MatchOptions,
+): ErrorMatcher<E> {
+  return { ...options, err: true, enc: "nil", codes, schema };
+}
+export function nil<T>(
+  codes: StatusCodePredicate,
+  schema: Schema<T>,
+  options?: MatchOptions,
+): ValueMatcher<T> {
+  return { ...options, enc: "nil", codes, schema };
+}
+
+export function fail(codes: StatusCodePredicate): FailMatcher {
+  return { enc: "fail", codes };
+}
+
+export type MatchedValue<Matchers> = Matchers extends Matcher<infer T, any>[]
+  ? T
+  : never;
+export type MatchedError<Matchers> = Matchers extends Matcher<any, infer E>[]
+  ? E
+  : never;
+export type MatchFunc<T, E> = (
+  response: Response,
+  options?: { resultKey?: string; extraFields?: Record<string, unknown> },
+) => Promise<[result: Result<T, E>, raw: unknown]>;
+
+export function match<T, E>(
+  ...matchers: Array<Matcher<T, E>>
+): MatchFunc<T, E | SDKError | SDKValidationError> {
+  return async function matchFunc(
+    response: Response,
+    options?: { resultKey?: string; extraFields?: Record<string, unknown> },
+  ): Promise<
+    [result: Result<T, E | SDKError | SDKValidationError>, 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;
+      }
+    }
+
+    if (!matcher) {
+      const responseBody = await response.text();
+      return [{
+        ok: false,
+        error: new SDKError(
+          "Unexpected API response status or content-type",
+          response,
+          responseBody,
+        ),
+      }, responseBody];
+    }
+
+    const encoding = matcher.enc;
+    switch (encoding) {
+      case "json":
+        raw = await response.json();
+        break;
+      case "bytes":
+        raw = new Uint8Array(await response.arrayBuffer());
+        break;
+      case "stream":
+        raw = response.body;
+        break;
+      case "text":
+        raw = await response.text();
+        break;
+      case "sse":
+        raw = response.body;
+        break;
+      case "nil":
+        raw = await discardResponseBody(response);
+        break;
+      case "fail":
+        raw = await response.text();
+        break;
+      default:
+        encoding satisfies never;
+        throw new Error(`Unsupported response type: ${encoding}`);
+    }
+
+    if (matcher.enc === "fail") {
+      return [{
+        ok: false,
+        error: new SDKError(
+          "API error occurred",
+          response,
+          typeof raw === "string" ? raw : "",
+        ),
+      }, 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),
+      };
+    } 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;
+    }
+
+    if ("err" in matcher) {
+      const result = safeParse(
+        data,
+        (v: unknown) => matcher.schema.parse(v),
+        "Response validation failed",
+      );
+      return [result.ok ? { ok: false, error: result.value } : result, raw];
+    } else {
+      return [
+        safeParse(
+          data,
+          (v: unknown) => matcher.schema.parse(v),
+          "Response validation failed",
+        ),
+        raw,
+      ];
+    }
+  };
+}
+
+const headerValRE = /, */;
+/**
+ * Iterates over a Headers object and returns an object with all the header
+ * entries. Values are represented as an array to account for repeated headers.
+ */
+export function unpackHeaders(headers: Headers): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+
+  for (const [k, v] of headers.entries()) {
+    out[k] = v.split(headerValRE);
+  }
+
+  return out;
+}
+
+/**
+ * Discards the response body to free up resources.
+ *
+ * To learn why this is need, see the undici docs:
+ * https://undici.nodejs.org/#/?id=garbage-collection
+ */
+export async function discardResponseBody(res: Response) {
+  const reader = res.body?.getReader();
+  if (reader == null) {
+    return;
+  }
+
+  try {
+    let done = false;
+    while (!done) {
+      const res = await reader.read();
+      done = res.done;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/lib/primitives.ts

@@ -0,0 +1,60 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+class InvariantError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvariantError";
+  }
+}
+
+export function invariant(
+  condition: unknown,
+  message: string,
+): asserts condition {
+  if (!condition) {
+    throw new InvariantError(message);
+  }
+}
+
+export type ExactPartial<T> = {
+  [P in keyof T]?: T[P] | undefined;
+};
+
+export type Remap<Inp, Mapping extends { [k in keyof Inp]?: string | null }> = {
+  [k in keyof Inp as Mapping[k] extends string /* if we have a string mapping for this key then use it */
+    ? Mapping[k]
+    : Mapping[k] extends null /* if the mapping is to `null` then drop the key */
+    ? never
+    : k /* otherwise keep the key as-is */]: Inp[k];
+};
+
+/**
+ * Converts or omits an object's keys according to a mapping.
+ *
+ * @param inp An object whose keys will be remapped
+ * @param mappings A mapping of original keys to new keys. If a key is not present in the mapping, it will be left as is. If a key is mapped to `null`, it will be removed in the resulting object.
+ * @returns A new object with keys remapped or omitted according to the mappings
+ */
+export function remap<
+  Inp extends Record<string, unknown>,
+  const Mapping extends { [k in keyof Inp]?: string | null },
+>(inp: Inp, mappings: Mapping): Remap<Inp, Mapping> {
+  let out: any = {};
+
+  if (!Object.keys(mappings).length) {
+    out = inp;
+    return out;
+  }
+
+  for (const [k, v] of Object.entries(inp)) {
+    const j = mappings[k];
+    if (j === null) {
+      continue;
+    }
+    out[j ?? k] = v;
+  }
+
+  return out;
+}

package/src/lib/retries.ts

@@ -0,0 +1,219 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { isConnectionError, isTimeoutError } from "./http.js";
+
+export type BackoffStrategy = {
+  initialInterval: number;
+  maxInterval: number;
+  exponent: number;
+  maxElapsedTime: number;
+};
+
+const defaultBackoff: BackoffStrategy = {
+  initialInterval: 500,
+  maxInterval: 60000,
+  exponent: 1.5,
+  maxElapsedTime: 3600000,
+};
+
+export type RetryConfig =
+  | { strategy: "none" }
+  | {
+      strategy: "backoff";
+      backoff?: BackoffStrategy;
+      retryConnectionErrors?: boolean;
+    };
+
+/**
+ * PermanentError is an error that is not recoverable. Throwing this error will
+ * cause a retry loop to terminate.
+ */
+export class PermanentError extends Error {
+  /** The underlying cause of the error. */
+  override readonly cause: unknown;
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    let msg = message;
+    if (options?.cause) {
+      msg += `: ${options.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") {
+      this.cause = options?.cause;
+    }
+
+    Object.setPrototypeOf(this, PermanentError.prototype);
+  }
+}
+
+/**
+ * TemporaryError is an error is used to signal that an HTTP request can be
+ * retried as part of a retry loop. If retry attempts are exhausted and this
+ * error is thrown, the response will be returned to the caller.
+ */
+export class TemporaryError extends Error {
+  response: Response;
+
+  constructor(message: string, response: Response) {
+    super(message);
+    this.response = response;
+    this.name = "TemporaryError";
+
+    Object.setPrototypeOf(this, TemporaryError.prototype);
+  }
+}
+
+export async function retry(
+  fetchFn: () => Promise<Response>,
+  options: {
+    config: RetryConfig;
+    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();
+  }
+}
+
+function wrapFetcher(
+  fn: () => Promise<Response>,
+  options: {
+    statusCodes: string[];
+    retryConnectionErrors: boolean;
+  },
+): () => Promise<Response> {
+  return async () => {
+    try {
+      const res = await fn();
+      if (isRetryableResponse(res, options.statusCodes)) {
+        throw new TemporaryError(
+          "Response failed with retryable status code",
+          res,
+        );
+      }
+
+      return res;
+    } catch (err: unknown) {
+      if (err instanceof TemporaryError) {
+        throw err;
+      }
+
+      if (
+        options.retryConnectionErrors &&
+        (isTimeoutError(err) || isConnectionError(err))
+      ) {
+        throw err;
+      }
+
+      throw new PermanentError("Permanent error", { cause: err });
+    }
+  };
+}
+
+const codeRangeRE = new RegExp("^[0-9]xx$", "i");
+
+function isRetryableResponse(res: Response, statusCodes: string[]): boolean {
+  const actual = `${res.status}`;
+
+  return statusCodes.some((code) => {
+    if (!codeRangeRE.test(code)) {
+      return code === actual;
+    }
+
+    const expectFamily = code.charAt(0);
+    if (!expectFamily) {
+      throw new Error("Invalid status code range");
+    }
+
+    const actualFamily = actual.charAt(0);
+    if (!actualFamily) {
+      throw new Error(`Invalid response status code: ${actual}`);
+    }
+
+    return actualFamily === expectFamily;
+  });
+}
+
+async function retryBackoff(
+  fn: () => Promise<Response>,
+  strategy: BackoffStrategy,
+): Promise<Response> {
+  const { maxElapsedTime, initialInterval, exponent, maxInterval } = strategy;
+
+  const start = Date.now();
+  let x = 0;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      const res = await fn();
+      return res;
+    } catch (err: unknown) {
+      if (err instanceof PermanentError) {
+        throw err.cause;
+      }
+      const elapsed = Date.now() - start;
+      if (elapsed > maxElapsedTime) {
+        if (err instanceof TemporaryError) {
+          return err.response;
+        }
+
+        throw err;
+      }
+
+      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);
+      x++;
+    }
+  }
+}
+
+function retryIntervalFromResponse(res: Response): number {
+  const retryVal = res.headers.get("retry-after") || "";
+  if (!retryVal) {
+    return 0;
+  }
+
+  const parsedNumber = Number(retryVal);
+  if (Number.isInteger(parsedNumber)) {
+    return parsedNumber * 1000;
+  }
+
+  const parsedDate = Date.parse(retryVal);
+  if (Number.isInteger(parsedDate)) {
+    const deltaMS = parsedDate - Date.now();
+    return deltaMS > 0 ? Math.ceil(deltaMS) : 0;
+  }
+
+  return 0;
+}
+
+async function delay(delay: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, delay));
+}

package/src/lib/schemas.ts

@@ -0,0 +1,86 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import {
+  output,
+  ZodEffects,
+  ZodError,
+  ZodObject,
+  ZodRawShape,
+  ZodTypeAny,
+} from "zod";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { ERR, OK, Result } from "../types/fp.js";
+
+/**
+ * Utility function that executes some code which may throw a ZodError. It
+ * intercepts this error and converts it to an SDKValidationError so as to not
+ * leak Zod implementation details to user code.
+ */
+export function parse<Inp, Out>(
+  rawValue: Inp,
+  fn: (value: Inp) => Out,
+  errorMessage: string,
+): Out {
+  try {
+    return fn(rawValue);
+  } catch (err) {
+    if (err instanceof ZodError) {
+      throw new SDKValidationError(errorMessage, err, rawValue);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Utility function that executes some code which may result in a ZodError. It
+ * intercepts this error and converts it to an SDKValidationError so as to not
+ * leak Zod implementation details to user code.
+ */
+export function safeParse<Inp, Out>(
+  rawValue: Inp,
+  fn: (value: Inp) => Out,
+  errorMessage: string,
+): Result<Out, SDKValidationError> {
+  try {
+    return OK(fn(rawValue));
+  } catch (err) {
+    return ERR(new SDKValidationError(errorMessage, err, rawValue));
+  }
+}
+
+export function collectExtraKeys<
+  Shape extends ZodRawShape,
+  Catchall extends ZodTypeAny,
+  K extends string,
+>(
+  obj: ZodObject<Shape, "strip", Catchall>,
+  extrasKey: K,
+): ZodEffects<
+  typeof obj,
+  & output<ZodObject<Shape, "strict">>
+  & {
+    [k in K]: Record<string, output<Catchall>>;
+  }
+> {
+  return obj.transform((val) => {
+    const extras: Record<string, output<Catchall>> = {};
+    const { shape } = obj;
+    for (const [key] of Object.entries(val)) {
+      if (key in shape) {
+        continue;
+      }
+
+      const v = val[key];
+      if (typeof v === "undefined") {
+        continue;
+      }
+
+      extras[key] = v;
+      delete val[key];
+    }
+
+    return { ...val, [extrasKey]: extras };
+  });
+}