@chainfuse/helpers 2.4.2 → 3.0.0

package/dist/net.d.mts

@@ -1,17 +1,173 @@
-import type { CustomLoging } from '@chainfuse/types';
+import type { z } from 'zod';
+export type LoggingFetchInitType<RI extends RequestInit = RequestInit> = RI & z.input<Awaited<ReturnType<typeof NetHelpers.loggingFetchInit>>>;
+/**
+ * Enum representing HTTP request methods.
+ *
+ * Each member of the enum corresponds to a standard HTTP method, which can be used to specify the desired action to be performed on a given resource.
+ */
+export declare enum Methods {
+    'GET' = "GET",
+    'HEAD' = "HEAD",
+    'POST' = "POST",
+    'PUT' = "PUT",
+    'DELETE' = "DELETE",
+    'CONNECT' = "CONNECT",
+    'OPTIONS' = "OPTIONS",
+    'TRACE' = "TRACE",
+    'PATCH' = "PATCH"
+}
 export declare class NetHelpers {
+    static cfApiLogging(): Promise<z.ZodDefault<z.ZodUnion<[z.ZodObject<{
+        level: z.ZodLiteral<0>;
+    }, "strip", z.ZodTypeAny, {
+        level: 0;
+    }, {
+        level: 0;
+    }>, z.ZodObject<{
+        level: z.ZodNumber;
+        color: z.ZodDefault<z.ZodBoolean>;
+        custom: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnion<[z.ZodVoid, z.ZodPromise<z.ZodVoid>]>>>;
+    }, "strip", z.ZodTypeAny, {
+        level: number;
+        color: boolean;
+        custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
+    }, {
+        level: number;
+        custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
+        color?: boolean | undefined;
+    }>]>>>;
     /**
-     * Removes the `body` property from a RequestInit object to reduce verbosity when logging.
+     * Creates an instance of the Cloudflare API client with enhanced logging capabilities.
+     *
+     * @param apiKey - The API token used to authenticate with the Cloudflare API.
+     * @param logging - The logging configuration object, parsed using the `cfApiLogging` parser.
+     *
+     * @returns A promise that resolves to an instance of the Cloudflare API client.
+     *
+     * The logging configuration supports the following properties:
+     * - `level`: The logging level. If set to `1`, it is internally treated as `2` to include headers for the `cf-ray` ID, but reset back to 1 for the returned logs.
+     * - `color`: Optional. If `true`, enables colored output using the `chalk` library.
+     * - `custom`: Optional. A custom logging function that receives detailed request and response information.
+     *
+     * The function also enhances logging by:
+     * - Extracting and displaying the `cf-ray` ID from response headers.
+     * - Formatting and coloring log output for better readability.
+     * - Stripping redundant parts of URLs and wrapping unique IDs in brackets with color coding.
+     */
+    static cfApi(apiKey: string, logging?: z.input<Awaited<ReturnType<typeof NetHelpers.cfApiLogging>>>): Promise<import("cloudflare").Cloudflare>;
+    static loggingFetchInit(): Promise<z.ZodObject<{
+        logging: z.ZodDefault<z.ZodUnion<[z.ZodObject<{
+            level: z.ZodLiteral<0>;
+        }, "strip", z.ZodTypeAny, {
+            level: 0;
+        }, {
+            level: 0;
+        }>, z.ZodObject<{
+            level: z.ZodNumber;
+            color: z.ZodDefault<z.ZodBoolean>;
+            custom: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnion<[z.ZodVoid, z.ZodPromise<z.ZodVoid>]>>>;
+        }, "strip", z.ZodTypeAny, {
+            level: number;
+            color: boolean;
+            custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
+        }, {
+            level: number;
+            custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
+            color?: boolean | undefined;
+        }>]>>;
+    }, "strip", z.ZodTypeAny, {
+        logging: {
+            level: 0;
+        } | {
+            level: number;
+            color: boolean;
+            custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
+        };
+    }, {
+        logging?: {
+            level: 0;
+        } | {
+            level: number;
+            custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
+            color?: boolean | undefined;
+        } | undefined;
+    }>>;
+    static loggingFetchInitLogging(): Promise<z.ZodDefault<z.ZodUnion<[z.ZodObject<{
+        level: z.ZodLiteral<0>;
+    }, "strip", z.ZodTypeAny, {
+        level: 0;
+    }, {
+        level: 0;
+    }>, z.ZodObject<{
+        level: z.ZodNumber;
+        color: z.ZodDefault<z.ZodBoolean>;
+        custom: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnion<[z.ZodVoid, z.ZodPromise<z.ZodVoid>]>>>;
+    }, "strip", z.ZodTypeAny, {
+        level: number;
+        color: boolean;
+        custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
+    }, {
+        level: number;
+        custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
+        color?: boolean | undefined;
+    }>]>>>;
+    /**
+     * A utility function that wraps the native `fetch` API with enhanced capabilities.
+     * This function allows for customizable logging of request and response details, including headers, body, and status, with support for colorized output and custom logging handlers.
+     *
+     * @template RI - The type of the `RequestInit` object, defaulting to `RequestInit`. Intended for cloudflare's `RequestInit` variation.
+     *
+     * @param info - The input to the `fetch` function, which can be a `Request` object or a URL string.
+     * @param init - An optional configuration object extending `RequestInit` with additional options.
+     *
+     * @returns A promise that resolves to the `Response` object returned by the `fetch` call.
+     *
+     * ### Logging Levels:
+     * - `level >= 1`: Logs basic request details (timestamp, unique ID, method, and URL).
+     * - `level >= 2`: Logs request headers (with sensitive headers stripped).
+     * - `level >= 3`: Logs request body (if available) and response body (if available).
      *
-     * @param {RequestInit} [init={}] - The RequestInit object from which to remove the 'body' property. If not provided, an empty object will be used.
+     * ### Logging Options:
+     * - `logging.level`: The verbosity level of logging (1, 2, or 3).
+     * - `logging.color`: A boolean indicating whether to use colorized output.
+     * - `logging.custom`: An optional custom logging function to handle the log output.
      *
-     * @returns {RequestInit} The updated RequestInit object without the 'body' property.
+     * ### Features:
+     * - Automatically generates a unique ID for each request.
+     * - Strips sensitive headers from logs to ensure security.
+     * - Supports JSON and stream-based request/response bodies.
+     * - Allows for colorized output using the `chalk` library.
+     * - Provides hooks for custom logging implementations.
+     */
+    static loggingFetch<RI extends RequestInit = RequestInit>(info: Parameters<typeof fetch>[0], init?: LoggingFetchInitType<RI>): Promise<Response>;
+    /**
+     * Removes sensitive headers from the provided `Headers` object. Specifically, it deletes the `Set-Cookie` and `Authorization` headers.
+     *
+     * @param originalHeaders - The original `Headers` object to sanitize. Defaults to an empty `Headers` object if not provided.
+     * @returns A new `Headers` object with the sensitive headers removed.
      */
-    static initBodyTrimmer(init?: RequestInit): RequestInit;
     static stripSensitiveHeaders(originalHeaders?: Headers): Headers;
-    static cfApi(apiKey: string, logger?: CustomLoging): Promise<import("cloudflare").Cloudflare>;
+    /**
+     * Determines if the given object is a `Request`-like object.
+     *
+     * This function checks if the provided object has a `url` property of type `string`,
+     * which is a characteristic of the `Request` object used in the Fetch API.
+     *
+     * @param obj - The object to check, typically the first parameter of the `fetch` function.
+     * @returns A boolean indicating whether the object is a `Request` instance.
+     */
     static isRequestLike(obj: Parameters<typeof fetch>[0]): obj is Request;
-    static loggingFetch(info: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1], body?: boolean, logger?: CustomLoging): Promise<Response>;
+    /**
+     * Returns a promise that resolves to a `chalk` instance with a color corresponding to the provided HTTP method.
+     *
+     * The colors are based on the Swagger UI method colors:
+     * @link https://github.com/swagger-api/swagger-ui/blob/master/src/style/_variables.scss#L48-L55
+     *
+     * @param method - The HTTP method for which to retrieve the color.
+     * @returns A promise that resolves to a `chalk` instance with the color corresponding to the provided HTTP method.
+     * @throws An error if the provided method is unsupported.
+     */
+    static methodColors(method: Methods): Promise<import("chalk").ChalkInstance>;
     /**
      * Parses the Server-Timing header and returns an object with the metrics.
      * The object keys are the metric names (with optional descriptions), and the values are the duration of each metric or null if no duration is found.