@alchemy/common 0.0.0-alpha.0

package/dist/esm/logging/sinks.d.ts

@@ -0,0 +1,90 @@
+import type { LogEntry } from "./config.js";
+/**
+ * In-memory sink for testing purposes.
+ * Captures all log entries in an array that can be inspected in tests.
+ *
+ * **Note:** This is primarily intended for testing SDK integrations.
+ * Most applications should use the default console sink.
+ *
+ * @example
+ * ```ts
+ * import { InMemorySink, setGlobalLoggerConfig, createLogger } from "@alchemy/common";
+ *
+ * // In tests
+ * const sink = new InMemorySink();
+ *
+ * setGlobalLoggerConfig({
+ *   sinks: [sink.sink]
+ * });
+ *
+ * const logger = createLogger({
+ *   package: "@alchemy/aa-infra",
+ *   version: "1.0.0",
+ *   namespace: "aa-infra"
+ * });
+ *
+ * logger.info("test message");
+ *
+ * // Inspect captured logs
+ * expect(sink.count).toBe(1);
+ * expect(sink.latest()?.message).toBe("test message");
+ * ```
+ */
+export declare class InMemorySink {
+    /**
+     * Array of captured log entries
+     */
+    entries: LogEntry[];
+    /**
+     * Creates a new InMemorySink instance.
+     * Binds the sink method to the instance for use as a callback.
+     */
+    constructor();
+    /**
+     * The sink function to pass to setGlobalLoggerConfig.
+     * Captures log entries into the internal array.
+     *
+     * @param {LogEntry} entry - The log entry to capture
+     * @returns {void}
+     */
+    sink(entry: LogEntry): void;
+    /**
+     * Clear all captured entries
+     *
+     * @returns {void}
+     */
+    clear(): void;
+    /**
+     * Get entries filtered by log level
+     *
+     * @param {number} level - The log level to filter by (LogLevel.ERROR, LogLevel.INFO, etc.)
+     * @returns {LogEntry[]} Array of log entries matching the specified level
+     */
+    getByLevel(level: number): LogEntry[];
+    /**
+     * Get entries filtered by namespace
+     *
+     * @param {string} namespace - The namespace to filter by (e.g., "aa-infra", "wallet-apis")
+     * @returns {LogEntry[]} Array of log entries matching the specified namespace
+     */
+    getByNamespace(namespace: string): LogEntry[];
+    /**
+     * Get entries filtered by message substring
+     *
+     * @param {string} substring - The substring to search for in log messages
+     * @returns {LogEntry[]} Array of log entries containing the substring in their message
+     */
+    getByMessage(substring: string): LogEntry[];
+    /**
+     * Get the most recent log entry
+     *
+     * @returns {LogEntry | undefined} The latest log entry, or undefined if no entries have been captured
+     */
+    latest(): LogEntry | undefined;
+    /**
+     * Get the number of captured entries
+     *
+     * @returns {number} The total count of captured log entries
+     */
+    get count(): number;
+}

package/dist/esm/logging/sinks.js

@@ -0,0 +1,111 @@
+/**
+ * In-memory sink for testing purposes.
+ * Captures all log entries in an array that can be inspected in tests.
+ *
+ * **Note:** This is primarily intended for testing SDK integrations.
+ * Most applications should use the default console sink.
+ *
+ * @example
+ * ```ts
+ * import { InMemorySink, setGlobalLoggerConfig, createLogger } from "@alchemy/common";
+ *
+ * // In tests
+ * const sink = new InMemorySink();
+ *
+ * setGlobalLoggerConfig({
+ *   sinks: [sink.sink]
+ * });
+ *
+ * const logger = createLogger({
+ *   package: "@alchemy/aa-infra",
+ *   version: "1.0.0",
+ *   namespace: "aa-infra"
+ * });
+ *
+ * logger.info("test message");
+ *
+ * // Inspect captured logs
+ * expect(sink.count).toBe(1);
+ * expect(sink.latest()?.message).toBe("test message");
+ * ```
+ */
+export class InMemorySink {
+    /**
+     * Creates a new InMemorySink instance.
+     * Binds the sink method to the instance for use as a callback.
+     */
+    constructor() {
+        /**
+         * Array of captured log entries
+         */
+        Object.defineProperty(this, "entries", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        this.sink = this.sink.bind(this);
+    }
+    /**
+     * The sink function to pass to setGlobalLoggerConfig.
+     * Captures log entries into the internal array.
+     *
+     * @param {LogEntry} entry - The log entry to capture
+     * @returns {void}
+     */
+    sink(entry) {
+        this.entries.push(entry);
+    }
+    /**
+     * Clear all captured entries
+     *
+     * @returns {void}
+     */
+    clear() {
+        this.entries = [];
+    }
+    /**
+     * Get entries filtered by log level
+     *
+     * @param {number} level - The log level to filter by (LogLevel.ERROR, LogLevel.INFO, etc.)
+     * @returns {LogEntry[]} Array of log entries matching the specified level
+     */
+    getByLevel(level) {
+        return this.entries.filter((e) => e.level === level);
+    }
+    /**
+     * Get entries filtered by namespace
+     *
+     * @param {string} namespace - The namespace to filter by (e.g., "aa-infra", "wallet-apis")
+     * @returns {LogEntry[]} Array of log entries matching the specified namespace
+     */
+    getByNamespace(namespace) {
+        return this.entries.filter((e) => e.namespace === namespace);
+    }
+    /**
+     * Get entries filtered by message substring
+     *
+     * @param {string} substring - The substring to search for in log messages
+     * @returns {LogEntry[]} Array of log entries containing the substring in their message
+     */
+    getByMessage(substring) {
+        return this.entries.filter((e) => e.message.includes(substring));
+    }
+    /**
+     * Get the most recent log entry
+     *
+     * @returns {LogEntry | undefined} The latest log entry, or undefined if no entries have been captured
+     */
+    latest() {
+        return this.entries[this.entries.length - 1];
+    }
+    /**
+     * Get the number of captured entries
+     *
+     * @returns {number} The total count of captured log entries
+     */
+    get count() {
+        return this.entries.length;
+    }
+}
+//# sourceMappingURL=sinks.js.map

package/dist/esm/logging/sinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.js","sourceRoot":"","sources":["../../../src/logging/sinks.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,YAAY;IAMvB;;;OAGG;IACH;QATA;;WAEG;QACI;;;;mBAAsB,EAAE;WAAC;QAO9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,KAAe;QAClB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,KAAa;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,SAAiB;QAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,SAAiB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IACnE,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;CACF","sourcesContent":["import type { LogEntry } from \"./config.js\";\n\n/**\n * In-memory sink for testing purposes.\n * Captures all log entries in an array that can be inspected in tests.\n *\n * **Note:** This is primarily intended for testing SDK integrations.\n * Most applications should use the default console sink.\n *\n * @example\n * ```ts\n * import { InMemorySink, setGlobalLoggerConfig, createLogger } from \"@alchemy/common\";\n *\n * // In tests\n * const sink = new InMemorySink();\n *\n * setGlobalLoggerConfig({\n *   sinks: [sink.sink]\n * });\n *\n * const logger = createLogger({\n *   package: \"@alchemy/aa-infra\",\n *   version: \"1.0.0\",\n *   namespace: \"aa-infra\"\n * });\n *\n * logger.info(\"test message\");\n *\n * // Inspect captured logs\n * expect(sink.count).toBe(1);\n * expect(sink.latest()?.message).toBe(\"test message\");\n * ```\n */\nexport class InMemorySink {\n  /**\n   * Array of captured log entries\n   */\n  public entries: LogEntry[] = [];\n\n  /**\n   * Creates a new InMemorySink instance.\n   * Binds the sink method to the instance for use as a callback.\n   */\n  constructor() {\n    this.sink = this.sink.bind(this);\n  }\n\n  /**\n   * The sink function to pass to setGlobalLoggerConfig.\n   * Captures log entries into the internal array.\n   *\n   * @param {LogEntry} entry - The log entry to capture\n   * @returns {void}\n   */\n  sink(entry: LogEntry): void {\n    this.entries.push(entry);\n  }\n\n  /**\n   * Clear all captured entries\n   *\n   * @returns {void}\n   */\n  clear(): void {\n    this.entries = [];\n  }\n\n  /**\n   * Get entries filtered by log level\n   *\n   * @param {number} level - The log level to filter by (LogLevel.ERROR, LogLevel.INFO, etc.)\n   * @returns {LogEntry[]} Array of log entries matching the specified level\n   */\n  getByLevel(level: number): LogEntry[] {\n    return this.entries.filter((e) => e.level === level);\n  }\n\n  /**\n   * Get entries filtered by namespace\n   *\n   * @param {string} namespace - The namespace to filter by (e.g., \"aa-infra\", \"wallet-apis\")\n   * @returns {LogEntry[]} Array of log entries matching the specified namespace\n   */\n  getByNamespace(namespace: string): LogEntry[] {\n    return this.entries.filter((e) => e.namespace === namespace);\n  }\n\n  /**\n   * Get entries filtered by message substring\n   *\n   * @param {string} substring - The substring to search for in log messages\n   * @returns {LogEntry[]} Array of log entries containing the substring in their message\n   */\n  getByMessage(substring: string): LogEntry[] {\n    return this.entries.filter((e) => e.message.includes(substring));\n  }\n\n  /**\n   * Get the most recent log entry\n   *\n   * @returns {LogEntry | undefined} The latest log entry, or undefined if no entries have been captured\n   */\n  latest(): LogEntry | undefined {\n    return this.entries[this.entries.length - 1];\n  }\n\n  /**\n   * Get the number of captured entries\n   *\n   * @returns {number} The total count of captured log entries\n   */\n  get count(): number {\n    return this.entries.length;\n  }\n}\n"]}

package/dist/esm/logging/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Schema definition for event logging.
+ * An array of event definitions with their names and optional data structures.
+ */
+export type EventsSchema = readonly {
+    EventName: string;
+    EventData?: Record<string, any>;
+}[];
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Type-safe parameters for tracking events based on the provided schema.
+ * Ensures event names and data structures match the schema definition.
+ * When no schema is provided, allows any event with optional data.
+ *
+ * @template Schema - The events schema to validate against
+ */
+export type TrackEventParameters<Schema extends EventsSchema> = Schema extends readonly [] ? {
+    name: string;
+    data?: any;
+} : {
+    [K in keyof Schema]: Prettify<{
+        name: Schema[K]["EventName"];
+    } & ([undefined] extends [
+        Schema[K]["EventData"]
+    ] ? {
+        data?: undefined;
+    } : {
+        data: Schema[K]["EventData"];
+    })>;
+}[number];
+/**
+ * Main event logger interface for type-safe event tracking and performance profiling.
+ *
+ * @template Schema - The events schema defining allowed events and their data structures
+ */
+export interface EventLogger<Schema extends EventsSchema = []> {
+    /**
+     * Tracks an event with type-safe validation against the schema.
+     *
+     * @param params - Event parameters including name and optional data
+     * @returns Promise that resolves when the event is tracked
+     */
+    trackEvent(params: TrackEventParameters<Schema extends readonly [] ? [] : [...Schema, PerformanceEvent]>): Promise<void>;
+    /**
+     * Wraps a function to automatically track its execution time as a performance event.
+     *
+     * @template TArgs - Function argument types
+     * @template TRet - Function return type
+     * @param name - Name identifier for the profiled function
+     * @param func - Function to wrap with performance tracking
+     * @returns Wrapped function that tracks execution time
+     */
+    profiled<TArgs extends any[], TRet>(name: string, func: (...args: TArgs) => TRet): (...args: TArgs) => TRet;
+    /** Internal properties for logger state and configuration */
+    _internal: {
+        /** Promise that resolves when logger is ready for use */
+        ready: Promise<unknown>;
+        /** Anonymous identifier for this logger instance */
+        anonId: string;
+    };
+}
+/**
+ * Internal logger interface without the profiled method.
+ * Used internally by different logger implementations.
+ *
+ * @template Schema - The events schema defining allowed events and their data structures
+ */
+export type InnerLogger<Schema extends EventsSchema> = Omit<EventLogger<Schema>, "profiled">;
+/**
+ * Context information attached to all logged events.
+ * Provides metadata about the package and version generating events.
+ */
+export type LoggerContext = {
+    /** Name of the package generating events */
+    package: string;
+    /** Version of the package generating events */
+    version: string;
+    /** Additional context properties as key-value pairs */
+    [key: string]: string;
+};
+/**
+ * Built-in performance event schema for tracking function execution times.
+ * Automatically included in all event schemas for profiled function tracking.
+ */
+export type PerformanceEvent = {
+    EventName: "performance";
+    EventData: {
+        /** Execution time in milliseconds */
+        executionTimeMs: number;
+        /** Name of the function being profiled */
+        functionName: string;
+    };
+};
+export {};

package/dist/esm/logging/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/logging/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/logging/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Schema definition for event logging.\n * An array of event definitions with their names and optional data structures.\n */\nexport type EventsSchema = readonly {\n  EventName: string;\n  EventData?: Record<string, any>;\n}[];\n\ntype Prettify<T> = {\n  [K in keyof T]: T[K];\n} & {};\n\n/**\n * Type-safe parameters for tracking events based on the provided schema.\n * Ensures event names and data structures match the schema definition.\n * When no schema is provided, allows any event with optional data.\n *\n * @template Schema - The events schema to validate against\n */\nexport type TrackEventParameters<Schema extends EventsSchema> =\n  Schema extends readonly []\n    ? { name: string; data?: any }\n    : {\n        [K in keyof Schema]: Prettify<\n          { name: Schema[K][\"EventName\"] } & ([undefined] extends [\n            Schema[K][\"EventData\"],\n          ]\n            ? { data?: undefined }\n            : { data: Schema[K][\"EventData\"] })\n        >;\n      }[number];\n\n/**\n * Main event logger interface for type-safe event tracking and performance profiling.\n *\n * @template Schema - The events schema defining allowed events and their data structures\n */\nexport interface EventLogger<Schema extends EventsSchema = []> {\n  /**\n   * Tracks an event with type-safe validation against the schema.\n   *\n   * @param params - Event parameters including name and optional data\n   * @returns Promise that resolves when the event is tracked\n   */\n  trackEvent(\n    params: TrackEventParameters<\n      Schema extends readonly [] ? [] : [...Schema, PerformanceEvent]\n    >,\n  ): Promise<void>;\n\n  /**\n   * Wraps a function to automatically track its execution time as a performance event.\n   *\n   * @template TArgs - Function argument types\n   * @template TRet - Function return type\n   * @param name - Name identifier for the profiled function\n   * @param func - Function to wrap with performance tracking\n   * @returns Wrapped function that tracks execution time\n   */\n  profiled<TArgs extends any[], TRet>(\n    name: string,\n    func: (...args: TArgs) => TRet,\n  ): (...args: TArgs) => TRet;\n\n  /** Internal properties for logger state and configuration */\n  _internal: {\n    /** Promise that resolves when logger is ready for use */\n    ready: Promise<unknown>;\n    /** Anonymous identifier for this logger instance */\n    anonId: string;\n  };\n}\n\n/**\n * Internal logger interface without the profiled method.\n * Used internally by different logger implementations.\n *\n * @template Schema - The events schema defining allowed events and their data structures\n */\nexport type InnerLogger<Schema extends EventsSchema> = Omit<\n  EventLogger<Schema>,\n  \"profiled\"\n>;\n\n/**\n * Context information attached to all logged events.\n * Provides metadata about the package and version generating events.\n */\nexport type LoggerContext = {\n  /** Name of the package generating events */\n  package: string;\n  /** Version of the package generating events */\n  version: string;\n  /** Additional context properties as key-value pairs */\n  [key: string]: string;\n};\n\n/**\n * Built-in performance event schema for tracking function execution times.\n * Automatically included in all event schemas for profiled function tracking.\n */\nexport type PerformanceEvent = {\n  EventName: \"performance\";\n  EventData: {\n    /** Execution time in milliseconds */\n    executionTimeMs: number;\n    /** Name of the function being profiled */\n    functionName: string;\n  };\n};\n"]}

package/dist/esm/logging/utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Detects if the current environment is in development mode.
+ * Checks multiple common development environment indicators.
+ *
+ * @returns {boolean} True if running in development mode
+ */
+export declare function isClientDevMode(): boolean;

package/dist/esm/logging/utils.js

@@ -0,0 +1,21 @@
+/**
+ * Detects if the current environment is in development mode.
+ * Checks multiple common development environment indicators.
+ *
+ * @returns {boolean} True if running in development mode
+ */
+export function isClientDevMode() {
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+        return true;
+    }
+    if (typeof process !== "undefined" &&
+        process.env.NODE_ENV === "development") {
+        return true;
+    }
+    if (typeof window !== "undefined" &&
+        window.location?.hostname?.includes("localhost")) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=utils.js.map

package/dist/esm/logging/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/logging/utils.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IACE,OAAO,OAAO,KAAK,WAAW;QAC9B,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,EACtC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IACE,OAAO,MAAM,KAAK,WAAW;QAC7B,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC,EAChD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["// just in case we're in a setting that doesn't have these types defined\ndeclare const __DEV__: boolean | undefined;\ndeclare const window: Window | undefined;\n\n/**\n * Detects if the current environment is in development mode.\n * Checks multiple common development environment indicators.\n *\n * @returns {boolean} True if running in development mode\n */\nexport function isClientDevMode() {\n  if (typeof __DEV__ !== \"undefined\" && __DEV__) {\n    return true;\n  }\n\n  if (\n    typeof process !== \"undefined\" &&\n    process.env.NODE_ENV === \"development\"\n  ) {\n    return true;\n  }\n\n  if (\n    typeof window !== \"undefined\" &&\n    window.location?.hostname?.includes(\"localhost\")\n  ) {\n    return true;\n  }\n\n  return false;\n}\n"]}

package/dist/esm/rest/restClient.d.ts

@@ -0,0 +1,34 @@
+import type { RestRequestFn, RestRequestSchema } from "./types.js";
+/**
+ * Parameters for creating an AlchemyRestClient instance.
+ */
+export type AlchemyRestClientParams = {
+    /** API key for Alchemy authentication */
+    apiKey?: string;
+    /** JWT token for Alchemy authentication */
+    jwt?: string;
+    /** Custom URL (optional - defaults to Alchemy's chain-agnostic URL, but can be used to override it) */
+    url?: string;
+    /** Custom headers to be sent with requests */
+    headers?: HeadersInit;
+};
+/**
+ * A client for making requests to Alchemy's non-JSON-RPC endpoints.
+ */
+export declare class AlchemyRestClient<Schema extends RestRequestSchema> {
+    private readonly url;
+    private readonly headers;
+    /**
+     * Creates a new instance of AlchemyRestClient.
+     *
+     * @param {AlchemyRestClientParams} params - The parameters for configuring the client, including API key, JWT, custom URL, and headers.
+     */
+    constructor({ apiKey, jwt, url, headers }: AlchemyRestClientParams);
+    /**
+     * Makes an HTTP request to an Alchemy non-JSON-RPC endpoint.
+     *
+     * @param {RestRequestFn<Schema>} params - The parameters for the request
+     * @returns {Promise<unknown>} The response from the request
+     */
+    request: RestRequestFn<Schema>;
+}

package/dist/esm/rest/restClient.js

@@ -0,0 +1,55 @@
+import { FetchError } from "../errors/FetchError.js";
+import { ServerError } from "../errors/ServerError.js";
+import { withAlchemyHeaders } from "../utils/headers.js";
+const ALCHEMY_API_URL = "https://api.g.alchemy.com";
+/**
+ * A client for making requests to Alchemy's non-JSON-RPC endpoints.
+ */
+export class AlchemyRestClient {
+    /**
+     * Creates a new instance of AlchemyRestClient.
+     *
+     * @param {AlchemyRestClientParams} params - The parameters for configuring the client, including API key, JWT, custom URL, and headers.
+     */
+    constructor({ apiKey, jwt, url, headers }) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "headers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Makes an HTTP request to an Alchemy non-JSON-RPC endpoint.
+         *
+         * @param {RestRequestFn<Schema>} params - The parameters for the request
+         * @returns {Promise<unknown>} The response from the request
+         */
+        Object.defineProperty(this, "request", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: async (params) => {
+                const response = await fetch(`${this.url}/${params.route}`, {
+                    method: params.method,
+                    body: params.body ? JSON.stringify(params.body) : undefined,
+                    headers: this.headers,
+                }).catch((error) => {
+                    throw new FetchError(params.route, params.method, error);
+                });
+                if (!response.ok) {
+                    throw new ServerError(await response.text(), response.status, new Error(response.statusText));
+                }
+                return response.json();
+            }
+        });
+        this.url = url ?? ALCHEMY_API_URL;
+        this.headers = new Headers(withAlchemyHeaders({ headers, apiKey, jwt }));
+    }
+}
+//# sourceMappingURL=restClient.js.map

package/dist/esm/rest/restClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restClient.js","sourceRoot":"","sources":["../../../src/rest/restClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGzD,MAAM,eAAe,GAAG,2BAA2B,CAAC;AAgBpD;;GAEG;AACH,MAAM,OAAO,iBAAiB;IAI5B;;;;OAIG;IACH,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAA2B;QARjD;;;;;WAAY;QACZ;;;;;WAAiB;QAYlC;;;;;WAKG;QACI;;;;mBAAiC,KAAK,EAAE,MAAM,EAAE,EAAE;gBACvD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,EAAE;oBAC1D,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;oBAC3D,OAAO,EAAE,IAAI,CAAC,OAAO;iBACtB,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;oBACjB,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;gBAC3D,CAAC,CAAC,CAAC;gBAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBACjB,MAAM,IAAI,WAAW,CACnB,MAAM,QAAQ,CAAC,IAAI,EAAE,EACrB,QAAQ,CAAC,MAAM,EACf,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAC/B,CAAC;gBACJ,CAAC;gBAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;YACzB,CAAC;WAAC;QA5BA,IAAI,CAAC,GAAG,GAAG,GAAG,IAAI,eAAe,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAC,kBAAkB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC;CA2BF","sourcesContent":["import { FetchError } from \"../errors/FetchError.js\";\nimport { ServerError } from \"../errors/ServerError.js\";\nimport { withAlchemyHeaders } from \"../utils/headers.js\";\nimport type { RestRequestFn, RestRequestSchema } from \"./types.js\";\n\nconst ALCHEMY_API_URL = \"https://api.g.alchemy.com\";\n\n/**\n * Parameters for creating an AlchemyRestClient instance.\n */\nexport type AlchemyRestClientParams = {\n  /** API key for Alchemy authentication */\n  apiKey?: string;\n  /** JWT token for Alchemy authentication */\n  jwt?: string;\n  /** Custom URL (optional - defaults to Alchemy's chain-agnostic URL, but can be used to override it) */\n  url?: string;\n  /** Custom headers to be sent with requests */\n  headers?: HeadersInit;\n};\n\n/**\n * A client for making requests to Alchemy's non-JSON-RPC endpoints.\n */\nexport class AlchemyRestClient<Schema extends RestRequestSchema> {\n  private readonly url: string;\n  private readonly headers: Headers;\n\n  /**\n   * Creates a new instance of AlchemyRestClient.\n   *\n   * @param {AlchemyRestClientParams} params - The parameters for configuring the client, including API key, JWT, custom URL, and headers.\n   */\n  constructor({ apiKey, jwt, url, headers }: AlchemyRestClientParams) {\n    this.url = url ?? ALCHEMY_API_URL;\n    this.headers = new Headers(withAlchemyHeaders({ headers, apiKey, jwt }));\n  }\n\n  /**\n   * Makes an HTTP request to an Alchemy non-JSON-RPC endpoint.\n   *\n   * @param {RestRequestFn<Schema>} params - The parameters for the request\n   * @returns {Promise<unknown>} The response from the request\n   */\n  public request: RestRequestFn<Schema> = async (params) => {\n    const response = await fetch(`${this.url}/${params.route}`, {\n      method: params.method,\n      body: params.body ? JSON.stringify(params.body) : undefined,\n      headers: this.headers,\n    }).catch((error) => {\n      throw new FetchError(params.route, params.method, error);\n    });\n\n    if (!response.ok) {\n      throw new ServerError(\n        await response.text(),\n        response.status,\n        new Error(response.statusText),\n      );\n    }\n\n    return response.json();\n  };\n}\n"]}

package/dist/esm/rest/types.d.ts

@@ -0,0 +1,24 @@
+import type { Prettify } from "viem";
+export type RestRequestSchema = readonly {
+    Route: string;
+    Method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD";
+    Body?: unknown | undefined;
+    Response: unknown;
+}[];
+export type RestRequestParams<Schema extends RestRequestSchema | undefined = undefined> = Schema extends RestRequestSchema ? {
+    [K in keyof Schema]: Prettify<{
+        route: Schema[K] extends Schema[number] ? Schema[K]["Route"] : never;
+        method: Schema[K] extends Schema[number] ? Schema[K]["Method"] : never;
+    } & (Schema[K] extends Schema[number] ? Schema[K]["Body"] extends undefined ? {
+        body?: undefined;
+    } : {
+        body: Schema[K]["Body"];
+    } : never)>;
+}[number] : {
+    route: string;
+    method: RestRequestSchema[number]["Method"];
+    body?: unknown | undefined;
+};
+export type RestRequestFn<Schema extends RestRequestSchema | undefined = undefined> = <_parameters extends RestRequestParams<Schema> = RestRequestParams<Schema>, _returnType = Schema extends RestRequestSchema ? Extract<Schema[number], {
+    Route: _parameters["route"];
+}>["Response"] : unknown>(params: _parameters) => Promise<_returnType>;

package/dist/esm/rest/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/rest/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rest/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Prettify } from \"viem\";\n\nexport type RestRequestSchema = readonly {\n  Route: string;\n  Method: \"GET\" | \"POST\" | \"PUT\" | \"DELETE\" | \"PATCH\" | \"OPTIONS\" | \"HEAD\";\n  Body?: unknown | undefined;\n  Response: unknown;\n}[];\n\nexport type RestRequestParams<\n  Schema extends RestRequestSchema | undefined = undefined,\n> = Schema extends RestRequestSchema\n  ? {\n      [K in keyof Schema]: Prettify<\n        {\n          route: Schema[K] extends Schema[number] ? Schema[K][\"Route\"] : never;\n          method: Schema[K] extends Schema[number]\n            ? Schema[K][\"Method\"]\n            : never;\n        } & (Schema[K] extends Schema[number]\n          ? Schema[K][\"Body\"] extends undefined\n            ? { body?: undefined }\n            : { body: Schema[K][\"Body\"] }\n          : never)\n      >;\n    }[number]\n  : {\n      route: string;\n      method: RestRequestSchema[number][\"Method\"];\n      body?: unknown | undefined;\n    };\n\nexport type RestRequestFn<\n  Schema extends RestRequestSchema | undefined = undefined,\n> = <\n  _parameters extends RestRequestParams<Schema> = RestRequestParams<Schema>,\n  _returnType = Schema extends RestRequestSchema\n    ? Extract<Schema[number], { Route: _parameters[\"route\"] }>[\"Response\"]\n    : unknown,\n>(\n  params: _parameters,\n) => Promise<_returnType>;\n"]}

package/dist/esm/tracing/traceHeader.d.ts

@@ -0,0 +1,82 @@
+/**
+ * These are the headers that are used in the trace headers, could be found in the spec
+ *
+ * @see https://www.w3.org/TR/trace-context/#design-overview
+ */
+export declare const TRACE_HEADER_NAME = "traceparent";
+/**
+ * These are the headers that are used in the trace headers, could be found in the spec
+ *
+ * @see https://www.w3.org/TR/trace-context/#design-overview
+ */
+export declare const TRACE_HEADER_STATE = "tracestate";
+/**
+ * Some tools that are useful when dealing with the values
+ * of the trace header. Follows the W3C trace context standard.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export declare class TraceHeader {
+    readonly traceId: string;
+    readonly parentId: string;
+    readonly traceFlags: string;
+    readonly traceState: Record<string, string>;
+    /**
+     * Initializes a new instance with the provided trace identifiers and state information.
+     *
+     * @param {string} traceId The unique identifier for the trace
+     * @param {string} parentId The identifier of the parent trace
+     * @param {string} traceFlags Flags containing trace-related options
+     * @param {TraceHeader["traceState"]} traceState The trace state information for additional trace context
+     */
+    constructor(traceId: string, parentId: string, traceFlags: string, traceState: TraceHeader["traceState"]);
+    /**
+     * Creating a default trace id that is a random setup for both trace id and parent id
+     *
+     * @example ```ts
+     * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+     * ```
+     *
+     * @returns {TraceHeader} A default trace header
+     */
+    static default(): TraceHeader;
+    /**
+     * Should be able to consume a trace header from the headers of an http request
+     *
+     * @example ```ts
+     * const traceHeader = TraceHeader.fromTraceHeader(headers);
+     * ```
+     *
+     * @param {Record<string,string>} headers The headers from the http request
+     * @returns {TraceHeader | undefined} The trace header object, or nothing if not found
+     */
+    static fromTraceHeader(headers: Record<string, string>): TraceHeader | undefined;
+    /**
+     * Should be able to convert the trace header to the format that is used in the headers of an http request
+     *
+     * @example ```ts
+     * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+     * const headers = traceHeader.toTraceHeader();
+     * ```
+     *
+     * @returns {{traceparent: string, tracestate: string}} The trace header in the format of a record, used in our http client
+     */
+    toTraceHeader(): {
+        readonly traceparent: `00-${string}-${string}-${string}`;
+        readonly tracestate: string;
+    };
+    /**
+     * Should be able to create a new trace header with a new event in the trace state,
+     *  as the key of the eventName as breadcrumbs appending onto previous breadcrumbs with the - infix if exists. And the
+     * trace parent gets updated as according to the docs
+     *
+     * @example ```ts
+     * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+     * const newTraceHeader = traceHeader.withEvent("newEvent");
+     * ```
+     *
+     * @param {string} eventName The key of the new event
+     * @returns {TraceHeader} The new trace header
+     */
+    withEvent(eventName: string): TraceHeader;
+}