@rainfall-digital/sdk 0.1.2

package/src/lib/matchers.ts

@@ -0,0 +1,352 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { RainfallDefaultError } from "../models/errors/rainfall-default-error.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { ERR, OK, Result } from "../types/fp.js";
+import { matchResponse, matchStatusCode, StatusCodePredicate } from "./http.js";
+import { isPlainObject } from "./is-plain-object.js";
+
+export type Encoding =
+  | "jsonl"
+  | "json"
+  | "text"
+  | "bytes"
+  | "stream"
+  | "sse"
+  | "nil"
+  | "fail";
+
+const DEFAULT_CONTENT_TYPES: Record<Encoding, string> = {
+  jsonl: "application/jsonl",
+  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 jsonl<T>(
+  codes: StatusCodePredicate,
+  schema: Schema<T>,
+  options?: MatchOptions,
+): ValueMatcher<T> {
+  return { ...options, enc: "jsonl", codes, schema };
+}
+
+export function jsonlErr<E>(
+  codes: StatusCodePredicate,
+  schema: Schema<E>,
+  options?: MatchOptions,
+): ErrorMatcher<E> {
+  return { ...options, err: true, enc: "jsonl", 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,
+  request: Request,
+  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 | RainfallDefaultError | ResponseValidationError> {
+  return async function matchFunc(
+    response: Response,
+    request: Request,
+    options?: { resultKey?: string; extraFields?: Record<string, unknown> },
+  ): Promise<
+    [
+      result: Result<T, E | RainfallDefaultError | ResponseValidationError>,
+      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) {
+      return [{
+        ok: false,
+        error: new RainfallDefaultError("Unexpected Status or Content-Type", {
+          response,
+          request,
+          body: await response.text().catch(() => ""),
+        }),
+      }, raw];
+    }
+
+    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}`);
+    }
+
+    if (matcher.enc === "fail") {
+      return [{
+        ok: false,
+        error: new RainfallDefaultError("API error occurred", {
+          request,
+          response,
+          body,
+        }),
+      }, 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;
+    }
+
+    if ("err" in matcher) {
+      const result = safeParseResponse(
+        data,
+        (v: unknown) => matcher.schema.parse(v),
+        "Response validation failed",
+        { request, response, body },
+      );
+      return [result.ok ? { ok: false, error: result.value } : result, raw];
+    } else {
+      return [
+        safeParseResponse(
+          data,
+          (v: unknown) => matcher.schema.parse(v),
+          "Response validation failed",
+          { request, response, body },
+        ),
+        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;
+}
+
+function safeParseResponse<Inp, Out>(
+  rawValue: Inp,
+  fn: (value: Inp) => Out,
+  errorMessage: string,
+  httpMeta: { response: Response; request: Request; body: string },
+): Result<Out, ResponseValidationError> {
+  try {
+    return OK(fn(rawValue));
+  } catch (err) {
+    return ERR(
+      new ResponseValidationError(errorMessage, {
+        cause: err,
+        rawValue,
+        rawMessage: errorMessage,
+        ...httpMeta,
+      }),
+    );
+  }
+}

package/src/lib/primitives.ts

@@ -0,0 +1,150 @@
+/*
+ * 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;
+}
+
+export function combineSignals(
+  ...signals: Array<AbortSignal | null | undefined>
+): AbortSignal | null {
+  const filtered: AbortSignal[] = [];
+  for (const signal of signals) {
+    if (signal) {
+      filtered.push(signal);
+    }
+  }
+
+  switch (filtered.length) {
+    case 0:
+    case 1:
+      return filtered[0] || null;
+    default:
+      if ("any" in AbortSignal && typeof AbortSignal.any === "function") {
+        return AbortSignal.any(filtered);
+      }
+      return abortSignalAny(filtered);
+  }
+}
+
+export function abortSignalAny(signals: AbortSignal[]): AbortSignal {
+  const controller = new AbortController();
+  const result = controller.signal;
+  if (!signals.length) {
+    return controller.signal;
+  }
+
+  if (signals.length === 1) {
+    return signals[0] || controller.signal;
+  }
+
+  for (const signal of signals) {
+    if (signal.aborted) {
+      return signal;
+    }
+  }
+
+  function abort(this: AbortSignal) {
+    controller.abort(this.reason);
+    clean();
+  }
+
+  const signalRefs: WeakRef<AbortSignal>[] = [];
+  function clean() {
+    for (const signalRef of signalRefs) {
+      const signal = signalRef.deref();
+      if (signal) {
+        signal.removeEventListener("abort", abort);
+      }
+    }
+  }
+
+  for (const signal of signals) {
+    signalRefs.push(new WeakRef(signal));
+    signal.addEventListener("abort", abort);
+  }
+
+  return result;
+}
+
+export function compactMap<T>(
+  values: Record<string, T | undefined>,
+): Record<string, T> {
+  const out: Record<string, T> = {};
+
+  for (const [k, v] of Object.entries(values)) {
+    if (typeof v !== "undefined") {
+      out[k] = v;
+    }
+  }
+
+  return out;
+}
+
+export function allRequired<V extends Record<string, unknown>>(
+  v: V,
+):
+  | {
+      [K in keyof V]: NonNullable<V[K]>;
+    }
+  | undefined {
+  if (Object.values(v).every((x) => x == null)) {
+    return void 0;
+  }
+
+  return v as ReturnType<typeof allRequired<V>>;
+}

package/src/lib/retries.ts

@@ -0,0 +1,218 @@
+/*
+ * 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;
+
+  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));
+}