@safaricom-mxl/log 0.0.3

package/dist/nitro/v3/plugin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.mjs","names":[],"sources":["../../../src/nitro-v3/plugin.ts"],"sourcesContent":["import { definePlugin } from 'nitro'\nimport { useRuntimeConfig } from 'nitro/runtime-config'\nimport type { CaptureError } from 'nitro/types'\nimport type { HTTPEvent } from 'nitro/h3'\nimport { parseURL } from 'ufo'\nimport { createRequestLogger, initLogger, isEnabled } from '../logger'\nimport { shouldLog, getServiceForPath, extractErrorStatus } from '../nitro'\nimport type { MxllogConfig } from '../nitro'\nimport type { EnrichContext, RequestLogger, TailSamplingContext, WideEvent } from '../types'\nimport { filterSafeHeaders } from '../utils'\n\n// Nitro v3 doesn't fully export hook types yet\n// https://github.com/nitrojs/nitro/blob/8882bc9e1dbf2d342e73097f22a2156f70f50575/src/types/runtime/nitro.ts#L48-L53\ninterface NitroV3Hooks {\n  close: () => void\n  error: CaptureError\n  request: (event: HTTPEvent) => void | Promise<void>\n  response: (res: Response, event: HTTPEvent) => void | Promise<void>\n  '@safaricom-mxl/log:emit:keep': (ctx: TailSamplingContext) => void | Promise<void>\n  '@safaricom-mxl/log:enrich': (ctx: EnrichContext) => void | Promise<void>\n  '@safaricom-mxl/log:drain': (ctx: { event: WideEvent; request?: { method?: string; path: string; requestId?: string }; headers?: Record<string, string> }) => void | Promise<void>\n}\n\ntype Hooks = {\n  hook: <T extends keyof NitroV3Hooks>(name: T, listener: NitroV3Hooks[T]) => void\n  callHook: <T extends keyof NitroV3Hooks>(name: T, ...args: Parameters<NitroV3Hooks[T]>) => Promise<void>\n}\n\nfunction getContext(event: HTTPEvent): Record<string, unknown> {\n  if (!event.req.context) {\n    event.req.context = {}\n  }\n  return event.req.context\n}\n\nfunction getSafeRequestHeaders(event: HTTPEvent): Record<string, string> {\n  const headers: Record<string, string> = {}\n  event.req.headers.forEach((value, key) => {\n    headers[key] = value\n  })\n  return filterSafeHeaders(headers)\n}\n\nfunction getSafeResponseHeaders(res: Response): Record<string, string> | undefined {\n  const headers: Record<string, string> = {}\n  res.headers.forEach((value, key) => {\n    headers[key] = value\n  })\n  if (Object.keys(headers).length === 0) return undefined\n  return filterSafeHeaders(headers)\n}\n\nfunction buildHookContext(\n  event: HTTPEvent,\n  res?: Response,\n): Omit<EnrichContext, 'event'> {\n  const { pathname } = parseURL(event.req.url)\n  const responseHeaders = res ? getSafeResponseHeaders(res) : undefined\n  return {\n    request: { method: event.req.method, path: pathname },\n    headers: getSafeRequestHeaders(event),\n    response: {\n      status: res?.status ?? 200,\n      headers: responseHeaders,\n    },\n  }\n}\n\nasync function callDrainHook(\n  hooks: Hooks,\n  emittedEvent: WideEvent | null,\n  event: HTTPEvent,\n  hookContext: Omit<EnrichContext, 'event'>,\n): Promise<void> {\n  if (!emittedEvent) return\n\n  let drainPromise: Promise<unknown> | undefined\n  try {\n    const result = hooks.callHook('@safaricom-mxl/log:drain', {\n      event: emittedEvent,\n      request: hookContext.request,\n      headers: hookContext.headers,\n    })\n    drainPromise = result?.catch?.((err: unknown) => {\n      console.error('[mxllog] drain failed:', err)\n    })\n  } catch (err) {\n    console.error('[mxllog] drain failed:', err)\n  }\n\n  if (!drainPromise) return\n\n  // Use waitUntil if available (srvx native — Cloudflare Workers, Vercel Edge, etc.)\n  // This keeps the runtime alive for background work without blocking the response\n  if (typeof event.req.waitUntil === 'function') {\n    event.req.waitUntil(drainPromise)\n  } else {\n    // Fallback: await drain to prevent lost logs in serverless environments\n    // (e.g. Vercel Fluid Compute). On the normal path this runs from the\n    // response hook (response already sent); on the error path it may run\n    // before the error response is finalized.\n    await drainPromise\n  }\n}\n\nasync function callEnrichAndDrain(\n  hooks: Hooks,\n  emittedEvent: WideEvent | null,\n  event: HTTPEvent,\n  res?: Response,\n): Promise<void> {\n  if (!emittedEvent) return\n\n  const hookContext = buildHookContext(event, res)\n\n  try {\n    await hooks.callHook('@safaricom-mxl/log:enrich', { event: emittedEvent, ...hookContext })\n  } catch (err) {\n    console.error('[mxllog] enrich failed:', err)\n  }\n\n  await callDrainHook(hooks, emittedEvent, event, hookContext)\n}\n\n/**\n * Nitro v3 plugin entry point.\n *\n * Usage in Nitro v3:\n * ```ts\n * // plugins/mxllog.ts\n * export { default } from '@safaricom-mxl/log/nitro/v3'\n * ```\n */\nexport default definePlugin((nitroApp) => {\n  // In production builds the plugin is bundled and useRuntimeConfig()\n  // resolves the virtual module correctly. In dev mode the plugin is\n  // loaded externally so useRuntimeConfig() returns a stub — fall back\n  // to the env var bridge set by the module.\n  const mxllogConfig = (useRuntimeConfig().mxllog ?? (process.env.__MXLLOG_CONFIG ? JSON.parse(process.env.__MXLLOG_CONFIG) : undefined)) as MxllogConfig | undefined\n\n  initLogger({\n    enabled: mxllogConfig?.enabled,\n    env: mxllogConfig?.env,\n    pretty: mxllogConfig?.pretty,\n    sampling: mxllogConfig?.sampling,\n  })\n\n  if (!isEnabled()) return\n\n  const hooks = nitroApp.hooks as unknown as Hooks\n\n  hooks.hook('request', (event) => {\n    const { pathname } = parseURL(event.req.url)\n\n    // Skip logging for routes not matching include/exclude patterns\n    if (!shouldLog(pathname, mxllogConfig?.include, mxllogConfig?.exclude)) {\n      return\n    }\n\n    const ctx = getContext(event)\n\n    // Store start time for duration calculation in tail sampling\n    ctx._mxllogStartTime = Date.now()\n\n    let requestIdOverride: string | undefined = undefined\n    if (globalThis.navigator?.userAgent === 'Cloudflare-Workers') {\n      const cfRay = event.req.headers.get('cf-ray')\n      if (cfRay) requestIdOverride = cfRay\n    }\n\n    const log = createRequestLogger({\n      method: event.req.method,\n      path: pathname,\n      requestId: requestIdOverride || ctx.requestId as string | undefined || crypto.randomUUID(),\n    })\n\n    // Apply route-based service configuration if a matching route is found\n    const routeService = getServiceForPath(pathname, mxllogConfig?.routes)\n    if (routeService) {\n      log.set({ service: routeService })\n    }\n\n    ctx.log = log\n  })\n\n  hooks.hook('response', async (res, event) => {\n    const ctx = event.req.context\n    // Skip if already emitted by error hook\n    if (ctx?._mxllogEmitted) return\n\n    const log = ctx?.log as RequestLogger | undefined\n    if (!log || !ctx) return\n\n    const { status } = res\n    log.set({ status })\n\n    const startTime = ctx._mxllogStartTime as number | undefined\n    const durationMs = startTime ? Date.now() - startTime : undefined\n\n    const { pathname } = parseURL(event.req.url)\n\n    const tailCtx: TailSamplingContext = {\n      status,\n      duration: durationMs,\n      path: pathname,\n      method: event.req.method,\n      context: log.getContext(),\n      shouldKeep: false,\n    }\n\n    await hooks.callHook('@safaricom-mxl/log:emit:keep', tailCtx)\n\n    const emittedEvent = log.emit({ _forceKeep: tailCtx.shouldKeep })\n    await callEnrichAndDrain(hooks, emittedEvent, event, res)\n  })\n\n  hooks.hook('error', async (error, { event }) => {\n    if (!event) return\n    const e = event as HTTPEvent\n\n    const ctx = e.req.context\n    const log = ctx?.log as RequestLogger | undefined\n    if (!log || !ctx) return\n\n    // Check if error.cause is an MxllogError (thrown errors get wrapped in HTTPError by nitro)\n    const actualError = (error.cause as Error)?.name === 'MxllogError'\n      ? error.cause as Error\n      : error as Error\n\n    log.error(actualError)\n\n    const errorStatus = extractErrorStatus(actualError)\n    log.set({ status: errorStatus })\n\n    const { pathname } = parseURL(e.req.url)\n    const startTime = ctx._mxllogStartTime as number | undefined\n    const durationMs = startTime ? Date.now() - startTime : undefined\n\n    const tailCtx: TailSamplingContext = {\n      status: errorStatus,\n      duration: durationMs,\n      path: pathname,\n      method: e.req.method,\n      context: log.getContext(),\n      shouldKeep: false,\n    }\n\n    await hooks.callHook('@safaricom-mxl/log:emit:keep', tailCtx)\n\n    ctx._mxllogEmitted = true\n\n    const emittedEvent = log.emit({ _forceKeep: tailCtx.shouldKeep })\n    await callEnrichAndDrain(hooks, emittedEvent, e)\n  })\n})\n"],"mappings":"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"}

package/dist/nitro/v3/useLogger.d.mts

@@ -0,0 +1,24 @@
+import { RequestLogger } from "../../types.mjs";
+import { HTTPEvent } from "nitro/h3";
+
+//#region src/nitro-v3/useLogger.d.ts
+/**
+ * Returns the request logger attached to the given Nitro v3 HTTP event.
+ *
+ * @param event - The current HTTPEvent from Nitro v3.
+ * @param service - Optional service name to override the default service.
+ * @returns The request-scoped logger.
+ * @throws Error if the logger is not initialized on the event context.
+ *
+ * @example
+ * import { useLogger } from '@safaricom-mxl/log/nitro/v3'
+ *
+ * export default defineHandler((event) => {
+ *   const log = useLogger(event)
+ *   log.set({ foo: 'bar' })
+ * })
+ */
+declare function useLogger<T extends object = Record<string, unknown>>(event: HTTPEvent, service?: string): RequestLogger<T>;
+//#endregion
+export { useLogger };
+//# sourceMappingURL=useLogger.d.mts.map

package/dist/nitro/v3/useLogger.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLogger.d.mts","names":[],"sources":["../../../src/nitro-v3/useLogger.ts"],"mappings":";;;;;;AAmBA;;;;;;;;;;;;;;iBAAgB,SAAA,oBAA6B,MAAA,kBAAA,CAAyB,KAAA,EAAO,SAAA,EAAW,OAAA,YAAmB,aAAA,CAAc,CAAA"}

package/dist/nitro/v3/useLogger.mjs

@@ -0,0 +1,27 @@
+//#region src/nitro-v3/useLogger.ts
+/**
+* Returns the request logger attached to the given Nitro v3 HTTP event.
+*
+* @param event - The current HTTPEvent from Nitro v3.
+* @param service - Optional service name to override the default service.
+* @returns The request-scoped logger.
+* @throws Error if the logger is not initialized on the event context.
+*
+* @example
+* import { useLogger } from '@safaricom-mxl/log/nitro/v3'
+*
+* export default defineHandler((event) => {
+*   const log = useLogger(event)
+*   log.set({ foo: 'bar' })
+* })
+*/
+function useLogger(event, service) {
+	const log = event.req.context?.log;
+	if (!log) throw new Error("[mxllog] Logger not initialized. Make sure the mxllog Nitro module is registered in nitro.config.ts. Example: modules: [mxllog({ env: { service: 'my-app' } })]");
+	if (service) log.set({ service });
+	return log;
+}
+
+//#endregion
+export { useLogger };
+//# sourceMappingURL=useLogger.mjs.map

package/dist/nitro/v3/useLogger.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLogger.mjs","names":[],"sources":["../../../src/nitro-v3/useLogger.ts"],"sourcesContent":["import type { HTTPEvent } from 'nitro/h3'\nimport type { RequestLogger } from '../types'\n\n/**\n * Returns the request logger attached to the given Nitro v3 HTTP event.\n *\n * @param event - The current HTTPEvent from Nitro v3.\n * @param service - Optional service name to override the default service.\n * @returns The request-scoped logger.\n * @throws Error if the logger is not initialized on the event context.\n *\n * @example\n * import { useLogger } from '@safaricom-mxl/log/nitro/v3'\n *\n * export default defineHandler((event) => {\n *   const log = useLogger(event)\n *   log.set({ foo: 'bar' })\n * })\n */\nexport function useLogger<T extends object = Record<string, unknown>>(event: HTTPEvent, service?: string): RequestLogger<T> {\n  const ctx = event.req.context as Record<string, unknown> | undefined\n  const log = ctx?.log as RequestLogger<T> | undefined\n\n  if (!log) {\n    throw new Error(\n      '[mxllog] Logger not initialized. Make sure the mxllog Nitro module is registered in nitro.config.ts. '\n      + 'Example: modules: [mxllog({ env: { service: \\'my-app\\' } })]',\n    )\n  }\n\n  if (service) {\n    const untyped = log as unknown as RequestLogger\n    untyped.set({ service })\n  }\n\n  return log\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAmBA,SAAgB,UAAsD,OAAkB,SAAoC;CAE1H,MAAM,MADM,MAAM,IAAI,SACL;AAEjB,KAAI,CAAC,IACH,OAAM,IAAI,MACR,kKAED;AAGH,KAAI,QAEF,CADgB,IACR,IAAI,EAAE,SAAS,CAAC;AAG1B,QAAO"}

package/dist/nitro-CrFBjY1Y.d.mts

@@ -0,0 +1,42 @@
+import { EnvironmentContext, RouteConfig, SamplingConfig } from "./types.mjs";
+
+//#region src/nitro.d.ts
+interface NitroModuleOptions {
+  /**
+   * Enable or disable all logging globally.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Environment context overrides.
+   */
+  env?: Partial<EnvironmentContext>;
+  /**
+   * Enable pretty printing.
+   * @default true in development, false in production
+   */
+  pretty?: boolean;
+  /**
+   * Route patterns to include in logging.
+   * Supports glob patterns like '/api/**'.
+   * If not set, all routes are logged.
+   */
+  include?: string[];
+  /**
+   * Route patterns to exclude from logging.
+   * Supports glob patterns like '/_nitro/**'.
+   * Exclusions take precedence over inclusions.
+   */
+  exclude?: string[];
+  /**
+   * Route-specific service configuration.
+   */
+  routes?: Record<string, RouteConfig>;
+  /**
+   * Sampling configuration for filtering logs.
+   */
+  sampling?: SamplingConfig;
+}
+//#endregion
+export { NitroModuleOptions as t };
+//# sourceMappingURL=nitro-CrFBjY1Y.d.mts.map

package/dist/nitro-CrFBjY1Y.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nitro-CrFBjY1Y.d.mts","names":[],"sources":["../src/nitro.ts"],"mappings":";;;UAIiB,kBAAA;EAAA;;;;EAKf,OAAA;EA8BwB;;;EAzBxB,GAAA,GAAM,OAAA,CAAQ,kBAAA;EA8BW;;;;EAxBzB,MAAA;EAAA;;;;;EAOA,OAAA;EAiBA;;;;;EAVA,OAAA;;;;EAKA,MAAA,GAAS,MAAA,SAAe,WAAA;;;;EAKxB,QAAA,GAAW,cAAA;AAAA"}

package/dist/nitro-Dsv6dSzv.mjs

@@ -0,0 +1,39 @@
+//#region src/nitro.ts
+/**
+* Resolve an MxllogError from an error or its cause chain.
+* Both Nitro v2 (h3) and v3 wrap thrown errors — this unwraps them.
+*/
+function resolveMxllogError(error) {
+	if (error.name === "MxllogError") return error;
+	if (error.cause?.name === "MxllogError") return error.cause;
+	return null;
+}
+/**
+* Extract HTTP status from an error, checking both `status` and `statusCode`.
+*/
+function extractErrorStatus(error) {
+	return error.status ?? error.statusCode ?? 500;
+}
+/**
+* Build a standard mxllog error JSON response body.
+* Used by both v2 and v3 error handlers to ensure consistent shape.
+*/
+function serializeMxllogErrorResponse(error, url) {
+	const status = extractErrorStatus(error);
+	const { data } = error;
+	const statusMessage = error.statusMessage || error.message;
+	return {
+		url,
+		status,
+		statusCode: status,
+		statusText: statusMessage,
+		statusMessage,
+		message: error.message,
+		error: true,
+		...data !== void 0 && { data }
+	};
+}
+
+//#endregion
+export { resolveMxllogError as n, serializeMxllogErrorResponse as r, extractErrorStatus as t };
+//# sourceMappingURL=nitro-Dsv6dSzv.mjs.map

package/dist/nitro-Dsv6dSzv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"nitro-Dsv6dSzv.mjs","names":[],"sources":["../src/nitro.ts"],"sourcesContent":["import type { EnvironmentContext, RouteConfig, SamplingConfig } from './types'\n\nexport { shouldLog, getServiceForPath } from './shared/routes'\n\nexport interface NitroModuleOptions {\n  /**\n   * Enable or disable all logging globally.\n   * @default true\n   */\n  enabled?: boolean\n\n  /**\n   * Environment context overrides.\n   */\n  env?: Partial<EnvironmentContext>\n\n  /**\n   * Enable pretty printing.\n   * @default true in development, false in production\n   */\n  pretty?: boolean\n\n  /**\n   * Route patterns to include in logging.\n   * Supports glob patterns like '/api/**'.\n   * If not set, all routes are logged.\n   */\n  include?: string[]\n\n  /**\n   * Route patterns to exclude from logging.\n   * Supports glob patterns like '/_nitro/**'.\n   * Exclusions take precedence over inclusions.\n   */\n  exclude?: string[]\n\n  /**\n   * Route-specific service configuration.\n   */\n  routes?: Record<string, RouteConfig>\n\n  /**\n   * Sampling configuration for filtering logs.\n   */\n  sampling?: SamplingConfig\n}\n\nexport interface MxllogConfig {\n  enabled?: boolean\n  env?: Record<string, unknown>\n  pretty?: boolean\n  include?: string[]\n  exclude?: string[]\n  routes?: Record<string, RouteConfig>\n  sampling?: SamplingConfig\n}\n\n/**\n * Resolve an MxllogError from an error or its cause chain.\n * Both Nitro v2 (h3) and v3 wrap thrown errors — this unwraps them.\n */\nexport function resolveMxllogError(error: Error): Error | null {\n  if (error.name === 'MxllogError') return error\n  if ((error.cause as Error)?.name === 'MxllogError') return error.cause as Error\n  return null\n}\n\n/**\n * Extract HTTP status from an error, checking both `status` and `statusCode`.\n */\nexport function extractErrorStatus(error: unknown): number {\n  return (error as { status?: number }).status\n    ?? (error as { statusCode?: number }).statusCode\n    ?? 500\n}\n\n/**\n * Build a standard mxllog error JSON response body.\n * Used by both v2 and v3 error handlers to ensure consistent shape.\n */\nexport function serializeMxllogErrorResponse(error: Error, url: string): Record<string, unknown> {\n  const status = extractErrorStatus(error)\n  const { data } = error as { data?: unknown }\n  const statusMessage = (error as { statusMessage?: string }).statusMessage || error.message\n  return {\n    url,\n    status,\n    statusCode: status,\n    statusText: statusMessage,\n    statusMessage,\n    message: error.message,\n    error: true,\n    ...(data !== undefined && { data }),\n  }\n}\n\n"],"mappings":";;;;;AA6DA,SAAgB,mBAAmB,OAA4B;AAC7D,KAAI,MAAM,SAAS,cAAe,QAAO;AACzC,KAAK,MAAM,OAAiB,SAAS,cAAe,QAAO,MAAM;AACjE,QAAO;;;;;AAMT,SAAgB,mBAAmB,OAAwB;AACzD,QAAQ,MAA8B,UAChC,MAAkC,cACnC;;;;;;AAOP,SAAgB,6BAA6B,OAAc,KAAsC;CAC/F,MAAM,SAAS,mBAAmB,MAAM;CACxC,MAAM,EAAE,SAAS;CACjB,MAAM,gBAAiB,MAAqC,iBAAiB,MAAM;AACnF,QAAO;EACL;EACA;EACA,YAAY;EACZ,YAAY;EACZ;EACA,SAAS,MAAM;EACf,OAAO;EACP,GAAI,SAAS,UAAa,EAAE,MAAM;EACnC"}

package/dist/nuxt/module.d.mts

@@ -0,0 +1,164 @@
+import { EnvironmentContext, RouteConfig, SamplingConfig, TransportConfig } from "../types.mjs";
+import * as _nuxt_schema0 from "@nuxt/schema";
+
+//#region src/nuxt/module.d.ts
+interface ModuleOptions {
+  /**
+   * Enable or disable all logging globally.
+   * When false, all emits, tagged logs, and request logger operations become no-ops.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Environment context overrides.
+   */
+  env?: Partial<EnvironmentContext>;
+  /**
+   * Enable pretty printing.
+   * @default true in development, false in production
+   */
+  pretty?: boolean;
+  /**
+   * Route patterns to include in logging.
+   * Supports glob patterns like '/api/**'.
+   * If not set, all routes are logged.
+   * @example ['/api/**', '/auth/**']
+   */
+  include?: string[];
+  /**
+   * Route patterns to exclude from logging.
+   * Supports glob patterns like '/api/_nuxt_icon/**'.
+   * Exclusions take precedence over inclusions.
+   * @example ['/api/_nuxt_icon/**', '/health']
+   */
+  exclude?: string[];
+  /**
+   * Route-specific service configuration.
+   * Allows setting different service names for different routes.
+   * Patterns are matched using glob syntax.
+   *
+   * @example
+   * ```ts
+   * routes: {
+   *   '/api/foo/**': { service: 'service1' },
+   *   '/api/bar/**': { service: 'service2' }
+   * }
+   * ```
+   */
+  routes?: Record<string, RouteConfig>;
+  /**
+   * Sampling configuration for filtering logs.
+   * Allows configuring what percentage of logs to keep per level.
+   *
+   * @example
+   * ```ts
+   * sampling: {
+   *   rates: {
+   *     info: 10,    // Keep 10% of info logs
+   *     warn: 50,    // Keep 50% of warning logs
+   *     debug: 5,    // Keep 5% of debug logs
+   *     error: 100,  // Always keep errors (default)
+   *   }
+   * }
+   * ```
+   */
+  sampling?: SamplingConfig;
+  /**
+   * Transport configuration for sending client logs to the server.
+   *
+   * @example
+   * ```ts
+   * transport: {
+   *   enabled: true,  // Send logs to server API
+   *   endpoint: '/api/_mxllog/ingest'  // Custom endpoint
+   * }
+   * ```
+   */
+  transport?: TransportConfig;
+  /**
+   * Axiom adapter configuration.
+   * When configured, use `createAxiomDrain()` from `mxllog/axiom` to send logs.
+   *
+   * @example
+   * ```ts
+   * axiom: {
+   *   dataset: 'my-app-logs',
+   *   token: process.env.AXIOM_TOKEN,
+   * }
+   * ```
+   */
+  axiom?: {
+    /** Axiom dataset name */dataset: string; /** Axiom API token */
+    token: string; /** Organization ID (required for Personal Access Tokens) */
+    orgId?: string; /** Base URL for Axiom API. Default: https://api.axiom.co */
+    baseUrl?: string; /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+  };
+  /**
+   * OTLP adapter configuration.
+   * When configured, use `createOTLPDrain()` from `mxllog/otlp` to send logs.
+   *
+   * @example
+   * ```ts
+   * otlp: {
+   *   endpoint: 'http://localhost:4318',
+   *   headers: {
+   *     'Authorization': `Basic ${process.env.GRAFANA_TOKEN}`,
+   *   },
+   * }
+   * ```
+   */
+  otlp?: {
+    /** OTLP HTTP endpoint (e.g., http://localhost:4318) */endpoint: string; /** Override service name (defaults to event.service) */
+    serviceName?: string; /** Additional resource attributes */
+    resourceAttributes?: Record<string, string | number | boolean>; /** Custom headers (e.g., for authentication) */
+    headers?: Record<string, string>; /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+  };
+  /**
+   * PostHog adapter configuration.
+   * When configured, use `createPostHogDrain()` from `mxllog/posthog` to send logs.
+   *
+   * @example
+   * ```ts
+   * posthog: {
+   *   apiKey: process.env.POSTHOG_API_KEY,
+   * }
+   * ```
+   */
+  posthog?: {
+    /** PostHog project API key */apiKey: string; /** PostHog host URL. Default: https://us.i.posthog.com */
+    host?: string; /** PostHog event name. Default: mxllog_wide_event */
+    eventName?: string; /** Override distinct_id (defaults to event.service) */
+    distinctId?: string; /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+  };
+  /**
+   * Sentry adapter configuration.
+   * When configured, use `createSentryDrain()` from `mxllog/sentry` to send logs.
+   *
+   * @example
+   * ```ts
+   * sentry: {
+   *   dsn: process.env.SENTRY_DSN,
+   * }
+   * ```
+   */
+  sentry?: {
+    /** Sentry DSN */dsn: string; /** Environment override (defaults to event.environment) */
+    environment?: string; /** Release version override (defaults to event.version) */
+    release?: string; /** Additional tags to attach as attributes */
+    tags?: Record<string, string>; /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+  };
+  /**
+   * How long to retain events before cleanup (used by @mxllog/nuxthub).
+   * Supports "30d" (days), "24h" (hours), "60m" (minutes).
+   * @default '30d'
+   */
+  retention?: string;
+}
+declare const _default: _nuxt_schema0.NuxtModule<ModuleOptions, ModuleOptions, false>;
+//#endregion
+export { ModuleOptions, _default as default };
+//# sourceMappingURL=module.d.mts.map

package/dist/nuxt/module.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.mts","names":[],"sources":["../../src/nuxt/module.ts"],"mappings":";;;;UAaiB,aAAA;;;AAAjB;;;EAME,OAAA;EAKM;;;EAAN,GAAA,GAAM,OAAA,CAAQ,kBAAA;EAoEF;;;;EA9DZ,MAAA;EA+Je;;;;;;EAvJf,OAAA;EAQA;;;;;;EAAA,OAAA;EA8CY;;;;;;;;;;;;;EA/BZ,MAAA,GAAS,MAAA,SAAe,WAAA;EAkFtB;;;;;;;;;;;;;;;;EAhEF,QAAA,GAAW,cAAA;EAyHZ;;;;;;;;;;;EA5GC,SAAA,GAAY,eAAA;;;;;;;;;;;;;EAcZ,KAAA;6BAEE,OAAA;IAEA,KAAA;IAEA,KAAA;IAEA,OAAA;IAEA,OAAA;EAAA;;;;;;;;;;;;;;;EAiBF,IAAA;2DAEE,QAAA;IAEA,WAAA;IAEA,kBAAA,GAAqB,MAAA;IAErB,OAAA,GAAU,MAAA;IAEV,OAAA;EAAA;;;;;;;;;;;;EAcF,OAAA;kCAEE,MAAA;IAEA,IAAA;IAEA,SAAA;IAEA,UAAA;IAEA,OAAA;EAAA;;;;;;;;;;;;EAcF,MAAA;qBAEE,GAAA;IAEA,WAAA;IAEA,OAAA;IAEA,IAAA,GAAO,MAAA;IAEP,OAAA;EAAA;;;;;;EAQF,SAAA;AAAA;AAAA,cACD,QAAA"}

package/dist/nuxt/module.mjs

@@ -0,0 +1,84 @@
+import { addImports, addPlugin, addServerHandler, addServerImports, addServerPlugin, createResolver, defineNuxtModule } from "@nuxt/kit";
+
+//#region package.json
+var name = "@safaricom-mxl/log";
+var version = "0.0.3";
+
+//#endregion
+//#region src/nuxt/module.ts
+var module_default = defineNuxtModule({
+	meta: {
+		name,
+		version,
+		configKey: name,
+		docs: "https://mxllog.dev"
+	},
+	defaults: {},
+	setup(options, nuxt) {
+		const resolver = createResolver(import.meta.url);
+		const transportEnabled = options.transport?.enabled ?? false;
+		const transportEndpoint = options.transport?.endpoint ?? "/api/_mxllog/ingest";
+		nuxt.hook("nitro:config", (nitroConfig) => {
+			nitroConfig.errorHandler = nitroConfig.errorHandler || resolver.resolve("../nitro/errorHandler");
+		});
+		nuxt.options.runtimeConfig.mxllog = options;
+		nuxt.options.runtimeConfig.public.mxllog = {
+			enabled: options.enabled ?? true,
+			pretty: options.pretty,
+			transport: {
+				enabled: transportEnabled,
+				endpoint: transportEndpoint
+			}
+		};
+		if (transportEnabled) addServerHandler({
+			route: transportEndpoint,
+			method: "post",
+			handler: resolver.resolve("../runtime/server/routes/_mxllog/ingest.post")
+		});
+		addServerPlugin(resolver.resolve("../nitro/plugin"));
+		addPlugin({
+			src: resolver.resolve("../runtime/client/plugin"),
+			mode: "client"
+		});
+		addImports([
+			{
+				name: "log",
+				from: resolver.resolve("../runtime/client/log")
+			},
+			{
+				name: "setIdentity",
+				from: resolver.resolve("../runtime/client/log")
+			},
+			{
+				name: "clearIdentity",
+				from: resolver.resolve("../runtime/client/log")
+			},
+			{
+				name: "createMxllogError",
+				from: resolver.resolve("../error")
+			},
+			{
+				name: "parseError",
+				from: resolver.resolve("../runtime/utils/parseError")
+			}
+		]);
+		addServerImports([
+			{
+				name: "useLogger",
+				from: resolver.resolve("../runtime/server/useLogger")
+			},
+			{
+				name: "log",
+				from: resolver.resolve("../logger")
+			},
+			{
+				name: "createMxllogError",
+				from: resolver.resolve("../error")
+			}
+		]);
+	}
+});
+
+//#endregion
+export { module_default as default };
+//# sourceMappingURL=module.mjs.map

package/dist/nuxt/module.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.mjs","names":[],"sources":["../../package.json","../../src/nuxt/module.ts"],"sourcesContent":["","import {\n  addImports,\n  addPlugin,\n  addServerHandler,\n  addServerImports,\n  addServerPlugin,\n  createResolver,\n  defineNuxtModule,\n} from '@nuxt/kit'\nimport type { NitroConfig } from 'nitropack'\nimport type { EnvironmentContext, RouteConfig, SamplingConfig, TransportConfig } from '../types'\nimport { name, version } from '../../package.json'\n\nexport interface ModuleOptions {\n  /**\n   * Enable or disable all logging globally.\n   * When false, all emits, tagged logs, and request logger operations become no-ops.\n   * @default true\n   */\n  enabled?: boolean\n\n  /**\n   * Environment context overrides.\n   */\n  env?: Partial<EnvironmentContext>\n\n  /**\n   * Enable pretty printing.\n   * @default true in development, false in production\n   */\n  pretty?: boolean\n\n  /**\n   * Route patterns to include in logging.\n   * Supports glob patterns like '/api/**'.\n   * If not set, all routes are logged.\n   * @example ['/api/**', '/auth/**']\n   */\n  include?: string[]\n\n  /**\n   * Route patterns to exclude from logging.\n   * Supports glob patterns like '/api/_nuxt_icon/**'.\n   * Exclusions take precedence over inclusions.\n   * @example ['/api/_nuxt_icon/**', '/health']\n   */\n  exclude?: string[]\n\n  /**\n   * Route-specific service configuration.\n   * Allows setting different service names for different routes.\n   * Patterns are matched using glob syntax.\n   *\n   * @example\n   * ```ts\n   * routes: {\n   *   '/api/foo/**': { service: 'service1' },\n   *   '/api/bar/**': { service: 'service2' }\n   * }\n   * ```\n   */\n  routes?: Record<string, RouteConfig>\n\n  /**\n   * Sampling configuration for filtering logs.\n   * Allows configuring what percentage of logs to keep per level.\n   *\n   * @example\n   * ```ts\n   * sampling: {\n   *   rates: {\n   *     info: 10,    // Keep 10% of info logs\n   *     warn: 50,    // Keep 50% of warning logs\n   *     debug: 5,    // Keep 5% of debug logs\n   *     error: 100,  // Always keep errors (default)\n   *   }\n   * }\n   * ```\n   */\n  sampling?: SamplingConfig\n\n  /**\n   * Transport configuration for sending client logs to the server.\n   *\n   * @example\n   * ```ts\n   * transport: {\n   *   enabled: true,  // Send logs to server API\n   *   endpoint: '/api/_mxllog/ingest'  // Custom endpoint\n   * }\n   * ```\n   */\n  transport?: TransportConfig\n\n  /**\n   * Axiom adapter configuration.\n   * When configured, use `createAxiomDrain()` from `mxllog/axiom` to send logs.\n   *\n   * @example\n   * ```ts\n   * axiom: {\n   *   dataset: 'my-app-logs',\n   *   token: process.env.AXIOM_TOKEN,\n   * }\n   * ```\n   */\n  axiom?: {\n    /** Axiom dataset name */\n    dataset: string\n    /** Axiom API token */\n    token: string\n    /** Organization ID (required for Personal Access Tokens) */\n    orgId?: string\n    /** Base URL for Axiom API. Default: https://api.axiom.co */\n    baseUrl?: string\n    /** Request timeout in milliseconds. Default: 5000 */\n    timeout?: number\n  }\n\n  /**\n   * OTLP adapter configuration.\n   * When configured, use `createOTLPDrain()` from `mxllog/otlp` to send logs.\n   *\n   * @example\n   * ```ts\n   * otlp: {\n   *   endpoint: 'http://localhost:4318',\n   *   headers: {\n   *     'Authorization': `Basic ${process.env.GRAFANA_TOKEN}`,\n   *   },\n   * }\n   * ```\n   */\n  otlp?: {\n    /** OTLP HTTP endpoint (e.g., http://localhost:4318) */\n    endpoint: string\n    /** Override service name (defaults to event.service) */\n    serviceName?: string\n    /** Additional resource attributes */\n    resourceAttributes?: Record<string, string | number | boolean>\n    /** Custom headers (e.g., for authentication) */\n    headers?: Record<string, string>\n    /** Request timeout in milliseconds. Default: 5000 */\n    timeout?: number\n  }\n\n  /**\n   * PostHog adapter configuration.\n   * When configured, use `createPostHogDrain()` from `mxllog/posthog` to send logs.\n   *\n   * @example\n   * ```ts\n   * posthog: {\n   *   apiKey: process.env.POSTHOG_API_KEY,\n   * }\n   * ```\n   */\n  posthog?: {\n    /** PostHog project API key */\n    apiKey: string\n    /** PostHog host URL. Default: https://us.i.posthog.com */\n    host?: string\n    /** PostHog event name. Default: mxllog_wide_event */\n    eventName?: string\n    /** Override distinct_id (defaults to event.service) */\n    distinctId?: string\n    /** Request timeout in milliseconds. Default: 5000 */\n    timeout?: number\n  }\n\n  /**\n   * Sentry adapter configuration.\n   * When configured, use `createSentryDrain()` from `mxllog/sentry` to send logs.\n   *\n   * @example\n   * ```ts\n   * sentry: {\n   *   dsn: process.env.SENTRY_DSN,\n   * }\n   * ```\n   */\n  sentry?: {\n    /** Sentry DSN */\n    dsn: string\n    /** Environment override (defaults to event.environment) */\n    environment?: string\n    /** Release version override (defaults to event.version) */\n    release?: string\n    /** Additional tags to attach as attributes */\n    tags?: Record<string, string>\n    /** Request timeout in milliseconds. Default: 5000 */\n    timeout?: number\n  }\n\n  /**\n   * How long to retain events before cleanup (used by @mxllog/nuxthub).\n   * Supports \"30d\" (days), \"24h\" (hours), \"60m\" (minutes).\n   * @default '30d'\n   */\n  retention?: string\n}\n\nexport default defineNuxtModule<ModuleOptions>({\n  meta: {\n    name,\n    version,\n    configKey: name,\n    docs: 'https://mxllog.dev',\n  },\n  defaults: {},\n  setup(options, nuxt) {\n    const resolver = createResolver(import.meta.url)\n\n    const transportEnabled = options.transport?.enabled ?? false\n    const transportEndpoint = options.transport?.endpoint ?? '/api/_mxllog/ingest'\n\n    // Register custom error handler for proper MxllogError serialization\n    // Only set if not already configured to avoid overwriting user's custom handler\n    // @ts-expect-error nitro:config hook exists but is not in NuxtHooks type\n    nuxt.hook('nitro:config', (nitroConfig: NitroConfig) => {\n      nitroConfig.errorHandler = nitroConfig.errorHandler || resolver.resolve('../nitro/errorHandler')\n    })\n\n    nuxt.options.runtimeConfig.mxllog = options\n    nuxt.options.runtimeConfig.public.mxllog = {\n      enabled: options.enabled ?? true,\n      pretty: options.pretty,\n      transport: {\n        enabled: transportEnabled,\n        endpoint: transportEndpoint,\n      },\n    }\n\n    if (transportEnabled) {\n      addServerHandler({\n        route: transportEndpoint,\n        method: 'post',\n        handler: resolver.resolve('../runtime/server/routes/_mxllog/ingest.post'),\n      })\n    }\n\n    addServerPlugin(resolver.resolve('../nitro/plugin'))\n\n    addPlugin({\n      src: resolver.resolve('../runtime/client/plugin'),\n      mode: 'client',\n    })\n\n    addImports([\n      {\n        name: 'log',\n        from: resolver.resolve('../runtime/client/log'),\n      },\n      {\n        name: 'setIdentity',\n        from: resolver.resolve('../runtime/client/log'),\n      },\n      {\n        name: 'clearIdentity',\n        from: resolver.resolve('../runtime/client/log'),\n      },\n      {\n        name: 'createMxllogError',\n        from: resolver.resolve('../error'),\n      },\n      {\n        name: 'parseError',\n        from: resolver.resolve('../runtime/utils/parseError'),\n      },\n    ])\n\n    addServerImports([\n      {\n        name: 'useLogger',\n        from: resolver.resolve('../runtime/server/useLogger'),\n      },\n      {\n        name: 'log',\n        from: resolver.resolve('../logger'),\n      },\n      {\n        name: 'createMxllogError',\n        from: resolver.resolve('../error'),\n      },\n    ])\n  },\n})\n"],"mappings":";;;;;;;;AC0MA,qBAAe,iBAAgC;CAC7C,MAAM;EACJ;EACA;EACA,WAAW;EACX,MAAM;EACP;CACD,UAAU,EAAE;CACZ,MAAM,SAAS,MAAM;EACnB,MAAM,WAAW,eAAe,OAAO,KAAK,IAAI;EAEhD,MAAM,mBAAmB,QAAQ,WAAW,WAAW;EACvD,MAAM,oBAAoB,QAAQ,WAAW,YAAY;AAKzD,OAAK,KAAK,iBAAiB,gBAA6B;AACtD,eAAY,eAAe,YAAY,gBAAgB,SAAS,QAAQ,wBAAwB;IAChG;AAEF,OAAK,QAAQ,cAAc,SAAS;AACpC,OAAK,QAAQ,cAAc,OAAO,SAAS;GACzC,SAAS,QAAQ,WAAW;GAC5B,QAAQ,QAAQ;GAChB,WAAW;IACT,SAAS;IACT,UAAU;IACX;GACF;AAED,MAAI,iBACF,kBAAiB;GACf,OAAO;GACP,QAAQ;GACR,SAAS,SAAS,QAAQ,+CAA+C;GAC1E,CAAC;AAGJ,kBAAgB,SAAS,QAAQ,kBAAkB,CAAC;AAEpD,YAAU;GACR,KAAK,SAAS,QAAQ,2BAA2B;GACjD,MAAM;GACP,CAAC;AAEF,aAAW;GACT;IACE,MAAM;IACN,MAAM,SAAS,QAAQ,wBAAwB;IAChD;GACD;IACE,MAAM;IACN,MAAM,SAAS,QAAQ,wBAAwB;IAChD;GACD;IACE,MAAM;IACN,MAAM,SAAS,QAAQ,wBAAwB;IAChD;GACD;IACE,MAAM;IACN,MAAM,SAAS,QAAQ,WAAW;IACnC;GACD;IACE,MAAM;IACN,MAAM,SAAS,QAAQ,8BAA8B;IACtD;GACF,CAAC;AAEF,mBAAiB;GACf;IACE,MAAM;IACN,MAAM,SAAS,QAAQ,8BAA8B;IACtD;GACD;IACE,MAAM;IACN,MAAM,SAAS,QAAQ,YAAY;IACpC;GACD;IACE,MAAM;IACN,MAAM,SAAS,QAAQ,WAAW;IACnC;GACF,CAAC;;CAEL,CAAC"}

package/dist/pipeline.d.mts

@@ -0,0 +1,46 @@
+//#region src/pipeline.d.ts
+interface DrainPipelineOptions<T = unknown> {
+  batch?: {
+    /** Maximum number of events per batch sent to the drain function. @default 50 */size?: number; /** Maximum time (ms) an event can stay buffered before a flush is triggered, even if the batch is not full. @default 5000 */
+    intervalMs?: number;
+  };
+  retry?: {
+    /** Total number of attempts (including the initial one) before dropping the batch. @default 3 */maxAttempts?: number; /** Delay strategy between retry attempts. @default 'exponential' */
+    backoff?: 'exponential' | 'linear' | 'fixed'; /** Base delay (ms) for the first retry. Scaled by the backoff strategy on subsequent retries. @default 1000 */
+    initialDelayMs?: number; /** Upper bound (ms) for any single retry delay. @default 30000 */
+    maxDelayMs?: number;
+  };
+  /** Maximum number of events held in the buffer. When exceeded, the oldest event is dropped. @default 1000 */
+  maxBufferSize?: number;
+  /** Called when a batch is dropped after all retry attempts are exhausted, or when the buffer overflows. */
+  onDropped?: (events: T[], error?: Error) => void;
+}
+interface PipelineDrainFn<T> {
+  (ctx: T): void;
+  /** Flush all buffered events. Call on server shutdown. */
+  flush: () => Promise<void>;
+  readonly pending: number;
+}
+/**
+ * Create a drain pipeline that batches events, retries on failure, and manages buffer overflow.
+ *
+ * Returns a higher-order function: pass your drain adapter to get a hook-compatible function.
+ *
+ * @example
+ * ```ts
+ * const pipeline = createDrainPipeline({ batch: { size: 50 } })
+ * const drain = pipeline(async (batch) => {
+ *   await sendToBackend(batch)
+ * })
+ *
+ * // Use as a hook
+ * nitroApp.hooks.hook('@safaricom-mxl/log:drain', drain)
+ *
+ * // Flush on shutdown
+ * nitroApp.hooks.hook('close', () => drain.flush())
+ * ```
+ */
+declare function createDrainPipeline<T = unknown>(options?: DrainPipelineOptions<T>): (drain: (batch: T[]) => void | Promise<void>) => PipelineDrainFn<T>;
+//#endregion
+export { DrainPipelineOptions, PipelineDrainFn, createDrainPipeline };
+//# sourceMappingURL=pipeline.d.mts.map

package/dist/pipeline.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.mts","names":[],"sources":["../src/pipeline.ts"],"mappings":";UAAiB,oBAAA;EACf,KAAA;IADmC,iFAGjC,IAAA,WAiBqC;IAfrC,UAAA;EAAA;EAEF,KAAA;IAFE,iGAIA,WAAA,WAAA;IAEA,OAAA,uCAEA;IAAA,cAAA,WAKF;IAHE,UAAA;EAAA;EAKW;EAFb,aAAA;EAE0B;EAA1B,SAAA,IAAa,MAAA,EAAQ,CAAA,IAAK,KAAA,GAAQ,KAAA;AAAA;AAAA,UAGnB,eAAA;EAAA,CACd,GAAA,EAAK,CAAA;EADwB;EAG9B,KAAA,QAAa,OAAA;EAAA,SACJ,OAAA;AAAA;;;;;;;AAsBX;;;;;;;;;;;;;iBAAgB,mBAAA,aAAA,CAAiC,OAAA,GAAU,oBAAA,CAAqB,CAAA,KAAM,KAAA,GAAQ,KAAA,EAAO,CAAA,cAAe,OAAA,WAAkB,eAAA,CAAgB,CAAA"}

package/dist/pipeline.mjs

@@ -0,0 +1,122 @@
+//#region src/pipeline.ts
+/**
+* Create a drain pipeline that batches events, retries on failure, and manages buffer overflow.
+*
+* Returns a higher-order function: pass your drain adapter to get a hook-compatible function.
+*
+* @example
+* ```ts
+* const pipeline = createDrainPipeline({ batch: { size: 50 } })
+* const drain = pipeline(async (batch) => {
+*   await sendToBackend(batch)
+* })
+*
+* // Use as a hook
+* nitroApp.hooks.hook('@safaricom-mxl/log:drain', drain)
+*
+* // Flush on shutdown
+* nitroApp.hooks.hook('close', () => drain.flush())
+* ```
+*/
+function createDrainPipeline(options) {
+	const batchSize = options?.batch?.size ?? 50;
+	const intervalMs = options?.batch?.intervalMs ?? 5e3;
+	const maxBufferSize = options?.maxBufferSize ?? 1e3;
+	const maxAttempts = options?.retry?.maxAttempts ?? 3;
+	const backoffStrategy = options?.retry?.backoff ?? "exponential";
+	const initialDelayMs = options?.retry?.initialDelayMs ?? 1e3;
+	const maxDelayMs = options?.retry?.maxDelayMs ?? 3e4;
+	const onDropped = options?.onDropped;
+	if (batchSize <= 0 || !Number.isFinite(batchSize)) throw new Error(`[mxllog/pipeline] batch.size must be a positive finite number, got: ${batchSize}`);
+	if (intervalMs <= 0 || !Number.isFinite(intervalMs)) throw new Error(`[mxllog/pipeline] batch.intervalMs must be a positive finite number, got: ${intervalMs}`);
+	if (maxBufferSize <= 0 || !Number.isFinite(maxBufferSize)) throw new Error(`[mxllog/pipeline] maxBufferSize must be a positive finite number, got: ${maxBufferSize}`);
+	if (maxAttempts <= 0 || !Number.isFinite(maxAttempts)) throw new Error(`[mxllog/pipeline] retry.maxAttempts must be a positive finite number, got: ${maxAttempts}`);
+	if (initialDelayMs < 0 || !Number.isFinite(initialDelayMs)) throw new Error(`[mxllog/pipeline] retry.initialDelayMs must be a non-negative finite number, got: ${initialDelayMs}`);
+	if (maxDelayMs < 0 || !Number.isFinite(maxDelayMs)) throw new Error(`[mxllog/pipeline] retry.maxDelayMs must be a non-negative finite number, got: ${maxDelayMs}`);
+	return (drain) => {
+		const buffer = [];
+		let timer = null;
+		let activeFlush = null;
+		function clearTimer() {
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		}
+		function scheduleFlush() {
+			if (timer !== null || activeFlush) return;
+			timer = setTimeout(() => {
+				timer = null;
+				if (!activeFlush) startFlush();
+			}, intervalMs);
+		}
+		function getRetryDelay(attempt) {
+			let delay;
+			switch (backoffStrategy) {
+				case "linear":
+					delay = initialDelayMs * attempt;
+					break;
+				case "fixed":
+					delay = initialDelayMs;
+					break;
+				default:
+					delay = initialDelayMs * 2 ** (attempt - 1);
+					break;
+			}
+			return Math.min(delay, maxDelayMs);
+		}
+		async function sendWithRetry(batch) {
+			let lastError;
+			for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
+				await drain(batch);
+				return;
+			} catch (error) {
+				lastError = error instanceof Error ? error : new Error(String(error));
+				if (attempt < maxAttempts) await new Promise((r) => setTimeout(r, getRetryDelay(attempt)));
+			}
+			onDropped?.(batch, lastError);
+		}
+		async function drainBuffer() {
+			while (buffer.length > 0) await sendWithRetry(buffer.splice(0, batchSize));
+		}
+		function startFlush() {
+			if (activeFlush) return;
+			activeFlush = drainBuffer().finally(() => {
+				activeFlush = null;
+				if (buffer.length >= batchSize) startFlush();
+				else if (buffer.length > 0) scheduleFlush();
+			});
+		}
+		function push(ctx) {
+			if (buffer.length >= maxBufferSize) {
+				const dropped = buffer.splice(0, 1);
+				onDropped?.(dropped);
+			}
+			buffer.push(ctx);
+			if (buffer.length >= batchSize) {
+				clearTimer();
+				startFlush();
+			} else if (!activeFlush) scheduleFlush();
+		}
+		async function flush() {
+			clearTimer();
+			if (activeFlush) await activeFlush;
+			const snapshot = buffer.length;
+			if (snapshot > 0) {
+				const toFlush = buffer.splice(0, snapshot);
+				while (toFlush.length > 0) await sendWithRetry(toFlush.splice(0, batchSize));
+			}
+		}
+		const hookFn = push;
+		hookFn.flush = flush;
+		Object.defineProperty(hookFn, "pending", {
+			get: () => buffer.length,
+			enumerable: true
+		});
+		return hookFn;
+	};
+}
+
+//#endregion
+export { createDrainPipeline };
+//# sourceMappingURL=pipeline.mjs.map

package/dist/pipeline.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.mjs","names":[],"sources":["../src/pipeline.ts"],"sourcesContent":["export interface DrainPipelineOptions<T = unknown> {\n  batch?: {\n    /** Maximum number of events per batch sent to the drain function. @default 50 */\n    size?: number\n    /** Maximum time (ms) an event can stay buffered before a flush is triggered, even if the batch is not full. @default 5000 */\n    intervalMs?: number\n  }\n  retry?: {\n    /** Total number of attempts (including the initial one) before dropping the batch. @default 3 */\n    maxAttempts?: number\n    /** Delay strategy between retry attempts. @default 'exponential' */\n    backoff?: 'exponential' | 'linear' | 'fixed'\n    /** Base delay (ms) for the first retry. Scaled by the backoff strategy on subsequent retries. @default 1000 */\n    initialDelayMs?: number\n    /** Upper bound (ms) for any single retry delay. @default 30000 */\n    maxDelayMs?: number\n  }\n  /** Maximum number of events held in the buffer. When exceeded, the oldest event is dropped. @default 1000 */\n  maxBufferSize?: number\n  /** Called when a batch is dropped after all retry attempts are exhausted, or when the buffer overflows. */\n  onDropped?: (events: T[], error?: Error) => void\n}\n\nexport interface PipelineDrainFn<T> {\n  (ctx: T): void\n  /** Flush all buffered events. Call on server shutdown. */\n  flush: () => Promise<void>\n  readonly pending: number\n}\n\n/**\n * Create a drain pipeline that batches events, retries on failure, and manages buffer overflow.\n *\n * Returns a higher-order function: pass your drain adapter to get a hook-compatible function.\n *\n * @example\n * ```ts\n * const pipeline = createDrainPipeline({ batch: { size: 50 } })\n * const drain = pipeline(async (batch) => {\n *   await sendToBackend(batch)\n * })\n *\n * // Use as a hook\n * nitroApp.hooks.hook('@safaricom-mxl/log:drain', drain)\n *\n * // Flush on shutdown\n * nitroApp.hooks.hook('close', () => drain.flush())\n * ```\n */\nexport function createDrainPipeline<T = unknown>(options?: DrainPipelineOptions<T>): (drain: (batch: T[]) => void | Promise<void>) => PipelineDrainFn<T> {\n  const batchSize = options?.batch?.size ?? 50\n  const intervalMs = options?.batch?.intervalMs ?? 5000\n  const maxBufferSize = options?.maxBufferSize ?? 1000\n  const maxAttempts = options?.retry?.maxAttempts ?? 3\n  const backoffStrategy = options?.retry?.backoff ?? 'exponential'\n  const initialDelayMs = options?.retry?.initialDelayMs ?? 1000\n  const maxDelayMs = options?.retry?.maxDelayMs ?? 30000\n  const onDropped = options?.onDropped\n\n  if (batchSize <= 0 || !Number.isFinite(batchSize)) {\n    throw new Error(`[mxllog/pipeline] batch.size must be a positive finite number, got: ${batchSize}`)\n  }\n  if (intervalMs <= 0 || !Number.isFinite(intervalMs)) {\n    throw new Error(`[mxllog/pipeline] batch.intervalMs must be a positive finite number, got: ${intervalMs}`)\n  }\n  if (maxBufferSize <= 0 || !Number.isFinite(maxBufferSize)) {\n    throw new Error(`[mxllog/pipeline] maxBufferSize must be a positive finite number, got: ${maxBufferSize}`)\n  }\n  if (maxAttempts <= 0 || !Number.isFinite(maxAttempts)) {\n    throw new Error(`[mxllog/pipeline] retry.maxAttempts must be a positive finite number, got: ${maxAttempts}`)\n  }\n  if (initialDelayMs < 0 || !Number.isFinite(initialDelayMs)) {\n    throw new Error(`[mxllog/pipeline] retry.initialDelayMs must be a non-negative finite number, got: ${initialDelayMs}`)\n  }\n  if (maxDelayMs < 0 || !Number.isFinite(maxDelayMs)) {\n    throw new Error(`[mxllog/pipeline] retry.maxDelayMs must be a non-negative finite number, got: ${maxDelayMs}`)\n  }\n\n  return (drain: (batch: T[]) => void | Promise<void>): PipelineDrainFn<T> => {\n    const buffer: T[] = []\n    let timer: ReturnType<typeof setTimeout> | null = null\n    let activeFlush: Promise<void> | null = null\n\n    function clearTimer(): void {\n      if (timer !== null) {\n        clearTimeout(timer)\n        timer = null\n      }\n    }\n\n    function scheduleFlush(): void {\n      if (timer !== null || activeFlush) return\n      timer = setTimeout(() => {\n        timer = null\n        if (!activeFlush) startFlush()\n      }, intervalMs)\n    }\n\n    function getRetryDelay(attempt: number): number {\n      let delay: number\n      switch (backoffStrategy) {\n        case 'linear':\n          delay = initialDelayMs * attempt\n          break\n        case 'fixed':\n          delay = initialDelayMs\n          break\n        case 'exponential':\n        default:\n          delay = initialDelayMs * 2 ** (attempt - 1)\n          break\n      }\n      return Math.min(delay, maxDelayMs)\n    }\n\n    async function sendWithRetry(batch: T[]): Promise<void> {\n      let lastError: Error | undefined\n      for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n        try {\n          await drain(batch)\n          return\n        } catch (error) {\n          lastError = error instanceof Error ? error : new Error(String(error))\n          if (attempt < maxAttempts) {\n            await new Promise<void>(r => setTimeout(r, getRetryDelay(attempt)))\n          }\n        }\n      }\n      onDropped?.(batch, lastError)\n    }\n\n    async function drainBuffer(): Promise<void> {\n      while (buffer.length > 0) {\n        const batch = buffer.splice(0, batchSize)\n        await sendWithRetry(batch)\n      }\n    }\n\n    function startFlush(): void {\n      if (activeFlush) return\n      activeFlush = drainBuffer().finally(() => {\n        activeFlush = null\n        if (buffer.length >= batchSize) {\n          startFlush()\n        } else if (buffer.length > 0) {\n          scheduleFlush()\n        }\n      })\n    }\n\n    function push(ctx: T): void {\n      if (buffer.length >= maxBufferSize) {\n        const dropped = buffer.splice(0, 1)\n        onDropped?.(dropped)\n      }\n      buffer.push(ctx)\n\n      if (buffer.length >= batchSize) {\n        clearTimer()\n        startFlush()\n      } else if (!activeFlush) {\n        scheduleFlush()\n      }\n    }\n\n    async function flush(): Promise<void> {\n      clearTimer()\n      if (activeFlush) {\n        await activeFlush\n      }\n      // Snapshot the buffer length to avoid infinite loop if push() is called during flush\n      const snapshot = buffer.length\n      if (snapshot > 0) {\n        const toFlush = buffer.splice(0, snapshot)\n        while (toFlush.length > 0) {\n          const batch = toFlush.splice(0, batchSize)\n          await sendWithRetry(batch)\n        }\n      }\n    }\n\n    const hookFn = push as PipelineDrainFn<T>\n    hookFn.flush = flush\n    Object.defineProperty(hookFn, 'pending', {\n      get: () => buffer.length,\n      enumerable: true,\n    })\n\n    return hookFn\n  }\n}\n"],"mappings":"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"}