dub 0.35.0 → 0.36.0

package/src/lib/logger.ts

@@ -0,0 +1,9 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export interface Logger {
+  group(label?: string): void;
+  groupEnd(): void;
+  log(message: any, ...args: any[]): void;
+}

package/src/lib/matchers.ts

@@ -0,0 +1,308 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { safeParse } from "./schemas.js";
+import { StatusCodePredicate, matchResponse, matchStatusCode } from "./http.js";
+import { isPlainObject } from "./is-plain-object.js";
+import { SDKError } from "../models/errors/sdkerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { Result } from "../types/fp.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 = 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/retries.ts

@@ -2,6 +2,8 @@
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
 
+import { isConnectionError, isTimeoutError } from "./http.js";
+
 export type BackoffStrategy = {
   initialInterval: number;
   maxInterval: number;
@@ -99,47 +101,6 @@ function wrapFetcher(
   };
 }
 
-function isConnectionError(err: unknown) {
-  if (typeof err !== "object" || err == null) {
-    return false;
-  }
-
-  // Covers fetch in Deno as well
-  const isBrowserErr =
-    err instanceof TypeError &&
-    err.message.toLowerCase().startsWith("failed to fetch");
-
-  const isNodeErr =
-    err instanceof TypeError &&
-    err.message.toLowerCase().startsWith("fetch failed");
-
-  const isBunErr = "name" in err && err.name === "ConnectionError";
-
-  const isGenericErr =
-    "code" in err &&
-    typeof err.code === "string" &&
-    err.code.toLowerCase() === "econnreset";
-
-  return isBrowserErr || isNodeErr || isGenericErr || isBunErr;
-}
-
-function isTimeoutError(err: unknown) {
-  if (typeof err !== "object" || err == null) {
-    return false;
-  }
-
-  // Fetch in browser, Node.js, Bun, Deno
-  const isNative = "name" in err && err.name === "TimeoutError";
-
-  // Node.js HTTP client and Axios
-  const isGenericErr =
-    "code" in err &&
-    typeof err.code === "string" &&
-    err.code.toLowerCase() === "econnaborted";
-
-  return isNative || isGenericErr;
-}
-
 const codeRangeRE = new RegExp("^[0-9]xx$", "i");
 
 function isRetryableResponse(res: Response, statusCodes: string[]): boolean {

package/src/lib/schemas.ts

@@ -4,6 +4,7 @@
 
 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
@@ -21,6 +22,23 @@ export function parse<Inp, Out>(rawValue: Inp, fn: (value: Inp) => Out, errorMes
     }
 }
 
+/**
+ * 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,

package/src/lib/sdks.ts

@@ -2,15 +2,30 @@
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
 
-import { ResponseMatcher, HTTPClient, matchStatusCode } from "./http.js";
-import { SecurityState, resolveSecurity, resolveGlobalSecurity } from "./security.js";
+import {
+    HTTPClient,
+    matchContentType,
+    matchStatusCode,
+    isAbortError,
+    isTimeoutError,
+    isConnectionError,
+} from "./http.js";
+import { SecurityState } from "./security.js";
 import { retry, RetryConfig } from "./retries.js";
-import { pathToFunc } from "./url.js";
+import { Logger } from "./logger.js";
 import { encodeForm } from "./encodings.js";
 import { stringToBase64 } from "./base64.js";
-import { SDK_METADATA } from "./config.js";
+import { SDKOptions, SDK_METADATA, serverURLFromOptions } from "./config.js";
 import { SDKHooks } from "../hooks/hooks.js";
 import { HookContext } from "../hooks/types.js";
+import {
+    ConnectionError,
+    InvalidRequestError,
+    RequestAbortedError,
+    RequestTimeoutError,
+    UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { ERR, OK, Result } from "../types/fp.js";
 
 export type RequestOptions = {
     /**
@@ -58,32 +73,49 @@ const isBrowserLike =
     (typeof window === "object" && typeof window.document !== "undefined");
 
 export class ClientSDK {
-    private readonly client: HTTPClient;
+    private readonly httpClient: HTTPClient;
     protected readonly baseURL: URL | null;
     protected readonly hooks$: SDKHooks;
+    protected readonly logger?: Logger | undefined;
+    public readonly options$: SDKOptions & { hooks?: SDKHooks };
 
-    constructor(init: { client: HTTPClient; baseURL: URL | null; hooks: SDKHooks }) {
-        const url = init.baseURL;
+    constructor(options: SDKOptions = {}) {
+        const opt = options as unknown;
+        if (
+            typeof opt === "object" &&
+            opt != null &&
+            "hooks" in opt &&
+            opt.hooks instanceof SDKHooks
+        ) {
+            this.hooks$ = opt.hooks;
+        } else {
+            this.hooks$ = new SDKHooks();
+        }
+        this.options$ = { ...options, hooks: this.hooks$ };
+
+        const url = serverURLFromOptions(options);
         if (url) {
             url.pathname = url.pathname.replace(/\/+$/, "") + "/";
         }
-
-        this.hooks$ = init.hooks;
-        const { baseURL, client } = this.hooks$.sdkInit({ baseURL: url, client: init.client });
+        const { baseURL, client } = this.hooks$.sdkInit({
+            baseURL: url,
+            client: options.httpClient || new HTTPClient(),
+        });
         this.baseURL = baseURL;
-        this.client = client;
+        this.httpClient = client;
+        this.logger = options.debugLogger;
     }
 
-    protected createRequest$(
+    public createRequest$(
         context: HookContext,
         conf: RequestConfig,
         options?: RequestOptions
-    ): Request {
+    ): Result<Request, InvalidRequestError | UnexpectedClientError> {
         const { method, path, query, headers: opHeaders, security } = conf;
 
         const base = conf.baseURL ?? this.baseURL;
         if (!base) {
-            throw new TypeError("No base URL provided for operation");
+            return ERR(new InvalidRequestError("No base URL provided for operation"));
         }
         const reqURL = new URL(base);
         const inputURL = new URL(path, reqURL);
@@ -149,20 +181,27 @@ export class ClientSDK {
             }
         }
 
-        const input = this.hooks$.beforeCreateRequest(context, {
-            url: reqURL,
-            options: {
-                ...fetchOptions,
-                body: conf.body ?? null,
-                headers,
-                method,
-            },
-        });
+        let input;
+        try {
+            input = this.hooks$.beforeCreateRequest(context, {
+                url: reqURL,
+                options: {
+                    ...fetchOptions,
+                    body: conf.body ?? null,
+                    headers,
+                    method,
+                },
+            });
+        } catch (err: unknown) {
+            return ERR(
+                new UnexpectedClientError("Create request hook failed to execute", { cause: err })
+            );
+        }
 
-        return new Request(input.url, input.options);
+        return OK(new Request(input.url, input.options));
     }
 
-    protected async do$(
+    public async do$(
         request: Request,
         options: {
             context: HookContext;
@@ -170,19 +209,25 @@ export class ClientSDK {
             retryConfig?: RetryConfig | undefined;
             retryCodes?: string[] | undefined;
         }
-    ): Promise<Response> {
+    ): Promise<
+        Result<
+            Response,
+            RequestAbortedError | RequestTimeoutError | ConnectionError | UnexpectedClientError
+        >
+    > {
         const { context, errorCodes } = options;
         const retryConfig = options.retryConfig || { strategy: "none" };
         const retryCodes = options.retryCodes || [];
 
         return retry(
             async () => {
-                const req = request.clone();
-
-                let response = await this.client.request(
-                    await this.hooks$.beforeRequest(context, req)
+                const req = await this.hooks$.beforeRequest(context, request.clone());
+                await logRequest(this.logger, req).catch((e) =>
+                    this.logger?.log("Failed to log request:", e)
                 );
 
+                let response = await this.httpClient.request(req);
+
                 if (matchStatusCode(response, errorCodes)) {
                     const result = await this.hooks$.afterError(context, response, null);
                     if (result.error) {
@@ -193,18 +238,120 @@ export class ClientSDK {
                     response = await this.hooks$.afterSuccess(context, response);
                 }
 
+                await logResponse(this.logger, response, req).catch((e) =>
+                    this.logger?.log("Failed to log response:", e)
+                );
+
                 return response;
             },
             { config: retryConfig, statusCodes: retryCodes }
+        ).then(
+            (r) => OK(r),
+            (err) => {
+                switch (true) {
+                    case isAbortError(err):
+                        return ERR(
+                            new RequestAbortedError("Request aborted by client", { cause: err })
+                        );
+                    case isTimeoutError(err):
+                        return ERR(new RequestTimeoutError("Request timed out", { cause: err }));
+                    case isConnectionError(err):
+                        return ERR(new ConnectionError("Unable to make request", { cause: err }));
+                    default:
+                        return ERR(
+                            new UnexpectedClientError("Unexpected HTTP client error", {
+                                cause: err,
+                            })
+                        );
+                }
+            }
         );
     }
+}
 
-    protected matcher<Result>(): ResponseMatcher<Result> {
-        return new ResponseMatcher<Result>();
+const jsonLikeContentTypeRE = /^application\/(?:.{0,100}\+)?json/;
+async function logRequest(logger: Logger | undefined, req: Request) {
+    if (!logger) {
+        return;
     }
 
-    protected templateURLComponent = pathToFunc;
+    const contentType = req.headers.get("content-type");
+    const ct = contentType?.split(";")[0] || "";
+
+    logger.group(`> Request: ${req.method} ${req.url}`);
+
+    logger.group("Headers:");
+    for (const [k, v] of req.headers.entries()) {
+        logger.log(`${k}: ${v}`);
+    }
+    logger.groupEnd();
+
+    logger.group("Body:");
+    switch (true) {
+        case jsonLikeContentTypeRE.test(ct):
+            logger.log(await req.clone().json());
+            break;
+        case ct.startsWith("text/"):
+            logger.log(await req.clone().text());
+            break;
+        case ct === "multipart/form-data": {
+            const body = await req.clone().formData();
+            for (const [k, v] of body) {
+                const vlabel = v instanceof Blob ? "<Blob>" : v;
+                logger.log(`${k}: ${vlabel}`);
+            }
+            break;
+        }
+        default:
+            logger.log(`<${contentType}>`);
+            break;
+    }
+    logger.groupEnd();
+
+    logger.groupEnd();
+}
+
+async function logResponse(logger: Logger | undefined, res: Response, req: Request) {
+    if (!logger) {
+        return;
+    }
+
+    const contentType = res.headers.get("content-type");
+    const ct = contentType?.split(";")[0] || "";
+
+    logger.group(`< Response: ${req.method} ${req.url}`);
+    logger.log("Status Code:", res.status, res.statusText);
+
+    logger.group("Headers:");
+    for (const [k, v] of res.headers.entries()) {
+        logger.log(`${k}: ${v}`);
+    }
+    logger.groupEnd();
+
+    logger.group("Body:");
+    switch (true) {
+        case matchContentType(res, "application/json") || jsonLikeContentTypeRE.test(ct):
+            logger.log(await res.clone().json());
+            break;
+        case matchContentType(res, "text/event-stream"):
+            logger.log(`<${contentType}>`);
+            break;
+        case matchContentType(res, "text/*"):
+            logger.log(await res.clone().text());
+            break;
+        case matchContentType(res, "multipart/form-data"): {
+            const body = await res.clone().formData();
+            for (const [k, v] of body) {
+                const vlabel = v instanceof Blob ? "<Blob>" : v;
+                logger.log(`${k}: ${vlabel}`);
+            }
+            break;
+        }
+        default:
+            logger.log(`<${contentType}>`);
+            break;
+    }
+    logger.groupEnd();
 
-    protected resolveSecurity = resolveSecurity;
-    protected resolveGlobalSecurity = resolveGlobalSecurity;
+    logger.groupEnd();
 }