@leonardo-ai/sdk 4.6.0 → 4.14.1

package/src/lib/http.ts

@@ -2,17 +2,40 @@
  * Code generated by Speakeasy (https://speakeasyapi.dev). DO NOT EDIT.
  */
 
-export type Fetcher = (
-  input: RequestInfo | URL,
-  init?: RequestInit,
-) => Promise<Response>;
+import { never as znever } from "zod";
+import { parse } from "./schemas.js";
+import { isPlainObject } from "./is-plain-object.js";
+import { SDKError } from "../sdk/models/errors/sdkerror.js";
+
+export type Fetcher = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
 export type Awaitable<T> = T | Promise<T>;
 
-const DEFAULT_FETCHER: Fetcher = (input, init) => fetch(input, init);
+const DEFAULT_FETCHER: Fetcher = (input, init) => {
+    // If input is a Request and init is undefined, Bun will discard the method,
+    // headers, body and other options that were set on the request object.
+    // Node.js and browers would ignore an undefined init value. This check is
+    // therefore needed for interop with Bun.
+    if (init == null) {
+        return fetch(input);
+    } else {
+        return fetch(input, init);
+    }
+};
+
+export type RequestInput = {
+    /**
+     * The URL the request will use.
+     */
+    url: URL;
+    /**
+     * Options used to create a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request).
+     */
+    options?: RequestInit | undefined;
+};
 
 export interface HTTPClientOptions {
-  fetcher?: Fetcher;
+    fetcher?: Fetcher;
 }
 
 export type BeforeRequestHook = (req: Request) => Awaitable<Request | void>;
@@ -20,196 +43,464 @@ 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 requestHooks: BeforeRequestHook[] = [];
-  private requestErrorHooks: RequestErrorHook[] = [];
-  private responseHooks: ResponseHook[] = [];
-
-  constructor(private options: HTTPClientOptions = {}) {
-    this.fetcher = options.fetcher || DEFAULT_FETCHER;
-  }
-
-  async request(request: Request): Promise<Response> {
-    let req = request;
-    for (const hook of this.requestHooks) {
-      const nextRequest = await hook(req);
-      if (nextRequest) {
-        req = nextRequest;
-      }
+    private fetcher: Fetcher;
+    private requestHooks: BeforeRequestHook[] = [];
+    private requestErrorHooks: RequestErrorHook[] = [];
+    private responseHooks: ResponseHook[] = [];
+
+    constructor(private options: HTTPClientOptions = {}) {
+        this.fetcher = options.fetcher || DEFAULT_FETCHER;
     }
 
-    try {
-      const res = await this.fetcher(req);
+    async request(request: Request): Promise<Response> {
+        let req = request;
+        for (const hook of this.requestHooks) {
+            const nextRequest = await hook(req);
+            if (nextRequest) {
+                req = nextRequest;
+            }
+        }
+
+        try {
+            const res = await this.fetcher(req);
+
+            for (const hook of this.responseHooks) {
+                await hook(res, req);
+            }
+
+            return res;
+        } catch (err) {
+            for (const hook of this.requestErrorHooks) {
+                await hook(err, req);
+            }
+
+            throw err;
+        }
+    }
 
-      for (const hook of this.responseHooks) {
-        await hook(res, req);
-      }
+    /**
+     * Registers a hook that is called before a request is made. The hook function
+     * can mutate the request or return a new request. This may be useful to add
+     * additional information to request such as request IDs and tracing headers.
+     */
+    addHook(hook: "beforeRequest", fn: BeforeRequestHook): this;
+    /**
+     * Registers a hook that is called when a request cannot be made due to a
+     * network error.
+     */
+    addHook(hook: "requestError", fn: RequestErrorHook): this;
+    /**
+     * Registers a hook that is called when a response has been received from the
+     * server.
+     */
+    addHook(hook: "response", fn: ResponseHook): this;
+    addHook(
+        ...args:
+            | [hook: "beforeRequest", fn: BeforeRequestHook]
+            | [hook: "requestError", fn: RequestErrorHook]
+            | [hook: "response", fn: ResponseHook]
+    ) {
+        if (args[0] === "beforeRequest") {
+            this.requestHooks.push(args[1]);
+        } else if (args[0] === "requestError") {
+            this.requestErrorHooks.push(args[1]);
+        } else if (args[0] === "response") {
+            this.responseHooks.push(args[1]);
+        } else {
+            throw new Error(`Invalid hook type: ${args[0]}`);
+        }
+        return this;
+    }
 
-      return res;
-    } catch (err) {
-      for (const hook of this.requestErrorHooks) {
-        await hook(err, req);
-      }
+    /** Removes a hook that was previously registered with `addHook`. */
+    removeHook(hook: "beforeRequest", fn: BeforeRequestHook): this;
+    /** Removes a hook that was previously registered with `addHook`. */
+    removeHook(hook: "requestError", fn: RequestErrorHook): this;
+    /** Removes a hook that was previously registered with `addHook`. */
+    removeHook(hook: "response", fn: ResponseHook): this;
+    removeHook(
+        ...args:
+            | [hook: "beforeRequest", fn: BeforeRequestHook]
+            | [hook: "requestError", fn: RequestErrorHook]
+            | [hook: "response", fn: ResponseHook]
+    ): this {
+        let target: unknown[];
+        if (args[0] === "beforeRequest") {
+            target = this.requestHooks;
+        } else if (args[0] === "requestError") {
+            target = this.requestErrorHooks;
+        } else if (args[0] === "response") {
+            target = this.responseHooks;
+        } else {
+            throw new Error(`Invalid hook type: ${args[0]}`);
+        }
+
+        const index = target.findIndex((v) => v === args[1]);
+        if (index >= 0) {
+            target.splice(index, 1);
+        }
+
+        return this;
+    }
 
-      throw err;
-    }
-  }
-
-  /**
-   * Registers a hook that is called before a request is made. The hook function
-   * can mutate the request or return a new request. This may be useful to add
-   * additional information to request such as request IDs and tracing headers.
-   */
-  addHook(hook: "beforeRequest", fn: BeforeRequestHook): this;
-  /**
-   * Registers a hook that is called when a request cannot be made due to a
-   * network error.
-   */
-  addHook(hook: "requestError", fn: RequestErrorHook): this;
-  /**
-   * Registers a hook that is called when a response has been received from the
-   * server.
-   */
-  addHook(hook: "response", fn: ResponseHook): this;
-  addHook(
-    ...args:
-      | [hook: "beforeRequest", fn: BeforeRequestHook]
-      | [hook: "requestError", fn: RequestErrorHook]
-      | [hook: "response", fn: ResponseHook]
-  ) {
-    if (args[0] === "beforeRequest") {
-      this.requestHooks.push(args[1]);
-    } else if (args[0] === "requestError") {
-      this.requestErrorHooks.push(args[1]);
-    } else if (args[0] === "response") {
-      this.responseHooks.push(args[1]);
-    } else {
-      throw new Error(`Invalid hook type: ${args[0]}`);
-    }
-    return this;
-  }
-
-  /** Removes a hook that was previously registered with `addHook`. */
-  removeHook(hook: "beforeRequest", fn: BeforeRequestHook): this;
-  /** Removes a hook that was previously registered with `addHook`. */
-  removeHook(hook: "requestError", fn: RequestErrorHook): this;
-  /** Removes a hook that was previously registered with `addHook`. */
-  removeHook(hook: "response", fn: ResponseHook): this;
-  removeHook(
-    ...args:
-      | [hook: "beforeRequest", fn: BeforeRequestHook]
-      | [hook: "requestError", fn: RequestErrorHook]
-      | [hook: "response", fn: ResponseHook]
-  ): this {
-    let target: unknown[];
-    if (args[0] === "beforeRequest") {
-      target = this.requestHooks;
-    } else if (args[0] === "requestError") {
-      target = this.requestErrorHooks;
-    } else if (args[0] === "response") {
-      target = this.responseHooks;
-    } else {
-      throw new Error(`Invalid hook type: ${args[0]}`);
+    clone(): HTTPClient {
+        const child = new HTTPClient(this.options);
+        child.requestHooks = this.requestHooks.slice();
+        child.requestErrorHooks = this.requestErrorHooks.slice();
+        child.responseHooks = this.responseHooks.slice();
+
+        return child;
     }
+}
+
+export type StatusCodePredicate = number | string | (number | string)[];
 
-    const index = target.findIndex((v) => v === args[1]);
-    if (index >= 0) {
-      target.splice(index, 1);
+// A semicolon surrounded by optional whitespace characters is used to separate
+// segments in a media type string.
+const mediaParamSeparator = /\s*;\s*/g;
+
+function matchContentType(response: Response, pattern: string): boolean {
+    // `*` is a special case which means anything is acceptable.
+    if (pattern === "*") {
+        return true;
     }
 
-    return this;
-  }
+    let contentType = response.headers.get("content-type")?.trim() || "application/octet-stream";
+    contentType = contentType.toLowerCase();
 
-  clone(): HTTPClient {
-    const child = new HTTPClient(this.options);
-    child.requestHooks = this.requestHooks.slice();
-    child.requestErrorHooks = this.requestErrorHooks.slice();
-    child.responseHooks = this.responseHooks.slice();
+    const wantParts = pattern.toLowerCase().trim().split(mediaParamSeparator);
+    const [wantType = "", ...wantParams] = wantParts;
 
-    return child;
-  }
-}
+    if (wantType.split("/").length !== 2) {
+        return false;
+    }
 
-export function matchContentType(response: Response, pattern: string): boolean {
-  if (pattern === "*" || pattern === "*/*") {
-    return true;
-  }
+    const gotParts = contentType.split(mediaParamSeparator);
+    const [gotType = "", ...gotParams] = gotParts;
 
-  const contentType =
-    response.headers.get("content-type") ?? "application/octet-stream";
+    const [type = "", subtype = ""] = gotType.split("/");
+    if (!type || !subtype) {
+        return false;
+    }
 
-  const idx = contentType.split(";").findIndex((raw) => {
-    const ctype = raw.trim();
-    if (ctype === pattern) {
-      return true;
+    if (
+        wantType !== "*/*" &&
+        gotType !== wantType &&
+        `${type}/*` !== wantType &&
+        `*/${subtype}` !== wantType
+    ) {
+        return false;
     }
 
-    const parts = ctype.split("/");
-    if (parts.length !== 2) {
-      return false;
+    if (gotParams.length < wantParams.length) {
+        return false;
     }
 
-    return `${parts[0]}/*` === pattern || `*/${parts[1]}` === pattern;
-  });
+    const params = new Set(gotParams);
+    for (const wantParam of wantParams) {
+        if (!params.has(wantParam)) {
+            return false;
+        }
+    }
 
-  return idx >= 0;
+    return true;
 }
 
 const codeRangeRE = new RegExp("^[0-9]xx$", "i");
 
-export function matchStatusCode(
-  response: Response,
-  codes: number | string | (number | string)[],
-): boolean {
-  const actual = `${response.status}`;
-  const expectedCodes = Array.isArray(codes) ? codes : [codes];
-  if (!expectedCodes.length) {
-    return false;
-  }
+export function matchStatusCode(response: Response, codes: StatusCodePredicate): boolean {
+    const actual = `${response.status}`;
+    const expectedCodes = Array.isArray(codes) ? codes : [codes];
+    if (!expectedCodes.length) {
+        return false;
+    }
 
-  return expectedCodes.some((ec) => {
-    const code = `${ec}`;
+    return expectedCodes.some((ec) => {
+        const code = `${ec}`;
 
-    if (code === "default") {
-      return true;
-    }
+        if (code === "default") {
+            return true;
+        }
 
-    if (!codeRangeRE.test(`${code}`)) {
-      return code === actual;
-    }
+        if (!codeRangeRE.test(`${code}`)) {
+            return code === actual;
+        }
 
-    const expectFamily = code.charAt(0);
-    if (!expectFamily) {
-      throw new Error("Invalid status code range");
-    }
+        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}`);
-    }
+        const actualFamily = actual.charAt(0);
+        if (!actualFamily) {
+            throw new Error(`Invalid response status code: ${actual}`);
+        }
 
-    return actualFamily === expectFamily;
-  });
+        return actualFamily === expectFamily;
+    });
 }
 
 export function matchResponse(
-  response: Response,
-  code: number | string | (number | string)[],
-  contentTypePattern: string,
+    response: Response,
+    code: StatusCodePredicate,
+    contentTypePattern: string
 ): boolean {
-  return (
-    matchStatusCode(response, code) &&
-    matchContentType(response, contentTypePattern)
-  );
+    return matchStatusCode(response, code) && matchContentType(response, contentTypePattern);
 }
 
 const headerValRE = /, */;
 export function unpackHeaders(headers: Headers): Record<string, string[]> {
-  const out: Record<string, string[]> = {};
+    const out: Record<string, string[]> = {};
+
+    for (const [k, v] of headers.entries()) {
+        out[k] = v.split(headerValRE);
+    }
+
+    return out;
+}
+
+type ResponseMatcherSchema<T> =
+    | { parse: (data: unknown) => T }
+    | { inboundSchema: { parse: (data: unknown) => T } };
+
+type SerializationMethod = "sse" | "json" | "rawBytes" | "rawStream" | "text" | "void" | "fail";
+
+const defaultContentTypes: Record<SerializationMethod, string> = {
+    sse: "text/event-stream",
+    json: "application/json",
+    rawBytes: "application/octet-stream",
+    rawStream: "application/octet-stream",
+    text: "text/plain",
+    void: "",
+    fail: "",
+};
+
+type ResponsePredicateMatch<Result> = {
+    method: SerializationMethod;
+    codes: StatusCodePredicate;
+    ctype: string;
+    schema: ResponseMatcherSchema<Result | Error>;
+    hdrs: boolean;
+    key: string | undefined;
+    err: boolean;
+    fail: boolean;
+    sseSentinel?: string | undefined;
+};
+
+type ResponsePredicateOptions = {
+    /** Content type to match on. */
+    ctype?: string;
+    /** Pass HTTP headers to deserializer. */
+    hdrs?: boolean;
+    /** A value for an SSE event's data field that indicates a stream should be terminated. */
+    sseSentinel?: string;
+} & (
+    | {
+          /** The result key to store the deserialized value into. */
+          key?: string;
+          fail?: never;
+          err?: never;
+      }
+    | {
+          /** Indicates the matched response must throw the built-in error. */
+          fail: true;
+          key?: never;
+          err?: never;
+      }
+    | {
+          /** Indicates the matched response is a custom error. */
+          err: true;
+          key?: never;
+          fail?: never;
+      }
+);
+
+export class ResponseMatcher<Result> {
+    private predicates: ResponsePredicateMatch<Result>[] = [];
+
+    #any<T extends Result | Error>(
+        method: SerializationMethod,
+        codes: StatusCodePredicate,
+        schema: ResponseMatcherSchema<T>,
+        opts?: ResponsePredicateOptions
+    ) {
+        const ctype = opts?.ctype || defaultContentTypes[method];
+        const hdrs = !!opts?.hdrs;
+        const key = opts?.key;
+        const err = !!opts?.err;
+        const fail = !!opts?.fail;
+        const sseSentinel = opts?.sseSentinel;
+        this.predicates.push({
+            method,
+            codes,
+            ctype,
+            schema,
+            hdrs,
+            key,
+            err,
+            fail,
+            sseSentinel,
+        });
+        return this;
+    }
+
+    json<T extends Result | Error>(
+        codes: StatusCodePredicate,
+        schema: ResponseMatcherSchema<T>,
+        opts?: ResponsePredicateOptions
+    ): this {
+        return this.#any("json", codes, schema, opts);
+    }
+    bytes<T extends Result | Error>(
+        codes: StatusCodePredicate,
+        schema: ResponseMatcherSchema<T>,
+        opts?: ResponsePredicateOptions
+    ): this {
+        return this.#any("rawBytes", codes, schema, opts);
+    }
+    stream<T extends Result | Error>(
+        codes: StatusCodePredicate,
+        schema: ResponseMatcherSchema<T>,
+        opts?: ResponsePredicateOptions
+    ): this {
+        return this.#any("rawStream", codes, schema, opts);
+    }
+    text<T extends Result | Error>(
+        codes: StatusCodePredicate,
+        schema: ResponseMatcherSchema<T>,
+        opts?: ResponsePredicateOptions
+    ): this {
+        return this.#any("text", codes, schema, opts);
+    }
+    sse<T extends Result | Error>(
+        codes: StatusCodePredicate,
+        schema: ResponseMatcherSchema<T>,
+        opts?: Omit<ResponsePredicateOptions, "err" | "fail">
+    ): this {
+        return this.#any("sse", codes, schema, opts);
+    }
+    void<T extends Result | Error>(
+        codes: StatusCodePredicate,
+        schema: ResponseMatcherSchema<T>,
+        opts?: Pick<ResponsePredicateOptions, "hdrs">
+    ): this {
+        return this.#any("void", codes, schema, opts);
+    }
+    fail(codes: StatusCodePredicate): this {
+        return this.#any("fail", codes, znever(), { fail: true });
+    }
 
-  for (const [k, v] of headers.entries()) {
-    out[k] = v.split(headerValRE);
-  }
+    async match(
+        response: Response,
+        // envelope
+        options?: {
+            resultKey?: string;
+            extraFields?: Record<string, unknown>;
+        }
+    ): Promise<[result: Result, rawData: unknown]> {
+        let pred: ResponsePredicateMatch<Result> | undefined;
+        for (const predicate of this.predicates) {
+            const { codes, ctype } = predicate;
+            if (ctype && matchResponse(response, codes, ctype)) {
+                pred = predicate;
+                break;
+            } else if (!ctype && matchStatusCode(response, codes)) {
+                pred = predicate;
+                break;
+            }
+        }
+        if (pred == null) {
+            const responseBody = await response.text();
+            throw new SDKError(
+                "Unexpected API response status or content-type",
+                response,
+                responseBody
+            );
+        }
+
+        const { method, schema } = pred;
+
+        let raw: unknown;
+        switch (method) {
+            case "json":
+                raw = await response.json();
+                break;
+            case "rawBytes":
+                raw = await response.arrayBuffer();
+                break;
+            case "rawStream":
+                raw = response.body;
+                break;
+            case "text":
+                raw = await response.text();
+                break;
+            case "sse":
+                raw = response.body;
+                break;
+            case "void":
+                raw = await discardResponseBody(response);
+                break;
+            case "fail":
+                raw = await response.text();
+                break;
+            default:
+                method satisfies never;
+                throw new Error(`Unsupported response type: ${method}`);
+        }
+
+        const resultKey = pred.key || options?.resultKey;
+        let data: unknown;
+        if (pred.fail) {
+            throw new SDKError("API error occurred", response, typeof raw === "string" ? raw : "");
+        } else if (pred.err) {
+            data = {
+                ...options?.extraFields,
+                ...(pred.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
+                ...(isPlainObject(raw) ? raw : null),
+            };
+        } else if (resultKey) {
+            data = {
+                ...options?.extraFields,
+                ...(pred.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
+                [resultKey]: raw,
+            };
+        } else {
+            data = {
+                ...options?.extraFields,
+                ...(pred.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
+            };
+        }
+
+        const parser = "inboundSchema" in schema ? schema.inboundSchema : schema;
+        const body = parse(data, (v: unknown) => parser.parse(v), "Response validation failed");
+
+        if (body instanceof Error) {
+            throw body;
+        }
+
+        return [body, raw];
+    }
+}
+
+/**
+ * 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;
+    }
 
-  return out;
+    try {
+        let done = false;
+        while (!done) {
+            const res = await reader.read();
+            done = res.done;
+        }
+    } finally {
+        reader.releaseLock();
+    }
 }