@contentful/optimization-api-client 0.1.0-alpha7 → 0.1.0-alpha9

package/dist/logger.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.cjs","sources":["../src/lib/logger/LogSink.ts","../src/lib/logger/logging.ts","webpack/runtime/define_property_getters","webpack/runtime/has_own_property","webpack/runtime/make_namespace_object","../src/lib/logger/Logger.ts","../src/lib/logger/ConsoleLogSink.ts","../src/lib/logger/index.ts"],"sourcesContent":["import type { LogEvent } from './logging'\n\n/**\n * Abstract base class for log sinks that receive and process log events.\n *\n * @example\n * ```typescript\n * class MyCustomSink extends LogSink {\n *   name = 'MyCustomSink'\n *\n *   ingest(event: LogEvent): void {\n *     // process the event\n *   }\n * }\n * ```\n *\n * @public\n */\nabstract class LogSink {\n  /** Display name used to identify this sink for addition and removal. */\n  abstract name: string\n\n  /**\n   * Processes an incoming log event.\n   *\n   * @param event - The log event to process.\n   * @returns Nothing.\n   */\n  abstract ingest(event: LogEvent): void\n}\n\nexport default LogSink\n","/**\n * Supported log levels ordered from highest to lowest severity.\n *\n * @public\n */\nexport type LogLevels = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'log'\n\n/**\n * A log event emitted by the logger package.\n *\n * @public\n */\nexport interface LogEvent {\n  /** Logger scope name. */\n  name: string\n  /** Event severity level. */\n  level: LogLevels\n  /** Event payload, where the first entry is the formatted message. */\n  messages: unknown[]\n  /** Optional additional context attached by sinks or middleware. */\n  [other: string]: unknown\n}\n\n/**\n * Numeric severity map used for log-level threshold comparisons.\n *\n * @public\n */\nexport const logLevelSeverity: Readonly<Record<LogLevels, number>> = {\n  fatal: 60,\n  error: 50,\n  warn: 40,\n  info: 30,\n  debug: 20,\n  log: 10,\n}\n","__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n        if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n            Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n        }\n    }\n};","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};","import type LogSink from './LogSink'\nimport type { LogEvent, LogLevels } from './logging'\n\n/**\n * Central logger that routes log events through registered {@link LogSink} instances.\n *\n * @example\n * ```typescript\n * import { logger } from '@contentful/optimization-api-client/logger'\n *\n * logger.info('MyModule', 'Application started')\n * ```\n *\n * @public\n */\nexport class Logger {\n  /** The logger's identifier, used as the event scope name. */\n  readonly name = '@contentful/optimization'\n\n  private readonly PREFIX_PARTS = ['Ctfl', 'O10n']\n  private readonly DELIMITER = ':'\n  private sinks: LogSink[] = []\n\n  private assembleLocationPrefix(logLocation: string): string {\n    return `[${[...this.PREFIX_PARTS, logLocation].join(this.DELIMITER)}]`\n  }\n\n  /**\n   * Registers a log sink. If a sink with the same name already exists, it is replaced.\n   *\n   * @param sink - The {@link LogSink} instance to register.\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'\n   *\n   * logger.addSink(new ConsoleLogSink('debug'))\n   * ```\n   */\n  public addSink(sink: LogSink): void {\n    this.sinks = [...this.sinks.filter((existingSink) => existingSink.name !== sink.name), sink]\n  }\n\n  /**\n   * Removes a registered sink by name.\n   *\n   * @param name - The name of the sink to remove.\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * logger.removeSink('ConsoleLogSink')\n   * ```\n   */\n  public removeSink(name: string): void {\n    this.sinks = this.sinks.filter((sink) => sink.name !== name)\n  }\n\n  /**\n   * Removes all registered sinks.\n   *\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * logger.removeSinks()\n   * ```\n   */\n  public removeSinks(): void {\n    this.sinks = []\n  }\n\n  /**\n   * Logs a message at the debug level.\n   *\n   * @param logLocation - The module or component identifier.\n   * @param message - The log message.\n   * @param args - Additional arguments forwarded in the log event.\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * logger.debug('MyModule', 'Debugging value', someVariable)\n   * ```\n   */\n  public debug(logLocation: string, message: string, ...args: unknown[]): void {\n    this.emit('debug', logLocation, message, ...args)\n  }\n\n  /**\n   * Logs a message at the info level.\n   *\n   * @param logLocation - The module or component identifier.\n   * @param message - The log message.\n   * @param args - Additional arguments forwarded in the log event.\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * logger.info('MyModule', 'Operation completed')\n   * ```\n   */\n  public info(logLocation: string, message: string, ...args: unknown[]): void {\n    this.emit('info', logLocation, message, ...args)\n  }\n\n  /**\n   * Logs a message at the log level.\n   *\n   * @param logLocation - The module or component identifier.\n   * @param message - The log message.\n   * @param args - Additional arguments forwarded in the log event.\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * logger.log('MyModule', 'General log entry')\n   * ```\n   */\n  public log(logLocation: string, message: string, ...args: unknown[]): void {\n    this.emit('log', logLocation, message, ...args)\n  }\n\n  /**\n   * Logs a message at the warn level.\n   *\n   * @param logLocation - The module or component identifier.\n   * @param message - The log message.\n   * @param args - Additional arguments forwarded in the log event.\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * logger.warn('MyModule', 'Deprecated method called')\n   * ```\n   */\n  public warn(logLocation: string, message: string, ...args: unknown[]): void {\n    this.emit('warn', logLocation, message, ...args)\n  }\n\n  /**\n   * Logs a message at the error level.\n   *\n   * @param logLocation - The module or component identifier.\n   * @param message - The log message or Error object.\n   * @param args - Additional arguments forwarded in the log event.\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * logger.error('MyModule', new Error('Something failed'))\n   * ```\n   */\n  public error(logLocation: string, message: string | Error, ...args: unknown[]): void {\n    this.emit('error', logLocation, message, ...args)\n  }\n\n  /**\n   * Logs a message at the fatal level.\n   *\n   * @param logLocation - The module or component identifier.\n   * @param message - The log message or Error object.\n   * @param args - Additional arguments forwarded in the log event.\n   * @returns Nothing.\n   *\n   * @example\n   * ```typescript\n   * logger.fatal('MyModule', new Error('Unrecoverable failure'))\n   * ```\n   */\n  public fatal(logLocation: string, message: string | Error, ...args: unknown[]): void {\n    this.emit('fatal', logLocation, message, ...args)\n  }\n\n  private emit(\n    level: LogLevels,\n    logLocation: string,\n    message: string | Error,\n    ...args: unknown[]\n  ): void {\n    this.onLogEvent({\n      name: this.name,\n      level,\n      messages: [`${this.assembleLocationPrefix(logLocation)} ${String(message)}`, ...args],\n    })\n  }\n\n  private onLogEvent(event: LogEvent): void {\n    this.sinks.forEach((sink) => {\n      sink.ingest(event)\n    })\n  }\n}\n\n/**\n * Shared singleton {@link Logger} instance used across the SDK.\n *\n * @public\n */\nexport const logger = new Logger()\n\n/**\n * A location-scoped logger interface whose methods omit the `logLocation` parameter.\n *\n * @public\n */\nexport interface ScopedLogger {\n  /** Logs at debug level. */\n  debug: (message: string, ...args: unknown[]) => void\n  /** Logs at info level. */\n  info: (message: string, ...args: unknown[]) => void\n  /** Logs at log level. */\n  log: (message: string, ...args: unknown[]) => void\n  /** Logs at warn level. */\n  warn: (message: string, ...args: unknown[]) => void\n  /** Logs at error level. */\n  error: (message: string | Error, ...args: unknown[]) => void\n  /** Logs at fatal level. */\n  fatal: (message: string | Error, ...args: unknown[]) => void\n}\n\n/**\n * Creates a {@link ScopedLogger} that automatically prepends the given location to every log call.\n *\n * @param location - The module or component identifier to prepend.\n * @returns A {@link ScopedLogger} bound to the specified location.\n *\n * @example\n * ```typescript\n * import { createScopedLogger } from '@contentful/optimization-api-client/logger'\n *\n * const log = createScopedLogger('MyModule')\n * log.info('Initialization complete')\n * ```\n *\n * @public\n */\nexport function createScopedLogger(location: string): ScopedLogger {\n  return {\n    debug: (message: string, ...args: unknown[]) => {\n      logger.debug(location, message, ...args)\n    },\n    info: (message: string, ...args: unknown[]) => {\n      logger.info(location, message, ...args)\n    },\n    log: (message: string, ...args: unknown[]) => {\n      logger.log(location, message, ...args)\n    },\n    warn: (message: string, ...args: unknown[]) => {\n      logger.warn(location, message, ...args)\n    },\n    error: (message: string | Error, ...args: unknown[]) => {\n      logger.error(location, message, ...args)\n    },\n    fatal: (message: string | Error, ...args: unknown[]) => {\n      logger.fatal(location, message, ...args)\n    },\n  }\n}\n","/* eslint-disable no-console -- using console */\nimport { logLevelSeverity, type LogEvent, type LogLevels } from './logging'\nimport LogSink from './LogSink'\n\nconst consoleMap = {\n  debug: (...args: unknown[]) => {\n    console.debug(...args)\n  },\n  info: (...args: unknown[]) => {\n    console.info(...args)\n  },\n  log: (...args: unknown[]) => {\n    console.log(...args)\n  },\n  warn: (...args: unknown[]) => {\n    console.warn(...args)\n  },\n  error: (...args: unknown[]) => {\n    console.error(...args)\n  },\n  fatal: (...args: unknown[]) => {\n    console.error(...args)\n  },\n}\n\n/**\n * A {@link LogSink} that writes log events to the browser or Node.js console,\n * filtering by a configurable verbosity threshold.\n *\n * @example\n * ```typescript\n * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'\n *\n * logger.addSink(new ConsoleLogSink('debug'))\n * ```\n *\n * @public\n */\nexport class ConsoleLogSink extends LogSink {\n  /** Identifies this sink when registered with the {@link Logger}. */\n  public name = 'ConsoleLogSink'\n\n  /**\n   * Minimum log level required for events to be output.\n   *\n   * @defaultValue 'error'\n   */\n  readonly verbosity: LogLevels\n\n  /**\n   * Creates a new ConsoleLogSink.\n   *\n   * @param verbosity - Minimum log level to output.\n   */\n  constructor(verbosity?: LogLevels) {\n    super()\n\n    this.verbosity = verbosity ?? 'error'\n  }\n\n  /**\n   * Writes a log event to the console if its level meets the verbosity threshold.\n   *\n   * @param event - The log event to process.\n   * @returns Nothing.\n   */\n  ingest(event: LogEvent): void {\n    if (logLevelSeverity[event.level] < logLevelSeverity[this.verbosity]) return\n\n    consoleMap[event.level](...event.messages)\n  }\n}\n","import LogSink from './LogSink'\nimport { Logger } from './Logger'\n\nexport * from './ConsoleLogSink'\nexport * from './LogSink'\nexport * from './Logger'\nexport * from './logging'\n\nexport { LogSink }\nexport default Logger\n"],"names":["LogSink","logLevelSeverity","__webpack_require__","definition","key","Object","obj","prop","Symbol","Logger","logLocation","sink","existingSink","name","message","args","level","String","event","logger","createScopedLogger","location","consoleMap","console","ConsoleLogSink","verbosity"],"mappings":"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"}

package/dist/logger.d.cts

@@ -0,0 +1,287 @@
+/**
+ * A {@link LogSink} that writes log events to the browser or Node.js console,
+ * filtering by a configurable verbosity threshold.
+ *
+ * @example
+ * ```typescript
+ * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.addSink(new ConsoleLogSink('debug'))
+ * ```
+ *
+ * @public
+ */
+export declare class ConsoleLogSink extends LogSink {
+    /** Identifies this sink when registered with the {@link Logger}. */
+    name: string;
+    /**
+     * Minimum log level required for events to be output.
+     *
+     * @defaultValue 'error'
+     */
+    readonly verbosity: LogLevels;
+    /**
+     * Creates a new ConsoleLogSink.
+     *
+     * @param verbosity - Minimum log level to output.
+     */
+    constructor(verbosity?: LogLevels);
+    /**
+     * Writes a log event to the console if its level meets the verbosity threshold.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    ingest(event: LogEvent): void;
+}
+
+/**
+ * Creates a {@link ScopedLogger} that automatically prepends the given location to every log call.
+ *
+ * @param location - The module or component identifier to prepend.
+ * @returns A {@link ScopedLogger} bound to the specified location.
+ *
+ * @example
+ * ```typescript
+ * import { createScopedLogger } from '@contentful/optimization-api-client/logger'
+ *
+ * const log = createScopedLogger('MyModule')
+ * log.info('Initialization complete')
+ * ```
+ *
+ * @public
+ */
+export declare function createScopedLogger(location: string): ScopedLogger;
+
+/**
+ * A log event emitted by the logger package.
+ *
+ * @public
+ */
+export declare interface LogEvent {
+    /** Logger scope name. */
+    name: string;
+    /** Event severity level. */
+    level: LogLevels;
+    /** Event payload, where the first entry is the formatted message. */
+    messages: unknown[];
+    /** Optional additional context attached by sinks or middleware. */
+    [other: string]: unknown;
+}
+
+/**
+ * Central logger that routes log events through registered {@link LogSink} instances.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.info('MyModule', 'Application started')
+ * ```
+ *
+ * @public
+ */
+declare class Logger {
+    /** The logger's identifier, used as the event scope name. */
+    readonly name = "@contentful/optimization";
+    private readonly PREFIX_PARTS;
+    private readonly DELIMITER;
+    private sinks;
+    private assembleLocationPrefix;
+    /**
+     * Registers a log sink. If a sink with the same name already exists, it is replaced.
+     *
+     * @param sink - The {@link LogSink} instance to register.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+     *
+     * logger.addSink(new ConsoleLogSink('debug'))
+     * ```
+     */
+    addSink(sink: LogSink): void;
+    /**
+     * Removes a registered sink by name.
+     *
+     * @param name - The name of the sink to remove.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSink('ConsoleLogSink')
+     * ```
+     */
+    removeSink(name: string): void;
+    /**
+     * Removes all registered sinks.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSinks()
+     * ```
+     */
+    removeSinks(): void;
+    /**
+     * Logs a message at the debug level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.debug('MyModule', 'Debugging value', someVariable)
+     * ```
+     */
+    debug(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the info level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.info('MyModule', 'Operation completed')
+     * ```
+     */
+    info(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the log level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.log('MyModule', 'General log entry')
+     * ```
+     */
+    log(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the warn level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.warn('MyModule', 'Deprecated method called')
+     * ```
+     */
+    warn(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the error level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.error('MyModule', new Error('Something failed'))
+     * ```
+     */
+    error(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    /**
+     * Logs a message at the fatal level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.fatal('MyModule', new Error('Unrecoverable failure'))
+     * ```
+     */
+    fatal(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    private emit;
+    private onLogEvent;
+}
+export { Logger }
+export default Logger;
+
+/**
+ * Shared singleton {@link Logger} instance used across the SDK.
+ *
+ * @public
+ */
+export declare const logger: Logger;
+
+/**
+ * Supported log levels ordered from highest to lowest severity.
+ *
+ * @public
+ */
+export declare type LogLevels = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'log';
+
+/**
+ * Numeric severity map used for log-level threshold comparisons.
+ *
+ * @public
+ */
+export declare const logLevelSeverity: Readonly<Record<LogLevels, number>>;
+
+/**
+ * Abstract base class for log sinks that receive and process log events.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomSink extends LogSink {
+ *   name = 'MyCustomSink'
+ *
+ *   ingest(event: LogEvent): void {
+ *     // process the event
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare abstract class LogSink {
+    /** Display name used to identify this sink for addition and removal. */
+    abstract name: string;
+    /**
+     * Processes an incoming log event.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    abstract ingest(event: LogEvent): void;
+}
+
+/**
+ * A location-scoped logger interface whose methods omit the `logLocation` parameter.
+ *
+ * @public
+ */
+export declare interface ScopedLogger {
+    /** Logs at debug level. */
+    debug: (message: string, ...args: unknown[]) => void;
+    /** Logs at info level. */
+    info: (message: string, ...args: unknown[]) => void;
+    /** Logs at log level. */
+    log: (message: string, ...args: unknown[]) => void;
+    /** Logs at warn level. */
+    warn: (message: string, ...args: unknown[]) => void;
+    /** Logs at error level. */
+    error: (message: string | Error, ...args: unknown[]) => void;
+    /** Logs at fatal level. */
+    fatal: (message: string | Error, ...args: unknown[]) => void;
+}
+
+export { }

package/dist/logger.d.mts

@@ -0,0 +1,287 @@
+/**
+ * A {@link LogSink} that writes log events to the browser or Node.js console,
+ * filtering by a configurable verbosity threshold.
+ *
+ * @example
+ * ```typescript
+ * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.addSink(new ConsoleLogSink('debug'))
+ * ```
+ *
+ * @public
+ */
+export declare class ConsoleLogSink extends LogSink {
+    /** Identifies this sink when registered with the {@link Logger}. */
+    name: string;
+    /**
+     * Minimum log level required for events to be output.
+     *
+     * @defaultValue 'error'
+     */
+    readonly verbosity: LogLevels;
+    /**
+     * Creates a new ConsoleLogSink.
+     *
+     * @param verbosity - Minimum log level to output.
+     */
+    constructor(verbosity?: LogLevels);
+    /**
+     * Writes a log event to the console if its level meets the verbosity threshold.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    ingest(event: LogEvent): void;
+}
+
+/**
+ * Creates a {@link ScopedLogger} that automatically prepends the given location to every log call.
+ *
+ * @param location - The module or component identifier to prepend.
+ * @returns A {@link ScopedLogger} bound to the specified location.
+ *
+ * @example
+ * ```typescript
+ * import { createScopedLogger } from '@contentful/optimization-api-client/logger'
+ *
+ * const log = createScopedLogger('MyModule')
+ * log.info('Initialization complete')
+ * ```
+ *
+ * @public
+ */
+export declare function createScopedLogger(location: string): ScopedLogger;
+
+/**
+ * A log event emitted by the logger package.
+ *
+ * @public
+ */
+export declare interface LogEvent {
+    /** Logger scope name. */
+    name: string;
+    /** Event severity level. */
+    level: LogLevels;
+    /** Event payload, where the first entry is the formatted message. */
+    messages: unknown[];
+    /** Optional additional context attached by sinks or middleware. */
+    [other: string]: unknown;
+}
+
+/**
+ * Central logger that routes log events through registered {@link LogSink} instances.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.info('MyModule', 'Application started')
+ * ```
+ *
+ * @public
+ */
+declare class Logger {
+    /** The logger's identifier, used as the event scope name. */
+    readonly name = "@contentful/optimization";
+    private readonly PREFIX_PARTS;
+    private readonly DELIMITER;
+    private sinks;
+    private assembleLocationPrefix;
+    /**
+     * Registers a log sink. If a sink with the same name already exists, it is replaced.
+     *
+     * @param sink - The {@link LogSink} instance to register.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+     *
+     * logger.addSink(new ConsoleLogSink('debug'))
+     * ```
+     */
+    addSink(sink: LogSink): void;
+    /**
+     * Removes a registered sink by name.
+     *
+     * @param name - The name of the sink to remove.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSink('ConsoleLogSink')
+     * ```
+     */
+    removeSink(name: string): void;
+    /**
+     * Removes all registered sinks.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSinks()
+     * ```
+     */
+    removeSinks(): void;
+    /**
+     * Logs a message at the debug level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.debug('MyModule', 'Debugging value', someVariable)
+     * ```
+     */
+    debug(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the info level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.info('MyModule', 'Operation completed')
+     * ```
+     */
+    info(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the log level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.log('MyModule', 'General log entry')
+     * ```
+     */
+    log(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the warn level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.warn('MyModule', 'Deprecated method called')
+     * ```
+     */
+    warn(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the error level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.error('MyModule', new Error('Something failed'))
+     * ```
+     */
+    error(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    /**
+     * Logs a message at the fatal level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.fatal('MyModule', new Error('Unrecoverable failure'))
+     * ```
+     */
+    fatal(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    private emit;
+    private onLogEvent;
+}
+export { Logger }
+export default Logger;
+
+/**
+ * Shared singleton {@link Logger} instance used across the SDK.
+ *
+ * @public
+ */
+export declare const logger: Logger;
+
+/**
+ * Supported log levels ordered from highest to lowest severity.
+ *
+ * @public
+ */
+export declare type LogLevels = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'log';
+
+/**
+ * Numeric severity map used for log-level threshold comparisons.
+ *
+ * @public
+ */
+export declare const logLevelSeverity: Readonly<Record<LogLevels, number>>;
+
+/**
+ * Abstract base class for log sinks that receive and process log events.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomSink extends LogSink {
+ *   name = 'MyCustomSink'
+ *
+ *   ingest(event: LogEvent): void {
+ *     // process the event
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare abstract class LogSink {
+    /** Display name used to identify this sink for addition and removal. */
+    abstract name: string;
+    /**
+     * Processes an incoming log event.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    abstract ingest(event: LogEvent): void;
+}
+
+/**
+ * A location-scoped logger interface whose methods omit the `logLocation` parameter.
+ *
+ * @public
+ */
+export declare interface ScopedLogger {
+    /** Logs at debug level. */
+    debug: (message: string, ...args: unknown[]) => void;
+    /** Logs at info level. */
+    info: (message: string, ...args: unknown[]) => void;
+    /** Logs at log level. */
+    log: (message: string, ...args: unknown[]) => void;
+    /** Logs at warn level. */
+    warn: (message: string, ...args: unknown[]) => void;
+    /** Logs at error level. */
+    error: (message: string | Error, ...args: unknown[]) => void;
+    /** Logs at fatal level. */
+    fatal: (message: string | Error, ...args: unknown[]) => void;
+}
+
+export { }