@codeleap/logger 6.3.0 → 7.0.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './lib';
+export * from './types';
+export * from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAA;AACrB,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA"}

package/dist/lib/Logger.d.ts

@@ -0,0 +1,52 @@
+import { LoggerConfig } from '../types';
+import { SlackService } from './Slack';
+import { PerformanceService } from './performance';
+/**
+ * Base logger class. Logging methods (`info`, `error`, `warn`, `log`, `debug`, `test`) are stubs
+ * that must be overridden by the consuming app — calling them before providing an implementation
+ * throws. Use {@link createLogger} to produce a concrete instance, then assign it to `logger`.
+ *
+ * `initialize` must be called once before `patchConsole` or any Slack/perf functionality works.
+ */
+export declare class Logger {
+    static initialized: boolean;
+    private config;
+    slack: SlackService;
+    perf: PerformanceService;
+    private isIgnored;
+    /**
+     * Monkey-patches `console.log`, `console.warn`, and `console.error` so that any message
+     * matching an entry in `config.Logger.ignoreLogs` is silently dropped.
+     *
+     * Call this after `initialize`. Patching before initialization has no effect because
+     * `isIgnored` returns `false` until the config is loaded.
+     */
+    patchConsole(): void;
+    /**
+     * Bootstraps the logger with app-wide config. Safe to call multiple times — subsequent calls
+     * are no-ops. Also instantiates `slack` and `perf` sub-services, so they are only available
+     * after this method returns.
+     */
+    initialize<T extends LoggerConfig>(config: T): void;
+    /**
+     * Stub — must be overridden. Intended for temporary test logs that should never reach
+     * production; implementations typically no-op in non-dev environments.
+     */
+    test(...args: unknown[]): void;
+    /** Stub — must be overridden. */
+    info(...args: unknown[]): void;
+    /** Stub — must be overridden. */
+    error(...args: unknown[]): void;
+    /** Stub — must be overridden. */
+    warn(...args: unknown[]): void;
+    /** Stub — must be overridden. */
+    log(...args: unknown[]): void;
+    /** Stub — must be overridden. */
+    debug(...args: unknown[]): void;
+}
+/**
+ * Shared `Logger` instance. Logging methods throw until the consuming app replaces them via
+ * {@link createLogger} and calls {@link Logger.initialize}.
+ */
+export declare const logger: Logger;
+//# sourceMappingURL=Logger.d.ts.map

package/dist/lib/Logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/lib/Logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAElD;;;;;;GAMG;AACH,qBAAa,MAAM;IACjB,MAAM,CAAC,WAAW,UAAQ;IAE1B,OAAO,CAAC,MAAM,CAAe;IAE7B,KAAK,EAAG,YAAY,CAAA;IAEpB,IAAI,EAAG,kBAAkB,CAAA;IAEzB,OAAO,CAAC,SAAS;IAMjB;;;;;;OAMG;IACH,YAAY;IAWZ;;;;OAIG;IACH,UAAU,CAAC,CAAC,SAAS,YAAY,EAAE,MAAM,EAAE,CAAC;IAa5C;;;OAGG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAIvB,iCAAiC;IACjC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAIvB,iCAAiC;IACjC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAIxB,iCAAiC;IACjC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAIvB,iCAAiC;IACjC,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAItB,iCAAiC;IACjC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;CAGzB;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM,QAAe,CAAA"}

package/dist/lib/Slack.d.ts

@@ -0,0 +1,51 @@
+import { LoggerConfig } from '../types';
+type EchoSlack = {
+    label: string;
+    data: object;
+    options?: EchoSlackOptions;
+    module?: string;
+};
+type OptionInclude = 'version';
+type SendIn = 'debug' | 'release';
+type EchoSlackOptions = {
+    sendIn?: SendIn[];
+    include?: OptionInclude[];
+};
+/**
+ * Sends structured log messages to a Slack channel via the Slack Web API.
+ *
+ * The service is inert until {@link setApi} is called with an HTTP client. Messages are
+ * silently suppressed when the API client is absent, `echoConfig.enabled` is `false`, or
+ * the current environment does not match the caller-supplied `sendIn` filter.
+ */
+export declare class SlackService {
+    private config;
+    private echoConfig;
+    private isDev;
+    private appName;
+    private api;
+    constructor(config: LoggerConfig);
+    /**
+     * Registers the HTTP client used to POST messages to Slack. Must be called before `echo`
+     * can send anything; calling `echo` without a registered API is a no-op.
+     */
+    setApi(fetcher: any): void;
+    /**
+     * Posts a labelled object to Slack. The message is formatted with `util.inspect` so nested
+     * structures are human-readable in the channel.
+     *
+     * Delivery is conditional on three independent guards:
+     * - `options.sendIn` — restricts to `'debug'` (IsDev) or `'release'` (production) builds;
+     *   omitting `sendIn` sends in both environments.
+     * - `echoConfig.enabled` — master switch in the config; defaults to `true` when omitted.
+     * - A registered API client (see {@link setApi}).
+     *
+     * Failures are caught and logged to `console.error` rather than propagated.
+     */
+    echo(label: EchoSlack['label'], slackData: EchoSlack['data'], moduleName?: EchoSlack['module'], messageOptions?: EchoSlack['options']): Promise<void>;
+    private serializers;
+    private parseOptions;
+    private parseData;
+}
+export {};
+//# sourceMappingURL=Slack.d.ts.map

package/dist/lib/Slack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Slack.d.ts","sourceRoot":"","sources":["../../src/lib/Slack.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC,KAAK,SAAS,GAAG;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,KAAK,aAAa,GAAG,SAAS,CAAA;AAE9B,KAAK,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;AAEjC,KAAK,gBAAgB,GAAG;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;CAC1B,CAAA;AAMD;;;;;;GAMG;AACH,qBAAa,YAAY;IASX,OAAO,CAAC,MAAM;IAR1B,OAAO,CAAC,UAAU,CAA+B;IAEjD,OAAO,CAAC,KAAK,CAAsC;IAEnD,OAAO,CAAC,OAAO,CAAyB;IAExC,OAAO,CAAC,GAAG,CAAK;gBAEI,MAAM,EAAE,YAAY;IAMxC;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,GAAG;IAInB;;;;;;;;;;;OAWG;IACG,IAAI,CACR,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,EAC5B,UAAU,GAAE,SAAS,CAAC,QAAQ,CAAa,EAC3C,cAAc,GAAE,SAAS,CAAC,SAAS,CAAM;IA+B3C,OAAO,CAAC,WAAW,CAIlB;IAED,OAAO,CAAC,YAAY;IA+BpB,OAAO,CAAC,SAAS;CA0BlB"}

package/dist/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Logger';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA"}

package/dist/lib/performance/errors.d.ts

@@ -0,0 +1,16 @@
+import { InspectRenderOptions } from './types';
+type ErrorArgs = InspectRenderOptions & {
+    name: string;
+    maxRenders: number;
+};
+type ErrorNames = 'maxRenders';
+/**
+ * Thrown by {@link PerformanceService.inspectRender} when a component exceeds its allowed
+ * render budget. The error name is always `'Codeleap:Perf'`, making it easy to distinguish
+ * from application errors in React error boundaries or crash-reporting tools.
+ */
+export declare class PerformanceError extends Error {
+    constructor(errorName: ErrorNames, args: Partial<ErrorArgs>);
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/performance/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/lib/performance/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE9C,KAAK,SAAS,GAAG,oBAAoB,GAAG;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,KAAK,UAAU,GAAG,YAAY,CAAA;AAa9B;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC;CAI5D"}

package/dist/lib/performance/index.d.ts

@@ -0,0 +1,31 @@
+import { InspectRenderOptions } from './types';
+import { LoggerConfig } from '../../types';
+export * from './types';
+/**
+ * Dev-only performance utilities. All methods are no-ops in production
+ * (`config.Environment.IsDev === false`) or when
+ * `config.Logger.performanceInspector.enabled` is `false`.
+ */
+export declare class PerformanceService {
+    private config;
+    renderCounter: Record<string, number>;
+    constructor(config: LoggerConfig);
+    /**
+     * Tracks render frequency for a component and warns when it exceeds the configured threshold.
+     *
+     * Call this at the top of a function component body (not inside a hook). By default it also
+     * registers mount/unmount effects via `useEffect` — pass `noHooks: true` to skip those when
+     * the component cannot accept additional hooks.
+     *
+     * When the accumulated render count within a `throttleInterval` window exceeds `maxRenders`,
+     * the counter resets and a {@link PerformanceError} is thrown (surfacing as a React error
+     * boundary hit rather than a silent warning).
+     *
+     * Components whose names start with any entry in
+     * `config.Logger.performanceInspector.blacklist` are silently skipped.
+     *
+     * Has no effect outside a dev environment or when the inspector is disabled in config.
+     */
+    inspectRender: (name: string, options?: InspectRenderOptions) => void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/performance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/performance/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,cAAc,SAAS,CAAA;AAEvB;;;;GAIG;AACH,qBAAa,kBAAkB;IAGjB,OAAO,CAAC,MAAM;IAF1B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAK;gBAEtB,MAAM,EAAE,YAAY;IAExC;;;;;;;;;;;;;;;OAeG;IACH,aAAa,GACX,MAAM,MAAM,EACZ,UAAS,oBAIR,UAmDF;CACF"}

package/dist/lib/performance/types.d.ts

@@ -0,0 +1,7 @@
+export type InspectRenderOptions = {
+    noHooks?: boolean;
+    logMode?: 'raw' | 'summarized';
+    throttleInterval?: number;
+    maxRenders?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/performance/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/performance/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,KAAK,GAAG,YAAY,CAAA;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+export type LoggerConfig = {
+    AppName: string;
+    Environment: {
+        IsDev: boolean;
+    };
+    Slack: {
+        echo: {
+            channel?: string;
+            icon: string;
+            token: string;
+            baseURL?: string;
+            enabled?: boolean;
+            options?: Record<string, any>;
+        };
+    };
+    Logger: {
+        ignoreLogs: string[];
+        performanceInspector: {
+            enabled: boolean;
+            maxRenders: number;
+            blacklist: string[];
+        };
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAA;IAEf,WAAW,EAAE;QACX,KAAK,EAAE,OAAO,CAAA;KACf,CAAA;IAED,KAAK,EAAE;QACL,IAAI,EAAE;YACJ,OAAO,CAAC,EAAE,MAAM,CAAA;YAChB,IAAI,EAAE,MAAM,CAAA;YACZ,KAAK,EAAE,MAAM,CAAA;YACb,OAAO,CAAC,EAAE,MAAM,CAAA;YAChB,OAAO,CAAC,EAAE,OAAO,CAAA;YACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;SAC9B,CAAA;KACF,CAAA;IAED,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,EAAE,CAAA;QAEpB,oBAAoB,EAAE;YACpB,OAAO,EAAE,OAAO,CAAA;YAChB,UAAU,EAAE,MAAM,CAAA;YAClB,SAAS,EAAE,MAAM,EAAE,CAAA;SACpB,CAAA;KACF,CAAA;CAEF,CAAA"}

package/dist/utils/createLogger.d.ts

@@ -0,0 +1,40 @@
+type Level = 'info' | 'debug' | 'error' | 'warn' | 'log';
+export type TransportFunction = (level: Level, ...args: unknown[]) => void;
+type LoggerOptions = {
+    transport: TransportFunction[];
+};
+/**
+ * Concrete logger implementation produced by {@link createLogger}. Each log method writes to
+ * the native `console` counterpart **and** fans out to every registered transport, so
+ * third-party sinks (e.g. Sentry, Datadog) receive the same payload without extra wiring.
+ *
+ * `test` is intentionally a no-op — it exists as a scratch channel that leaves no output in
+ * any environment.
+ *
+ * Transport functions are shared as a static property, meaning all `CustomLogger` instances
+ * created in the same process share the same transport list. Only one call to
+ * {@link createLogger} is expected per app.
+ */
+declare class CustomLogger {
+    static transport: TransportFunction[];
+    static applyTransport(level: Level, ...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    /** Intentional no-op. Use as a scratch channel for temporary logs that must not ship. */
+    test(...args: unknown[]): void;
+    log(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+/**
+ * Wires up the transport list and returns a ready-to-use {@link CustomLogger} instance.
+ *
+ * The returned instance satisfies the logging method contract expected by {@link Logger},
+ * so it should be used to replace the stub methods on the shared `logger` singleton after
+ * calling `logger.initialize(config)`.
+ *
+ * Calling this more than once replaces the shared transport list for all existing instances.
+ */
+export declare const createLogger: (options: LoggerOptions) => CustomLogger;
+export {};
+//# sourceMappingURL=createLogger.d.ts.map

package/dist/utils/createLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createLogger.d.ts","sourceRoot":"","sources":["../../src/utils/createLogger.ts"],"names":[],"mappings":"AACA,KAAK,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAA;AAExD,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;AAE1E,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,EAAE,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,cAAM,YAAY;IAChB,MAAM,CAAC,SAAS,EAAE,iBAAiB,EAAE,CAAA;IAErC,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IAMtD,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAKvB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAKxB,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAKvB,yFAAyF;IACzF,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAIvB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;IAKtB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE;CAIzB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,aAAa,iBAIlD,CAAA"}

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './createLogger';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA"}

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@codeleap/logger",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "main": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "license": "UNLICENSED",
   "repository": {
     "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
@@ -9,23 +22,24 @@
     "directory": "packages/logger"
   },
   "devDependencies": {
-    "@codeleap/types": "6.3.0",
-    "@codeleap/utils": "6.3.0",
-    "@codeleap/config": "6.3.0",
+    "@codeleap/types": "7.0.0",
+    "@codeleap/utils": "7.0.0",
+    "@codeleap/config": "7.0.0",
     "ts-node-dev": "1.1.8",
     "@sentry/types": "8.40.0"
   },
   "scripts": {
-    "build": "echo 'No build needed'"
+    "build": "tsc --build tsconfig.build.json",
+    "typecheck": "bun tsc --noEmit -p ./tsconfig.json"
   },
   "peerDependencies": {
-    "@codeleap/types": "6.3.0",
-    "@codeleap/utils": "6.3.0",
-    "typescript": "5.5.2",
+    "@codeleap/types": "7.0.0",
+    "@codeleap/utils": "7.0.0",
+    "typescript": "6.0.3",
     "react": "19.1.0"
   },
   "dependencies": {
     "util": "0.12.5",
     "url-parse": "^1.5.10"
   }
-}
+}

package/src/lib/Logger.ts

@@ -1,45 +1,57 @@
 import { LoggerConfig } from '../types'
-import { SentryService } from './Sentry'
 import { SlackService } from './Slack'
 import { PerformanceService } from './performance'
 
+/**
+ * Base logger class. Logging methods (`info`, `error`, `warn`, `log`, `debug`, `test`) are stubs
+ * that must be overridden by the consuming app — calling them before providing an implementation
+ * throws. Use {@link createLogger} to produce a concrete instance, then assign it to `logger`.
+ *
+ * `initialize` must be called once before `patchConsole` or any Slack/perf functionality works.
+ */
 export class Logger {
   static initialized = false
 
-  private config: LoggerConfig
+  private config!: LoggerConfig
 
-  slack: SlackService
+  slack!: SlackService
 
-  sentry: SentryService
-
-  perf: PerformanceService
-
-  private overrideConsoleMethod(args: unknown[], originalConsole: Console['log']) {
-    if (!Logger.initialized) return
+  perf!: PerformanceService
 
+  private isIgnored(args: unknown[]): boolean {
+    if (!Logger.initialized) return false
     const ignoreLogs = this.config.Logger.ignoreLogs
-    const shouldIgnore = typeof args[0] === 'string' && ignoreLogs.some(ignoredWarning => args.join(' ').includes(ignoredWarning))
-
-    if (shouldIgnore) return
-
-    return originalConsole.apply(console, args)
+    return typeof args[0] === 'string' && ignoreLogs.some(w => args.join(' ').includes(w))
   }
 
-  constructor() {
-    const consoles = ['log', 'warn', 'error']
-
+  /**
+   * Monkey-patches `console.log`, `console.warn`, and `console.error` so that any message
+   * matching an entry in `config.Logger.ignoreLogs` is silently dropped.
+   *
+   * Call this after `initialize`. Patching before initialization has no effect because
+   * `isIgnored` returns `false` until the config is loaded.
+   */
+  patchConsole() {
+    const consoles = ['log', 'warn', 'error'] as const
     consoles.forEach(level => {
-      const consoleRef = console[level]
-      console[level] = (...args: unknown[]) => this.overrideConsoleMethod(args, consoleRef)
+      const consoleAny = console as unknown as Record<string, (...args: unknown[]) => void>
+      const consoleRef = consoleAny[level].bind(console)
+      consoleAny[level] = (...args: unknown[]) => {
+        if (!this.isIgnored(args)) consoleRef(...args)
+      }
     })
   }
 
+  /**
+   * Bootstraps the logger with app-wide config. Safe to call multiple times — subsequent calls
+   * are no-ops. Also instantiates `slack` and `perf` sub-services, so they are only available
+   * after this method returns.
+   */
   initialize<T extends LoggerConfig>(config: T) {
     if (Logger.initialized) return
 
     this.config = config
 
-    this.sentry = new SentryService(config)
 
     this.slack = new SlackService(config)
 
@@ -48,25 +60,42 @@ export class Logger {
     Logger.initialized = true
   }
 
+  /**
+   * Stub — must be overridden. Intended for temporary test logs that should never reach
+   * production; implementations typically no-op in non-dev environments.
+   */
+  test(...args: unknown[]){
+    throw new Error('Logger: implement the method "test"')
+  }
+
+  /** Stub — must be overridden. */
   info(...args: unknown[]) {
     throw new Error('Logger: implement the method "info"')
   }
 
+  /** Stub — must be overridden. */
   error(...args: unknown[]) {
     throw new Error('Logger: implement the method "error"')
   }
 
+  /** Stub — must be overridden. */
   warn(...args: unknown[]) {
     throw new Error('Logger: implement the method "warn"')
   }
 
+  /** Stub — must be overridden. */
   log(...args: unknown[]) {
     throw new Error('Logger: implement the method "log"')
   }
 
+  /** Stub — must be overridden. */
   debug(...args: unknown[]) {
     throw new Error('Logger: implement the method "debug"')
   }
 }
 
+/**
+ * Shared `Logger` instance. Logging methods throw until the consuming app replaces them via
+ * {@link createLogger} and calls {@link Logger.initialize}.
+ */
 export const logger = new Logger()

package/src/lib/Slack.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { inspect } from 'util'
 import { TypeGuards } from '@codeleap/types'
 import { LoggerConfig } from '../types'
@@ -22,6 +23,13 @@ const DEFAULT_CHANNEL = '#_dev_logs'
 
 const DEFAULT_BASE_URL = 'https://slack.com/api/chat.postMessage'
 
+/**
+ * Sends structured log messages to a Slack channel via the Slack Web API.
+ *
+ * The service is inert until {@link setApi} is called with an HTTP client. Messages are
+ * silently suppressed when the API client is absent, `echoConfig.enabled` is `false`, or
+ * the current environment does not match the caller-supplied `sendIn` filter.
+ */
 export class SlackService {
   private echoConfig: LoggerConfig['Slack']['echo']
 
@@ -29,7 +37,7 @@ export class SlackService {
 
   private appName: LoggerConfig['AppName']
 
-  private api
+  private api: any
 
   constructor(private config: LoggerConfig) {
     this.echoConfig = config.Slack.echo
@@ -37,14 +45,30 @@ export class SlackService {
     this.appName = config.AppName
   }
 
+  /**
+   * Registers the HTTP client used to POST messages to Slack. Must be called before `echo`
+   * can send anything; calling `echo` without a registered API is a no-op.
+   */
   setApi(fetcher: any) {
     this.api = fetcher
   }
 
+  /**
+   * Posts a labelled object to Slack. The message is formatted with `util.inspect` so nested
+   * structures are human-readable in the channel.
+   *
+   * Delivery is conditional on three independent guards:
+   * - `options.sendIn` — restricts to `'debug'` (IsDev) or `'release'` (production) builds;
+   *   omitting `sendIn` sends in both environments.
+   * - `echoConfig.enabled` — master switch in the config; defaults to `true` when omitted.
+   * - A registered API client (see {@link setApi}).
+   *
+   * Failures are caught and logged to `console.error` rather than propagated.
+   */
   async echo(
     label: EchoSlack['label'],
     slackData: EchoSlack['data'],
-    moduleName: EchoSlack['module'] = null,
+    moduleName: EchoSlack['module'] = undefined,
     messageOptions: EchoSlack['options'] = {}
   ) {
     const options = this.parseOptions(messageOptions)

package/src/lib/performance/errors.ts

@@ -11,13 +11,18 @@ const defineError = (errorName: ErrorNames, args: Partial<ErrorArgs>) => {
   switch (errorName) {
     case 'maxRenders':
       return `${args.name} is rendering more than ${args.maxRenders}time per ${
-        args.throttleInterval / 1000
+        (args.throttleInterval ?? 0) / 1000
       }second!
       If you aware of this, you can disable it in the Settings.ts > Performancer.
       `
   }
 }
 
+/**
+ * Thrown by {@link PerformanceService.inspectRender} when a component exceeds its allowed
+ * render budget. The error name is always `'Codeleap:Perf'`, making it easy to distinguish
+ * from application errors in React error boundaries or crash-reporting tools.
+ */
 export class PerformanceError extends Error {
   constructor(errorName: ErrorNames, args: Partial<ErrorArgs>) {
     super(defineError(errorName, args))

package/src/lib/performance/index.ts

@@ -6,18 +6,32 @@ import { LoggerConfig } from '../../types'
 
 export * from './types'
 
+/**
+ * Dev-only performance utilities. All methods are no-ops in production
+ * (`config.Environment.IsDev === false`) or when
+ * `config.Logger.performanceInspector.enabled` is `false`.
+ */
 export class PerformanceService {
   renderCounter: Record<string, number> = {}
 
   constructor(private config: LoggerConfig) { }
 
   /**
-  * inspectRender monitors how much time a component render per second.
-  * Use logger.perf.inspectRender('ComponentName') inside a component to monitor it.
-  * @param {string} name - Component name
-  * @param {PerformanceInspector} options - Some options for the inspector
-  * @returns
-  */
+   * Tracks render frequency for a component and warns when it exceeds the configured threshold.
+   *
+   * Call this at the top of a function component body (not inside a hook). By default it also
+   * registers mount/unmount effects via `useEffect` — pass `noHooks: true` to skip those when
+   * the component cannot accept additional hooks.
+   *
+   * When the accumulated render count within a `throttleInterval` window exceeds `maxRenders`,
+   * the counter resets and a {@link PerformanceError} is thrown (surfacing as a React error
+   * boundary hit rather than a silent warning).
+   *
+   * Components whose names start with any entry in
+   * `config.Logger.performanceInspector.blacklist` are silently skipped.
+   *
+   * Has no effect outside a dev environment or when the inspector is disabled in config.
+   */
   inspectRender = (
     name: string,
     options: InspectRenderOptions = {
@@ -67,13 +81,13 @@ export class PerformanceService {
       return
     }
 
-    function logSummary() {
+    function logSummary(this: PerformanceService) {
       if (renders <= 0) return
 
       console.log(`[PerformanceInspector] Render summary -> ${name}: ${renders}`)
       this.renderCounter[name] = 0
     }
-
+    // @ts-ignore
     throttle(logSummary, name, throttleInterval)
   }
 }

package/src/types.ts

@@ -27,12 +27,4 @@ export type LoggerConfig = {
     }
   }
 
-  Sentry: {
-    enabled: boolean
-    dsn: string
-    provider: any
-    debug?: boolean
-    initArgs?: any
-    beforeBreadcrumb?: any
-  }
 }

package/src/utils/createLogger.ts

@@ -7,6 +7,18 @@ type LoggerOptions = {
   transport: TransportFunction[]
 }
 
+/**
+ * Concrete logger implementation produced by {@link createLogger}. Each log method writes to
+ * the native `console` counterpart **and** fans out to every registered transport, so
+ * third-party sinks (e.g. Sentry, Datadog) receive the same payload without extra wiring.
+ *
+ * `test` is intentionally a no-op — it exists as a scratch channel that leaves no output in
+ * any environment.
+ *
+ * Transport functions are shared as a static property, meaning all `CustomLogger` instances
+ * created in the same process share the same transport list. Only one call to
+ * {@link createLogger} is expected per app.
+ */
 class CustomLogger {
   static transport: TransportFunction[]
 
@@ -31,6 +43,11 @@ class CustomLogger {
     CustomLogger.applyTransport('warn', ...args)
   }
 
+  /** Intentional no-op. Use as a scratch channel for temporary logs that must not ship. */
+  test(...args: unknown[]) {
+
+  }
+
   log(...args: unknown[]) {
     console.log(...args)
     CustomLogger.applyTransport('log', ...args)
@@ -42,6 +59,15 @@ class CustomLogger {
   }
 }
 
+/**
+ * Wires up the transport list and returns a ready-to-use {@link CustomLogger} instance.
+ *
+ * The returned instance satisfies the logging method contract expected by {@link Logger},
+ * so it should be used to replace the stub methods on the shared `logger` singleton after
+ * calling `logger.initialize(config)`.
+ *
+ * Calling this more than once replaces the shared transport list for all existing instances.
+ */
 export const createLogger = (options: LoggerOptions) => {
   CustomLogger.transport = options.transport
 

package/package.json.bak

@@ -1,31 +0,0 @@
-{
-  "name": "@codeleap/logger",
-  "version": "6.3.0",
-  "main": "src/index.ts",
-  "license": "UNLICENSED",
-  "repository": {
-    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
-    "type": "git",
-    "directory": "packages/logger"
-  },
-  "devDependencies": {
-    "@codeleap/types": "workspace:*",
-    "@codeleap/utils": "workspace:*",
-    "@codeleap/config": "workspace:*",
-    "ts-node-dev": "1.1.8",
-    "@sentry/types": "8.40.0"
-  },
-  "scripts": {
-    "build": "echo 'No build needed'"
-  },
-  "peerDependencies": {
-    "@codeleap/types": "workspace:*",
-    "@codeleap/utils": "workspace:*",
-    "typescript": "5.5.2",
-    "react": "19.1.0"
-  },
-  "dependencies": {
-    "util": "0.12.5",
-    "url-parse": "^1.5.10"
-  }
-}

package/src/lib/Sentry.ts

@@ -1,62 +0,0 @@
-import type { Breadcrumb, ClientOptions, SeverityLevel, Client } from '@sentry/types'
-import { LoggerConfig } from '../types'
-
-const SentrySeverityMap: Record<string, SeverityLevel> = {
-  debug: 'debug',
-  error: 'error',
-  info: 'info',
-  log: 'log',
-  warn: 'warning',
-  silent: 'log',
-}
-
-type SentryProvider = {
-  addBreadcrumb: (args: Breadcrumb) => void
-  init(options: ClientOptions): Client
-  captureException(err: any): void
-}
-
-export class SentryService {
-  get provider(): SentryProvider {
-    return this.config.Sentry.provider
-  }
-
-  private get enabled() {
-    return this.config.Sentry.enabled
-  }
-
-  constructor(private config: LoggerConfig) {
-    if (config.Sentry.enabled) {
-      const initOptions: ClientOptions = {
-        dsn: config.Sentry.dsn,
-        debug: config.Sentry.debug,
-        beforeBreadcrumb: config.Sentry.beforeBreadcrumb,
-        integrations: [],
-        enabled: this.enabled,
-        ...config.Sentry.initArgs,
-      }
-
-      this.provider?.init?.(initOptions)
-    }
-  }
-
-  captureBreadcrumb(type: string, msg: string, data: any, category = `logger:${type}`) {
-    if (!this.enabled) return
-
-    const sentryArgs: Breadcrumb = {
-      message: msg,
-      data,
-      category,
-      level: SentrySeverityMap[type],
-      type: '',
-    }
-
-    this.provider.addBreadcrumb(sentryArgs)
-  }
-
-  captureException(err: any) {
-    if (!this.enabled) return
-
-    this.provider.captureException(err)
-  }
-}