@alchemy/common 0.0.0-alpha.0

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

@@ -0,0 +1,191 @@
+/**
+ * Log level constants for controlling diagnostics output.
+ * Lower numeric values indicate higher priority (more restrictive filtering).
+ *
+ * @example
+ * ```ts
+ * import { LogLevel, setGlobalLoggerConfig } from "@alchemy/common";
+ *
+ * setGlobalLoggerConfig({ level: LogLevel.DEBUG });
+ * ```
+ */
+export declare const LogLevel: {
+    /** Critical errors only */
+    readonly ERROR: 0;
+    /** Warnings and errors */
+    readonly WARN: 1;
+    /** Informational messages, warnings, and errors */
+    readonly INFO: 2;
+    /** Debug messages and all above */
+    readonly DEBUG: 3;
+    /** All messages including verbose details */
+    readonly VERBOSE: 4;
+};
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+/**
+ * Configuration for redacting sensitive data in log output.
+ */
+export type RedactConfig = {
+    /** Predicate function to test if a key should be redacted. Returns true if the key should be redacted. */
+    keys?: (key: string) => boolean;
+    /** Function to replace redacted values. Defaults to returning "[REDACTED]". */
+    replacer?: (value: unknown, key?: string) => unknown;
+};
+/**
+ * Configuration for the diagnostics logging system.
+ * All properties are optional and will use sensible defaults if not provided.
+ */
+export type DiagnosticsConfig = {
+    /** Minimum log level to emit. Defaults to INFO in development, ERROR in production. */
+    level?: LogLevel;
+    /** Configuration for redacting sensitive data in logs. */
+    redact?: RedactConfig;
+    /** Array of sink functions to receive log entries. Defaults to console sink. */
+    sinks?: Array<(entry: LogEntry) => void>;
+    /** Disable telemetry headers in requests. Defaults to false. */
+    disableTelemetryHeaders?: boolean;
+    /** Array of exact namespace strings to allow. If undefined or empty, all namespaces are enabled. Example: ["aa-infra", "wallet-apis"] */
+    enabledNamespaces?: string[];
+};
+/**
+ * Base context attached to all log entries from a logger instance.
+ */
+export type LoggerContextBase = {
+    /** Package name (e.g., "@alchemy/aa-infra") */
+    package: string;
+    /** Package version (e.g., "1.0.0") */
+    version: string;
+};
+/**
+ * A single log entry emitted by the diagnostics logger.
+ */
+export type LogEntry = {
+    /** Timestamp in milliseconds since epoch (Date.now()) */
+    ts: number;
+    /** Log level of this entry */
+    level: LogLevel;
+    /** Optional namespace for filtering/grouping (e.g., "aa-infra", "wallet-apis") */
+    namespace: string | undefined;
+    /** The log message */
+    message: string;
+    /** Optional structured data attached to this log entry */
+    data?: Record<string, unknown>;
+    /** Package context (name and version) */
+    context: LoggerContextBase;
+};
+/**
+ * Gets the current global logger configuration.
+ * If not yet initialized, returns default configuration based on environment.
+ *
+ * @returns {Required<DiagnosticsConfig>} The current global configuration with all fields populated
+ * @example
+ * ```ts
+ * import { getGlobalLoggerConfig } from "@alchemy/common";
+ *
+ * const config = getGlobalLoggerConfig();
+ * console.log("Current log level:", config.level);
+ * ```
+ */
+export declare function getGlobalLoggerConfig(): Required<DiagnosticsConfig>;
+/**
+ * Sets the global logger configuration.
+ * Partial configuration is supported - unspecified fields retain their current values.
+ *
+ * Configuration precedence (highest to lowest):
+ * 1. Explicit setGlobalLoggerConfig calls
+ * 2. ALCHEMY_LOG_LEVEL environment variable
+ * 3. Defaults (INFO in dev, ERROR in prod)
+ *
+ * @param {DiagnosticsConfig} cfg - Partial configuration to apply
+ * @example
+ * ```ts
+ * import { setGlobalLoggerConfig, LogLevel } from "@alchemy/common";
+ *
+ * // Set log level only
+ * setGlobalLoggerConfig({ level: LogLevel.DEBUG });
+ *
+ * // Add custom sink
+ * setGlobalLoggerConfig({
+ *   sinks: [(entry) => console.log(JSON.stringify(entry))]
+ * });
+ *
+ * // Filter to specific namespaces
+ * setGlobalLoggerConfig({
+ *   enabledNamespaces: ["aa-infra", "wallet-apis"]
+ * });
+ * ```
+ */
+export declare function setGlobalLoggerConfig(cfg: DiagnosticsConfig): void;
+/**
+ * Checks if a given log level is enabled based on current global configuration.
+ * Used internally by logger to short-circuit disabled log statements.
+ *
+ * @param {LogLevel} level - The log level to check
+ * @returns {boolean} True if the level is enabled (will be logged), false otherwise
+ * @example
+ * ```ts
+ * import { isLevelEnabled, LogLevel } from "@alchemy/common";
+ *
+ * if (isLevelEnabled(LogLevel.DEBUG)) {
+ *   // Perform expensive debug computation
+ * }
+ * ```
+ */
+export declare function isLevelEnabled(level: LogLevel): boolean;
+/**
+ * Checks if a given namespace is enabled based on current global configuration.
+ * Used internally by logger to short-circuit logs from disabled namespaces.
+ *
+ * @param {string | undefined} namespace - The namespace to check
+ * @returns {boolean} True if the namespace is enabled (will be logged), false otherwise
+ * @example
+ * ```ts
+ * import { isNamespaceEnabled } from "@alchemy/common";
+ *
+ * if (isNamespaceEnabled("aa-infra")) {
+ *   // This namespace is enabled
+ * }
+ * ```
+ */
+export declare function isNamespaceEnabled(namespace: string | undefined): boolean;
+/**
+ * Redacts sensitive keys in an object based on global redaction configuration.
+ * Performs deep redaction by recursively processing nested objects and arrays.
+ * Default redaction includes: authorization, apiKey, jwt, privateKey, secret, password.
+ *
+ * @param {Record<string, unknown> | undefined} obj - The object to redact
+ * @returns {Record<string, unknown> | undefined} A new object with sensitive values redacted, or undefined if input was undefined
+ * @example
+ * ```ts
+ * import { redactObject } from "@alchemy/common";
+ *
+ * const data = {
+ *   apiKey: "secret123",
+ *   userId: "user-456",
+ *   nested: { secret: "hidden" }
+ * };
+ *
+ * const redacted = redactObject(data);
+ * // { apiKey: "[REDACTED]", userId: "user-456", nested: { secret: "[REDACTED]" } }
+ * ```
+ */
+export declare function redactObject(obj: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * Default console sink for diagnostics logging.
+ * Routes log entries to appropriate console methods based on log level.
+ *
+ * Format: [HH:MM:SS.mmm] [package@version] message {data}
+ *
+ * @param {LogEntry} entry - The log entry to output
+ * @example
+ * ```ts
+ * import { consoleSink, setGlobalLoggerConfig } from "@alchemy/common";
+ *
+ * // Console sink is used by default, but can be explicitly configured
+ * setGlobalLoggerConfig({
+ *   sinks: [consoleSink]
+ * });
+ * ```
+ */
+export declare function consoleSink(entry: LogEntry): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/types/logging/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/logging/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ;IACnB,2BAA2B;;IAE3B,0BAA0B;;IAE1B,mDAAmD;;IAEnD,mCAAmC;;IAEnC,6CAA6C;;CAErC,CAAC;AAGX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,0GAA0G;IAC1G,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACtD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,uFAAuF;IACvF,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,gFAAgF;IAChF,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC;IACzC,gEAAgE;IAChE,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yIAAyI;IACzI,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,KAAK,EAAE,QAAQ,CAAC;IAChB,kFAAkF;IAClF,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,yCAAyC;IACzC,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAqCF;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,CAAC,iBAAiB,CAAC,CAGnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAalE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAezE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAsBrC;AAiDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAwBjD"}

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

@@ -0,0 +1,7 @@
+export { createLogger, LogLevel, consoleSink } from "./logger.js";
+export type { DiagnosticsLogger } from "./logger.js";
+export { setGlobalLoggerConfig, getGlobalLoggerConfig, isLevelEnabled, isNamespaceEnabled, redactObject, } from "./config.js";
+export type { LogEntry, DiagnosticsConfig, RedactConfig, LoggerContextBase, } from "./config.js";
+export { InMemorySink } from "./sinks.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/logging/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,mBAAmB,YAAY,CAAC"}

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

@@ -0,0 +1,11 @@
+import type { EventsSchema, InnerLogger, LoggerContext } from "./types.js";
+/**
+ * Creates a local-only logger that outputs events to the console in development mode.
+ * This logger does not send data to external services and is safe for all environments.
+ *
+ * @template Schema - The events schema defining allowed events and their data structures
+ * @param {LoggerContext} context - Context information to attach to all events
+ * @returns {InnerLogger<Schema>} A logger instance that logs to console in dev mode
+ */
+export declare function createLocalLogger<Schema extends EventsSchema = []>(context: LoggerContext): InnerLogger<Schema>;
+//# sourceMappingURL=local.d.ts.map

package/dist/types/logging/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/logging/local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3E;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,SAAS,YAAY,GAAG,EAAE,EAChE,OAAO,EAAE,aAAa,GACrB,WAAW,CAAC,MAAM,CAAC,CAyBrB"}

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

@@ -0,0 +1,81 @@
+import { LogLevel, consoleSink, type LoggerContextBase } from "./config.js";
+/**
+ * Lazy message supplier function for expensive log computations.
+ * Only evaluated when the log level is enabled.
+ *
+ * @returns {[string, Record<string, unknown>?]} Tuple of [message, optional data]
+ */
+type MessageSupplier = () => [string, Record<string, unknown>?];
+/**
+ * Diagnostics logger instance for developer-facing debugging output.
+ * Provides level-based logging (error, warn, info, debug, verbose) with structured data.
+ */
+export type DiagnosticsLogger = {
+    /** Log debug messages for development and troubleshooting */
+    debug: (msg: string | MessageSupplier, data?: Record<string, unknown>) => void;
+    /** Log informational messages for key operations */
+    info: (msg: string | MessageSupplier, data?: Record<string, unknown>) => void;
+    /** Log warnings for recoverable issues */
+    warn: (msg: string | MessageSupplier, data?: Record<string, unknown>) => void;
+    /** Log errors for failures */
+    error: (msg: string | MessageSupplier, data?: Record<string, unknown>) => void;
+    /** Log verbose details for very detailed tracing */
+    verbose: (msg: string | MessageSupplier, data?: Record<string, unknown>) => void;
+    /** Create a child logger with additional context merged into all log entries */
+    withContext: (extra: Record<string, unknown>) => DiagnosticsLogger;
+    /**
+     * Wrap a function to measure and log its execution time at DEBUG level.
+     * Supports both synchronous and asynchronous functions.
+     *
+     * @template TArgs - Function argument types
+     * @template TRet - Function return type
+     * @param name - Name for profiling logs
+     * @param func - Function to profile
+     * @returns Wrapped function that logs execution time
+     */
+    profiled<TArgs extends any[], TRet>(name: string, func: (...args: TArgs) => TRet): (...args: TArgs) => TRet;
+};
+/**
+ * Parameters for creating a diagnostics logger instance.
+ */
+export type CreateLoggerParams = LoggerContextBase & {
+    /** Optional namespace for filtering/grouping (e.g., "aa-infra", "wallet-apis") */
+    namespace?: string;
+    /** Optional base context merged into all log entries from this logger */
+    baseContext?: Record<string, unknown>;
+};
+/**
+ * Creates a diagnostics logger instance for a package.
+ * Loggers emit structured log entries to configured sinks (default: console).
+ *
+ * All log methods support:
+ * - String messages: `logger.info("message", { data })`
+ * - Lazy suppliers: `logger.debug(() => ["expensive", computeData()])` (only evaluated when level enabled)
+ *
+ * @param {CreateLoggerParams} params - Logger configuration
+ * @returns {DiagnosticsLogger} A logger instance
+ * @example
+ * ```ts
+ * import { createLogger } from "@alchemy/common";
+ *
+ * const logger = createLogger({
+ *   package: "@alchemy/aa-infra",
+ *   version: "1.0.0",
+ *   namespace: "aa-infra"
+ * });
+ *
+ * logger.info("processing request", { chainId: 1 });
+ * logger.debug("detailed state", { userOp: op });
+ *
+ * // Child logger with additional context
+ * const childLogger = logger.withContext({ requestId: "123" });
+ * childLogger.info("step complete"); // includes requestId in all logs
+ *
+ * // Profile a function
+ * const sendWithProfiling = logger.profiled("sendUserOp", sendUserOp);
+ * await sendWithProfiling(op); // logs execution time at DEBUG level
+ * ```
+ */
+export declare function createLogger(params: CreateLoggerParams): DiagnosticsLogger;
+export { LogLevel, consoleSink };
+//# sourceMappingURL=logger.d.ts.map

package/dist/types/logging/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/logging/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,WAAW,EAKX,KAAK,iBAAiB,EAEvB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,6DAA6D;IAC7D,KAAK,EAAE,CACL,GAAG,EAAE,MAAM,GAAG,eAAe,EAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,IAAI,CAAC;IACV,oDAAoD;IACpD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC9E,0CAA0C;IAC1C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC9E,8BAA8B;IAC9B,KAAK,EAAE,CACL,GAAG,EAAE,MAAM,GAAG,eAAe,EAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,IAAI,CAAC;IACV,oDAAoD;IACpD,OAAO,EAAE,CACP,GAAG,EAAE,MAAM,GAAG,eAAe,EAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,IAAI,CAAC;IACV,gFAAgF;IAChF,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,iBAAiB,CAAC;IACnE;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,IAAI,EAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,GAC7B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG;IACnD,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,CAwF1E;AAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC"}

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

@@ -0,0 +1,7 @@
+import type { InnerLogger } from "./types.js";
+/**
+ * No-operation logger that discards all events.
+ * Used as a fallback when logger initialization fails or in disabled states.
+ */
+export declare const noopLogger: InnerLogger<any>;
+//# sourceMappingURL=noop.d.ts.map

package/dist/types/logging/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../../src/logging/noop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,GAAG,CAMvC,CAAC"}

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

@@ -0,0 +1,91 @@
+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;
+}
+//# sourceMappingURL=sinks.d.ts.map

package/dist/types/logging/sinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.d.ts","sourceRoot":"","sources":["../../../src/logging/sinks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,YAAY;IACvB;;OAEG;IACI,OAAO,EAAE,QAAQ,EAAE,CAAM;IAEhC;;;OAGG;;IAKH;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI3B;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE;IAIrC;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE;IAI7C;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE;IAI3C;;;;OAIG;IACH,MAAM,IAAI,QAAQ,GAAG,SAAS;IAI9B;;;;OAIG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;CACF"}

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

@@ -0,0 +1,97 @@
+/**
+ * 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 {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/logging/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC,EAAE,CAAC;AAEJ,KAAK,QAAQ,CAAC,CAAC,IAAI;KAChB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrB,GAAG,EAAE,CAAC;AAEP;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,YAAY,IAC1D,MAAM,SAAS,SAAS,EAAE,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,GAAG,CAAA;CAAE,GAC5B;KACG,CAAC,IAAI,MAAM,MAAM,GAAG,QAAQ,CAC3B;QAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,GAAG,CAAC,CAAC,SAAS,CAAC,SAAS;QACtD,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;KACvB,GACG;QAAE,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE,GACpB;QAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,CACtC;CACF,CAAC,MAAM,CAAC,CAAC;AAEhB;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,SAAS,YAAY,GAAG,EAAE;IAC3D;;;;;OAKG;IACH,UAAU,CACR,MAAM,EAAE,oBAAoB,CAC1B,MAAM,SAAS,SAAS,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,gBAAgB,CAAC,CAChE,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,IAAI,EAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,GAC7B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC;IAE5B,6DAA6D;IAC7D,SAAS,EAAE;QACT,yDAAyD;QACzD,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACxB,oDAAoD;QACpD,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,YAAY,IAAI,IAAI,CACzD,WAAW,CAAC,MAAM,CAAC,EACnB,UAAU,CACX,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE;QACT,qCAAqC;QACrC,eAAe,EAAE,MAAM,CAAC;QACxB,0CAA0C;QAC1C,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC"}

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

@@ -0,0 +1,8 @@
+/**
+ * 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;
+//# sourceMappingURL=utils.d.ts.map

package/dist/types/logging/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/logging/utils.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,eAAe,YAoB9B"}

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

@@ -0,0 +1,35 @@
+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>;
+}
+//# sourceMappingURL=restClient.d.ts.map

package/dist/types/rest/restClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restClient.d.ts","sourceRoot":"","sources":["../../../src/rest/restClient.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAInE;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,qBAAa,iBAAiB,CAAC,MAAM,SAAS,iBAAiB;IAC7D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC;;;;OAIG;gBACS,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,uBAAuB;IAKlE;;;;;OAKG;IACI,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAkBnC;CACH"}

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

@@ -0,0 +1,25 @@
+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>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rest/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAErC,MAAM,MAAM,iBAAiB,GAAG,SAAS;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACzE,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;CACnB,EAAE,CAAC;AAEJ,MAAM,MAAM,iBAAiB,CAC3B,MAAM,SAAS,iBAAiB,GAAG,SAAS,GAAG,SAAS,IACtD,MAAM,SAAS,iBAAiB,GAChC;KACG,CAAC,IAAI,MAAM,MAAM,GAAG,QAAQ,CAC3B;QACE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;QACrE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GACpC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GACnB,KAAK,CAAC;KACX,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GACjC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,SAAS,GACjC;QAAE,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE,GACpB;QAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;KAAE,GAC7B,KAAK,CAAC,CACX;CACF,CAAC,MAAM,CAAC,GACT;IACE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEN,MAAM,MAAM,aAAa,CACvB,MAAM,SAAS,iBAAiB,GAAG,SAAS,GAAG,SAAS,IACtD,CACF,WAAW,SAAS,iBAAiB,CAAC,MAAM,CAAC,GAAG,iBAAiB,CAAC,MAAM,CAAC,EACzE,WAAW,GAAG,MAAM,SAAS,iBAAiB,GAC1C,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC,UAAU,CAAC,GACpE,OAAO,EAEX,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,WAAW,CAAC,CAAC"}