@joinremba/catalog 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,298 @@
+# @joinremba/catalog
+
+[![npm version](https://img.shields.io/npm/v/@joinremba/catalog)](https://www.npmjs.com/package/@joinremba/catalog)
+[![Licence](https://img.shields.io/npm/l/@joinremba/catalog)](LICENSE)
+[![CI](https://github.com/joinremba/catalog/actions/workflows/ci.yml/badge.svg)](https://github.com/joinremba/catalog/actions/workflows/ci.yml)
+[![Bun](https://img.shields.io/badge/bun-1.3%2B-%23ffc83d?logo=bun)](https://bun.sh)
+
+Catalog is a production-ready logging and error event layer for TypeScript backends, built on [Pino](https://getpino.io/).
+
+## Features
+
+- **Event-name-first API** — Log with descriptive event names: `catalog.info("wallet.created", { userId })`. Events are indexed, searchable, and consistent across your codebase.
+- **Pino-based** — Ultra-fast structured JSON logging with full Pino ecosystem support.
+- **Sensitive data redaction** — Automatically redacts PII, secrets, and credentials from log output via configurable path patterns.
+- **Multi-transport** — Route logs to console, file, rolling files, or external services based on environment.
+- **Request context** — Correlate logs with request IDs via child loggers.
+- **Error serializer** — Standardised error serialization for consistent error objects in logs.
+- **HTTP request logging** — Middleware for automatic request/response logging.
+- **Environment-aware** — Pretty printing in development, structured JSON and file rolling in production.
+- **Framework adapters** — Plug into Express, Hono, Fastify, or any Bun-native server.
+
+## Installation
+
+```sh
+bun add @joinremba/catalog
+```
+
+## Quick Start
+
+```ts
+import { createCatalog } from "@joinremba/catalog";
+
+const catalog = createCatalog({
+  service: "@joinremba/api",
+  environment: process.env.NODE_ENV,
+  redact: ["authorization", "password", "bvn", "nin"],
+});
+
+catalog.info("wallet.created", { userId, walletId });
+catalog.error("payment.failed", { amount: 100, error: err.message });
+```
+
+## API Reference
+
+### `createCatalog(options)`
+
+Creates and returns a configured Catalog instance. It is the main entry point for the package.
+
+#### Options
+
+| Option        | Type                                     | Default               | Description                                            |
+| ------------- | ---------------------------------------- | --------------------- | ------------------------------------------------------ |
+| `service`     | `string`                                 | —                     | Application or service name, included in every log.    |
+| `environment` | `string`                                 | —                     | Environment name (e.g. `"production"`, `"staging"`).   |
+| `level`       | `LogLevel`                               | `"info"`              | Minimum log level.                                     |
+| `redact`      | `string[]`                               | —                     | Paths to redact (e.g. `["password", "creditCard.*"]`). |
+| `transport`   | `TransportOptions \| TransportOptions[]` | Pino default (stdout) | Single or array of transport configurations.           |
+
+#### Log Levels
+
+| Method               | Use                   |
+| -------------------- | --------------------- |
+| `catalog.trace(...)` | Trace-level logging   |
+| `catalog.debug(...)` | Debug-level logging   |
+| `catalog.info(...)`  | Informational logging |
+| `catalog.warn(...)`  | Warning logging       |
+| `catalog.error(...)` | Error logging         |
+| `catalog.fatal(...)` | Fatal logging         |
+
+Each method accepts an event name (string) and an optional data object:
+
+```ts
+catalog.info("user.signed-in", { userId: 42 });
+catalog.error("db.connection-failed", { err });
+catalog.info("app.started"); // event name only
+```
+
+### Child Loggers
+
+Create a child logger that inherits the parent's configuration and adds bound fields:
+
+```ts
+const catalog = createCatalog({ service: "app" });
+const reqLog = catalog.child({ requestId: "abc-123" });
+
+reqLog.info("request.handled", { path: "/api/users" });
+// Includes requestId: "abc-123" in every log
+```
+
+### Redaction
+
+Sensitive data is automatically redacted from log output. Configure paths using dot notation:
+
+```ts
+const catalog = createCatalog({
+  service: "secure-app",
+  redact: ["password", "creditCard.number", "ssn", "authorization"],
+});
+
+catalog.info("user.login", { userId: 42, password: "secret" });
+// password is redacted as [REDACTED]
+```
+
+### Multi-transport
+
+Route logs to multiple destinations:
+
+```ts
+const catalog = createCatalog({
+  service: "my-app",
+  transport: [
+    { target: "pino/file", options: {} }, // stdout
+    { target: "pino/file", options: { destination: "./logs/app.log" } }, // file
+    { target: "pino-roll", options: { file: "./logs/out.log", frequency: "daily" } }, // rolling
+  ],
+});
+```
+
+### Error Serializer
+
+Catalog includes a built-in error serializer that converts `Error` instances into structured objects:
+
+```ts
+try {
+  await riskyOperation();
+} catch (err) {
+  catalog.error("operation.failed", { error: err });
+  // error is serialised: { message, name, stack, cause }
+}
+```
+
+### Safe Error Response Helper
+
+For API backends, Catalog provides helpers to build safe error responses without leaking internals:
+
+```ts
+import { safeError } from "@joinremba/catalog";
+
+app.onError((err, c) => {
+  catalog.error("request.error", { error: err });
+  return c.json(safeError(err), 500);
+});
+```
+
+## Middleware
+
+### Request ID Middleware
+
+Automatically generates or extracts a request ID and binds it to all logs within a request:
+
+```ts
+import { requestId } from "@joinremba/catalog";
+import { createCatalog } from "@joinremba/catalog";
+
+const catalog = createCatalog({ service: "my-api" });
+
+// Express
+app.use(requestId({ header: "X-Request-Id" }));
+app.use((req, res, next) => {
+  const log = catalog.child({ requestId: req.headers["x-request-id"] });
+  req.log = log;
+  next();
+});
+```
+
+### HTTP Request Logger
+
+Automatically log incoming requests and responses:
+
+```ts
+import { httpLogger } from "@joinremba/catalog";
+
+// Express
+app.use(httpLogger({ catalog, excludePaths: ["/health"] }));
+```
+
+## Framework Adapters
+
+Catalog is framework-agnostic but ships with adapters for popular frameworks:
+
+```ts
+// Express
+import { expressAdapter } from "@joinremba/catalog/adapters/express";
+
+// Hono
+import { honoAdapter } from "@joinremba/catalog/adapters/hono";
+
+// Fastify
+import { fastifyAdapter } from "@joinremba/catalog/adapters/fastify";
+```
+
+Adapters automatically configure request ID tracking, error serialization, and HTTP logging for the target framework.
+
+## TypeScript Types
+
+```ts
+import type { Catalog, LogLevel, CatalogOptions, TransportOptions } from "@joinremba/catalog";
+```
+
+| Type               | Description                                                            |
+| ------------------ | ---------------------------------------------------------------------- |
+| `Catalog`          | The logger instance type.                                              |
+| `LogLevel`         | Union: `"trace" \| "debug" \| "info" \| "warn" \| "error" \| "fatal"`. |
+| `CatalogOptions`   | Options object passed to `createCatalog`.                              |
+| `TransportOptions` | Transport configuration with `target` and `options`.                   |
+
+## Examples
+
+### Basic usage
+
+```ts
+import { createCatalog } from "@joinremba/catalog";
+
+const catalog = createCatalog({ service: "my-service" });
+
+catalog.info("service.starting");
+catalog.debug("config.loaded", { port: 3000 });
+```
+
+### With request context
+
+```ts
+import { createCatalog } from "@joinremba/catalog";
+
+const catalog = createCatalog({ service: "web-app" });
+
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    const log = catalog.child({ requestId: crypto.randomUUID() });
+    log.info("request.incoming", { url: req.url });
+    return new Response("OK");
+  },
+});
+```
+
+### Environment-aware config
+
+```ts
+const catalog = createCatalog({
+  service: "my-app",
+  environment: process.env.NODE_ENV,
+  level: process.env.NODE_ENV === "production" ? "info" : "debug",
+  transport:
+    process.env.NODE_ENV === "production"
+      ? [
+          { target: "pino/file", options: { destination: "./logs/app.log" } },
+          { target: "pino-roll", options: { file: "./logs/out.log", frequency: "daily" } },
+        ]
+      : undefined, // pretty-print to console in dev
+});
+```
+
+## Roadmap
+
+**MVP** (current)
+
+- Pino wrapper with event-name-first API
+- Sensitive data redaction with configurable paths
+- Child loggers with bound context
+- Multi-transport support
+- Error serializer
+- Safe error response helper
+
+**V1**
+
+- Request ID middleware
+- HTTP request logging middleware
+- Express, Hono, Fastify adapters
+- Audit event module (`catalog.audit()`)
+- Security event module (`catalog.security()`)
+- Webhook event module
+- Payment-safe log redaction defaults
+- Local pretty log viewer
+- OpenTelemetry bridge
+- Log sampling
+
+**V2**
+
+- Hosted log ingestion
+- Dashboards and alerts
+- Retention policies
+- Compliance exports
+- Audit-log immutability
+- Team access controls
+
+## Related Packages
+
+- [@joinremba/beacon](https://github.com/joinremba/beacon) — Environment validation, config, secrets, and feature gates.
+- [@joinremba/gate](https://github.com/joinremba/gate) — API safety layer: validation, responses, idempotency, rate limiting, and API keys.
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@joinremba/catalog",
+  "version": "0.2.0",
+  "description": "Production-ready logging and error event layer for TypeScript backends, built on Pino.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./audit": {
+      "types": "./src/audit.ts",
+      "import": "./src/audit.ts",
+      "default": "./src/audit.ts"
+    },
+    "./security": {
+      "types": "./src/security.ts",
+      "import": "./src/security.ts",
+      "default": "./src/security.ts"
+    },
+    "./adapters/hono": {
+      "types": "./src/adapters/hono.ts",
+      "import": "./src/adapters/hono.ts",
+      "default": "./src/adapters/hono.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --format esm",
+    "dev": "bun --watch ./src/index.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "prepublishOnly": "bun run build",
+    "check": "bun lint && bun format:check && bun typecheck && bun test"
+  },
+  "author": {
+    "name": "Benson Isaac",
+    "email": "bensxnisaac@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joinremba/catalog.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joinremba/catalog/issues"
+  },
+  "homepage": "https://github.com/joinremba/catalog#readme",
+  "keywords": [
+    "logging",
+    "pino",
+    "logger",
+    "structured-logging",
+    "error-tracking",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.1"
+  },
+  "dependencies": {
+    "pino": "^10.3.1",
+    "pino-roll": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "pino-pretty": "^13.1.3",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/adapters/hono.test.ts

@@ -0,0 +1,62 @@
+import { expect, test } from "bun:test";
+import { createCatalog } from "../index";
+import { requestIdMiddleware, httpLoggerMiddleware } from "./hono";
+
+interface MockCtx {
+  req: {
+    method: string;
+    path: string;
+    header(name: string): string | undefined;
+    query(): Record<string, string | undefined>;
+  };
+  get(key: string): unknown;
+  set(key: string, val: unknown): void;
+  res?: { status: number };
+}
+
+function mockHonoContext(overrides?: {
+  path?: string;
+  header?: (name: string) => string | undefined;
+}): MockCtx {
+  const store: Record<string, unknown> = {};
+  return {
+    req: {
+      method: "GET",
+      path: overrides?.path ?? "/api/users",
+      header: overrides?.header ?? ((_name: string) => undefined),
+      query: () => ({}),
+    },
+    get: (key: string) => store[key],
+    set: (key: string, val: unknown) => {
+      store[key] = val;
+    },
+  };
+}
+
+test("requestIdMiddleware sets requestId on context", async () => {
+  const catalog = createCatalog({ service: "test" });
+  const c = mockHonoContext();
+  let called = false;
+  await requestIdMiddleware(catalog)(c, async () => {
+    called = true;
+  });
+  expect(c.get("requestId")).toBeDefined();
+  expect(called).toBe(true);
+});
+
+test("requestIdMiddleware preserves existing x-request-id header", async () => {
+  const catalog = createCatalog({ service: "test" });
+  const c = mockHonoContext({ header: () => "from-header" });
+  await requestIdMiddleware(catalog)(c, async () => {});
+  expect(c.get("requestId")).toBe("from-header");
+});
+
+test("httpLoggerMiddleware skips excluded paths", async () => {
+  const catalog = createCatalog({ service: "test" });
+  const c = mockHonoContext({ path: "/health" });
+  let called = false;
+  await httpLoggerMiddleware(catalog)(c, async () => {
+    called = true;
+  });
+  expect(called).toBe(true);
+});

package/src/adapters/hono.ts

@@ -0,0 +1,74 @@
+import type { Catalog } from "../index";
+
+interface HonoContext {
+  req: {
+    method: string;
+    path: string;
+    header(name: string): string | undefined;
+    query(): Record<string, string | undefined>;
+  };
+  get(key: string): unknown;
+  set(key: string, val: unknown): void;
+  res?: { status: number };
+}
+
+export interface HonoRequestIdOptions {
+  header?: string;
+  generate?: () => string;
+}
+
+export function requestIdMiddleware(catalog: Catalog, options?: HonoRequestIdOptions) {
+  const headerName = options?.header?.toLowerCase() ?? "x-request-id";
+  const generate = options?.generate ?? (() => crypto.randomUUID());
+
+  return (c: HonoContext, next: () => Promise<void>) => {
+    const existing = c.req.header(headerName) ?? c.req.header("x-request-id");
+    const requestId = existing ?? generate();
+    c.set("requestId", requestId);
+    return next();
+  };
+}
+
+export interface HttpLogOptions {
+  excludePaths?: string[];
+  logBody?: boolean;
+  maxBodyLength?: number;
+}
+
+export function httpLoggerMiddleware(catalog: Catalog, options?: HttpLogOptions) {
+  const exclude = new Set(options?.excludePaths ?? ["/health", "/favicon.ico"]);
+
+  return (c: HonoContext, next: () => Promise<void>) => {
+    if (exclude.has(c.req.path)) return next();
+
+    const requestId = c.get("requestId") as string | undefined;
+    const log = requestId ? catalog.child({ requestId }) : catalog;
+    const start = performance.now();
+    const method = c.req.method;
+    const path = c.req.path;
+
+    log.info({
+      message: `--> ${method} ${path}`,
+      method,
+      path,
+      query: Object.fromEntries(Object.entries(c.req.query()).filter(([, v]) => v !== undefined)),
+      userAgent: c.req.header("user-agent"),
+    });
+
+    return next().then(() => {
+      const duration = ((performance.now() - start) * 1000).toFixed(2);
+      const status = c.res?.status ?? 200;
+      const level = status >= 500 ? "error" : status >= 400 ? "warn" : "info";
+
+      const logData = {
+        message: `<-- ${method} ${path} ${status} ${duration}ms`,
+        status,
+        durationMs: duration,
+      };
+
+      if (level === "info") log.info(logData);
+      else if (level === "warn") log.warn(logData);
+      else log.error(logData);
+    });
+  };
+}

package/src/audit.test.ts

@@ -0,0 +1,17 @@
+import { expect, test } from "bun:test";
+import { createCatalog } from "./index";
+import { auditLogger } from "./audit";
+
+test("auditLogger logs audit event", () => {
+  const catalog = createCatalog({ service: "test" });
+  const audit = auditLogger(catalog);
+  expect(() =>
+    audit.log({
+      action: "user.deleted",
+      actor: "admin@example.com",
+      resource: "user",
+      resourceId: "42",
+      outcome: "success",
+    })
+  ).not.toThrow();
+});

package/src/audit.ts

@@ -0,0 +1,27 @@
+import type { Catalog } from "./index";
+
+export interface AuditEvent {
+  action: string;
+  actor: string;
+  resource: string;
+  resourceId?: string;
+  details?: Record<string, unknown>;
+  outcome: "success" | "failure";
+  reason?: string;
+}
+
+export function auditLogger(catalog: Catalog) {
+  return {
+    log(event: AuditEvent) {
+      catalog.info("audit." + event.action, {
+        audit: true,
+        actor: event.actor,
+        resource: event.resource,
+        resourceId: event.resourceId,
+        details: event.details,
+        outcome: event.outcome,
+        reason: event.reason,
+      });
+    },
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,87 @@
+import { expect, test } from "bun:test";
+import { createCatalog } from "./index";
+
+test("creates a catalog instance", () => {
+  const catalog = createCatalog({ service: "test-service" });
+  expect(catalog).toBeDefined();
+  expect(typeof catalog.info).toBe("function");
+});
+
+test("logs info with event name (event-name-first)", () => {
+  const catalog = createCatalog({ service: "test", level: "info" });
+  expect(() => catalog.info("user.created", { userId: "42" })).not.toThrow();
+});
+
+test("logs with object style (standard pino)", () => {
+  const catalog = createCatalog({ service: "test", level: "info" });
+  expect(() => catalog.info({ userId: "42", message: "User created" })).not.toThrow();
+});
+
+test("logs error with event name", () => {
+  const catalog = createCatalog({ service: "test", level: "error" });
+  expect(() => catalog.error("payment.failed", { amount: 100 })).not.toThrow();
+});
+
+test("logs with just an event name (no data)", () => {
+  const catalog = createCatalog({ service: "test" });
+  expect(() => catalog.info("app.started")).not.toThrow();
+});
+
+test("respects log level", () => {
+  const catalog = createCatalog({ service: "test", level: "warn" });
+  expect(catalog.level).toBe("warn");
+});
+
+test("creates child logger with bound fields", () => {
+  const catalog = createCatalog({ service: "app" });
+  const child = catalog.child({ requestId: "abc-123" });
+  expect(child).toBeDefined();
+  expect(typeof child.info).toBe("function");
+});
+
+test("child logger logs without errors", () => {
+  const catalog = createCatalog({ service: "app" });
+  const child = catalog.child({ requestId: "abc-123" });
+  expect(() => child.info("request.handled", { path: "/api" })).not.toThrow();
+});
+
+test("child logger supports object style", () => {
+  const catalog = createCatalog({ service: "app" });
+  const child = catalog.child({ requestId: "abc-123" });
+  expect(() => child.info({ path: "/api", method: "GET" })).not.toThrow();
+});
+
+test("redacts sensitive fields", () => {
+  const catalog = createCatalog({ service: "secure-app" });
+  expect(() => catalog.info("user.login", { userId: "1", password: "secret" })).not.toThrow();
+});
+
+test("redacts sensitive fields in object style", () => {
+  const catalog = createCatalog({ service: "secure-app" });
+  expect(() => catalog.info({ userId: "1", password: "secret", email: "a@b.com" })).not.toThrow();
+});
+
+test("handles multiple transport targets", () => {
+  const catalog = createCatalog({
+    service: "multi-transport",
+    transport: [{ target: "pino/file", options: {} }],
+  });
+  expect(() => catalog.info("app.started")).not.toThrow();
+});
+
+test("uses mixin for context injection", () => {
+  const catalog = createCatalog({
+    service: "with-mixin",
+    mixin: () => ({ requestId: "abc-123" }),
+  });
+  expect(() => catalog.info("request.started")).not.toThrow();
+});
+
+test("child logger inherits mixin", () => {
+  const catalog = createCatalog({
+    service: "with-mixin",
+    mixin: () => ({ requestId: "abc-123" }),
+  });
+  const child = catalog.child({ userId: "42" });
+  expect(() => child.info("user.action")).not.toThrow();
+});

package/src/index.ts

@@ -0,0 +1,180 @@
+import pino from "pino";
+import type { Logger as PinoLogger, Level as PinoLevel, LoggerOptions } from "pino";
+
+export type LogLevel = PinoLevel;
+
+export interface TransportOptions {
+  target: string;
+  options?: Record<string, unknown>;
+}
+
+export interface CatalogOptions {
+  service: string;
+  level?: LogLevel;
+  redact?: string[];
+  redactPaths?: string[];
+  transport?: TransportOptions | TransportOptions[];
+  mixin?: () => Record<string, unknown>;
+  base?: Record<string, unknown>;
+  environment?: string;
+}
+
+export interface Catalog {
+  trace(msg: string, data?: Record<string, unknown>): void;
+  trace(data: Record<string, unknown>): void;
+  debug(msg: string, data?: Record<string, unknown>): void;
+  debug(data: Record<string, unknown>): void;
+  info(msg: string, data?: Record<string, unknown>): void;
+  info(data: Record<string, unknown>): void;
+  warn(msg: string, data?: Record<string, unknown>): void;
+  warn(data: Record<string, unknown>): void;
+  error(msg: string, data?: Record<string, unknown>): void;
+  error(data: Record<string, unknown>): void;
+  fatal(msg: string, data?: Record<string, unknown>): void;
+  fatal(data: Record<string, unknown>): void;
+  child(bindings: Record<string, unknown>): Catalog;
+  readonly level: LogLevel;
+}
+
+const SENSITIVE_FIELDS = new Set([
+  "password",
+  "passwordHash",
+  "secret",
+  "apiKey",
+  "apiSecret",
+  "token",
+  "accessToken",
+  "refreshToken",
+  "idToken",
+  "ssn",
+  "taxId",
+  "passportNumber",
+  "driverLicense",
+  "phone",
+  "phoneNumber",
+  "mobile",
+  "email",
+  "emailAddress",
+  "accountNumber",
+  "routingNumber",
+  "iban",
+  "swift",
+  "cardNumber",
+  "cvv",
+  "cvc",
+  "expiryDate",
+  "pin",
+  "bvn",
+  "nin",
+  "bvnHash",
+  "ninHash",
+  "ip",
+  "ipAddress",
+  "userAgent",
+  "firstName",
+  "lastName",
+  "fullName",
+  "dateOfBirth",
+  "dob",
+  "address",
+  "location",
+  "otp",
+  "securityAnswer",
+]);
+
+function redactFields(
+  data: Record<string, unknown>,
+  extraFields?: Set<string>
+): Record<string, unknown> {
+  const fields = extraFields ? new Set([...SENSITIVE_FIELDS, ...extraFields]) : SENSITIVE_FIELDS;
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (fields.has(key) || fields.has(key.toLowerCase())) {
+      result[key] = "[REDACTED]";
+    } else if (
+      typeof value === "object" &&
+      value !== null &&
+      !Array.isArray(value) &&
+      !(value instanceof Error)
+    ) {
+      result[key] = redactFields(value as Record<string, unknown>, fields);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+const serializer: LoggerOptions["serializers"] = {
+  err: pino.stdSerializers.err,
+  error: pino.stdSerializers.err,
+};
+
+export function createCatalog(options: CatalogOptions): Catalog {
+  const { service, level, redact, redactPaths, transport, mixin, base } = options;
+  const extraRedactFields = redact ? new Set(redact) : undefined;
+
+  const pinoOptions: LoggerOptions = {
+    name: service,
+    level: level ?? "info",
+    redact: redactPaths ? { paths: redactPaths, censor: "[REDACTED]" } : undefined,
+    serializers: serializer,
+    ...(base && { base }),
+    mixin() {
+      return mixin ? mixin() : {};
+    },
+  };
+
+  let logger: PinoLogger;
+
+  if (transport) {
+    const transports = Array.isArray(transport) ? transport : [transport];
+    const targets = transports.map((t) => ({
+      target: t.target,
+      options: t.options ?? {},
+      level: level ?? "info",
+    }));
+    logger = pino(pinoOptions, pino.transport({ targets }) as unknown as pino.DestinationStream);
+  } else {
+    logger = pino(pinoOptions);
+  }
+
+  const buildChild = (parentLogger: PinoLogger): Catalog => {
+    const childAdapt = (method: PinoLevel) => {
+      return (first: string | Record<string, unknown>, second?: Record<string, unknown>) => {
+        if (typeof first === "string") {
+          if (second) {
+            parentLogger[method](redactFields(second, extraRedactFields), first);
+          } else {
+            parentLogger[method](first);
+          }
+        } else {
+          parentLogger[method](redactFields(first, extraRedactFields));
+        }
+      };
+    };
+
+    return {
+      trace: childAdapt("trace"),
+      debug: childAdapt("debug"),
+      info: childAdapt("info"),
+      warn: childAdapt("warn"),
+      error: childAdapt("error"),
+      fatal: childAdapt("fatal"),
+
+      child(bindings: Record<string, unknown>): Catalog {
+        return buildChild(parentLogger.child(bindings));
+      },
+
+      get level(): LogLevel {
+        return parentLogger.level as LogLevel;
+      },
+    };
+  };
+
+  const catalog: Catalog = buildChild(logger);
+
+  return catalog;
+}
+
+export default createCatalog;

package/src/security.ts

@@ -0,0 +1,25 @@
+import type { Catalog } from "./index";
+
+export interface SecurityEvent {
+  action: string;
+  actor: string;
+  ip?: string;
+  userAgent?: string;
+  details?: Record<string, unknown>;
+  severity: "low" | "medium" | "high" | "critical";
+}
+
+export function securityLogger(catalog: Catalog) {
+  return {
+    log(event: SecurityEvent) {
+      catalog.warn("security." + event.action, {
+        security: true,
+        actor: event.actor,
+        ip: event.ip,
+        userAgent: event.userAgent,
+        details: event.details,
+        severity: event.severity,
+      });
+    },
+  };
+}