tpaga-logger 0.0.1

package/README.md

@@ -0,0 +1,41 @@
+# @tpaga/logger
+
+Structured logging SDK for Tpaga Node.js microservices. Emits **wide-event JSON** (canonical log line) to stdout for **AWS CloudWatch Logs Insights**, following [loggingsucks.com](https://loggingsucks.com/).
+
+## Status
+
+| Fase | Estado | Rama |
+|------|--------|------|
+| 1 — Contrato de logs (SERF-5797) | Completada | `scaffolding` |
+| 2 — Scaffold build (tsup, vitest, CI) | En revisión | `scaffolding` |
+| 3 — Implementación SDK (SERF-5915) | Pendiente | — |
+| 4 — Piloto CloudWatch (SERF-5916) | Pendiente | — |
+
+## Documentación
+
+- Contrato: [`.agents/docs/SERF-5797_LOG_STRUCTURE_CONTRACT.md`](.agents/docs/SERF-5797_LOG_STRUCTURE_CONTRACT.md)
+- Plan: [`.agents/docs/SERF-5796_TPAGA_LOGGER_IMPLEMENTATION_PLAN.md`](.agents/docs/SERF-5796_TPAGA_LOGGER_IMPLEMENTATION_PLAN.md)
+
+## Desarrollo
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+**Fase 2:** `createLogger`, `withWideEvent`, y correlación son stubs que lanzan hasta Fase 3. `serializeError`, `safeStringify`, `write`, y `redact` (passthrough) están listos para tests.
+
+## Instalación (cuando se publique)
+
+```bash
+pnpm add @tpaga/logger
+```
+
+Ver [`.npmrc.example`](.npmrc.example) para registry interno (TBD).
+
+## Repo
+
+https://bitbucket.org/tpaga/tpaga-logger/src/main/

package/dist/index.cjs

@@ -0,0 +1,91 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LOG_LEVELS: () => LOG_LEVELS,
+  OUTCOMES: () => OUTCOMES,
+  createLogger: () => createLogger,
+  serializeError: () => serializeError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/logger.ts
+var import_pino = __toESM(require("pino"), 1);
+var serializeError = (err) => err instanceof Error ? {
+  type: err.name,
+  message: err.message,
+  code: err.code,
+  stack: err.stack
+} : { type: "UnknownError", message: String(err) };
+var createWideEventBuilder = (base, log) => {
+  const ctx = { ...base };
+  return {
+    enrich: (fields) => Object.assign(ctx, fields),
+    emit: (level, message, terminal) => log[level]({ ...ctx, ...terminal }, message)
+  };
+};
+var createLogger = (config) => {
+  const log = (0, import_pino.default)({
+    level: process.env.LOG_LEVEL ?? "info",
+    base: { service: config.service, environment: config.environment },
+    formatters: {
+      level: (label) => ({ level: label })
+    },
+    timestamp: import_pino.default.stdTimeFunctions.isoTime,
+    redact: {
+      paths: config.redactKeys ?? [],
+      censor: "[REDACTED]"
+    }
+  });
+  return {
+    startOperation: (functionName, base = {}) => createWideEventBuilder({ function: functionName, ...base }, log)
+  };
+};
+
+// src/constants.ts
+var LOG_LEVELS = ["info", "warn", "error", "debug"];
+var OUTCOMES = [
+  "success",
+  "error",
+  "validation_failed",
+  "not_found",
+  "conflict",
+  "timeout",
+  "skipped"
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LOG_LEVELS,
+  OUTCOMES,
+  createLogger,
+  serializeError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/logger.ts","../src/constants.ts"],"sourcesContent":["export { createLogger, serializeError } from './logger.js';\nexport { LOG_LEVELS, OUTCOMES } from './constants.js';\nexport type {\n  Logger,\n  LoggerConfig,\n  LogLevel,\n  Outcome,\n  SerializedError,\n  TerminalFields,\n  WideEventBuilder,\n} from './types.js';\n","import pino from 'pino';\nimport type { Logger, LoggerConfig, SerializedError, TerminalFields, WideEventBuilder } from './types.js';\n\nexport const serializeError = (err: unknown): SerializedError =>\n  err instanceof Error\n    ? {\n        type: err.name,\n        message: err.message,\n        code: (err as { code?: string }).code,\n        stack: err.stack,\n      }\n    : { type: 'UnknownError', message: String(err) };\n\nconst createWideEventBuilder = (\n  base: Record<string, unknown>,\n  log: pino.Logger,\n): WideEventBuilder => {\n  const ctx = { ...base };\n  return {\n    enrich: (fields) => Object.assign(ctx, fields),\n    emit: (level, message, terminal: TerminalFields) => log[level]({ ...ctx, ...terminal }, message),\n  };\n};\n\nexport const createLogger = (config: LoggerConfig): Logger => {\n  const log = pino({\n    level: process.env.LOG_LEVEL ?? 'info',\n    base: { service: config.service, environment: config.environment },\n    formatters: {\n      level: (label) => ({ level: label }),\n    },\n    timestamp: pino.stdTimeFunctions.isoTime,\n    redact: {\n      paths: (config.redactKeys as string[]) ?? [],\n      censor: '[REDACTED]',\n    },\n  });\n\n  return {\n    startOperation: (functionName, base = {}) =>\n      createWideEventBuilder({ function: functionName, ...base }, log),\n  };\n};\n","export const LOG_LEVELS = ['info', 'warn', 'error', 'debug'] as const;\n\nexport const OUTCOMES = [\n  'success',\n  'error',\n  'validation_failed',\n  'not_found',\n  'conflict',\n  'timeout',\n  'skipped',\n] as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAAiB;AAGV,IAAM,iBAAiB,CAAC,QAC7B,eAAe,QACX;AAAA,EACE,MAAM,IAAI;AAAA,EACV,SAAS,IAAI;AAAA,EACb,MAAO,IAA0B;AAAA,EACjC,OAAO,IAAI;AACb,IACA,EAAE,MAAM,gBAAgB,SAAS,OAAO,GAAG,EAAE;AAEnD,IAAM,yBAAyB,CAC7B,MACA,QACqB;AACrB,QAAM,MAAM,EAAE,GAAG,KAAK;AACtB,SAAO;AAAA,IACL,QAAQ,CAAC,WAAW,OAAO,OAAO,KAAK,MAAM;AAAA,IAC7C,MAAM,CAAC,OAAO,SAAS,aAA6B,IAAI,KAAK,EAAE,EAAE,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO;AAAA,EACjG;AACF;AAEO,IAAM,eAAe,CAAC,WAAiC;AAC5D,QAAM,UAAM,YAAAA,SAAK;AAAA,IACf,OAAO,QAAQ,IAAI,aAAa;AAAA,IAChC,MAAM,EAAE,SAAS,OAAO,SAAS,aAAa,OAAO,YAAY;AAAA,IACjE,YAAY;AAAA,MACV,OAAO,CAAC,WAAW,EAAE,OAAO,MAAM;AAAA,IACpC;AAAA,IACA,WAAW,YAAAA,QAAK,iBAAiB;AAAA,IACjC,QAAQ;AAAA,MACN,OAAQ,OAAO,cAA2B,CAAC;AAAA,MAC3C,QAAQ;AAAA,IACV;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL,gBAAgB,CAAC,cAAc,OAAO,CAAC,MACrC,uBAAuB,EAAE,UAAU,cAAc,GAAG,KAAK,GAAG,GAAG;AAAA,EACnE;AACF;;;AC1CO,IAAM,aAAa,CAAC,QAAQ,QAAQ,SAAS,OAAO;AAEpD,IAAM,WAAW;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":["pino"]}

package/dist/index.d.cts

@@ -0,0 +1,34 @@
+declare const LOG_LEVELS: readonly ["info", "warn", "error", "debug"];
+declare const OUTCOMES: readonly ["success", "error", "validation_failed", "not_found", "conflict", "timeout", "skipped"];
+
+type LogLevel = (typeof LOG_LEVELS)[number];
+type Outcome = (typeof OUTCOMES)[number];
+type LoggerConfig = {
+    service: string;
+    environment?: string;
+    redactKeys?: readonly string[];
+};
+type SerializedError = {
+    type: string;
+    message: string;
+    code?: string;
+    stack?: string;
+};
+type TerminalFields = {
+    outcome: Outcome | string;
+    durationMs: number;
+    statusCode?: number;
+    error?: SerializedError;
+};
+type WideEventBuilder = {
+    enrich: (fields: Record<string, unknown>) => void;
+    emit: (level: LogLevel, message: string, terminal: TerminalFields) => void;
+};
+type Logger = {
+    startOperation: (functionName: string, base?: Record<string, unknown>) => WideEventBuilder;
+};
+
+declare const serializeError: (err: unknown) => SerializedError;
+declare const createLogger: (config: LoggerConfig) => Logger;
+
+export { LOG_LEVELS, type LogLevel, type Logger, type LoggerConfig, OUTCOMES, type Outcome, type SerializedError, type TerminalFields, type WideEventBuilder, createLogger, serializeError };

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+declare const LOG_LEVELS: readonly ["info", "warn", "error", "debug"];
+declare const OUTCOMES: readonly ["success", "error", "validation_failed", "not_found", "conflict", "timeout", "skipped"];
+
+type LogLevel = (typeof LOG_LEVELS)[number];
+type Outcome = (typeof OUTCOMES)[number];
+type LoggerConfig = {
+    service: string;
+    environment?: string;
+    redactKeys?: readonly string[];
+};
+type SerializedError = {
+    type: string;
+    message: string;
+    code?: string;
+    stack?: string;
+};
+type TerminalFields = {
+    outcome: Outcome | string;
+    durationMs: number;
+    statusCode?: number;
+    error?: SerializedError;
+};
+type WideEventBuilder = {
+    enrich: (fields: Record<string, unknown>) => void;
+    emit: (level: LogLevel, message: string, terminal: TerminalFields) => void;
+};
+type Logger = {
+    startOperation: (functionName: string, base?: Record<string, unknown>) => WideEventBuilder;
+};
+
+declare const serializeError: (err: unknown) => SerializedError;
+declare const createLogger: (config: LoggerConfig) => Logger;
+
+export { LOG_LEVELS, type LogLevel, type Logger, type LoggerConfig, OUTCOMES, type Outcome, type SerializedError, type TerminalFields, type WideEventBuilder, createLogger, serializeError };

package/dist/index.js

@@ -0,0 +1,51 @@
+// src/logger.ts
+import pino from "pino";
+var serializeError = (err) => err instanceof Error ? {
+  type: err.name,
+  message: err.message,
+  code: err.code,
+  stack: err.stack
+} : { type: "UnknownError", message: String(err) };
+var createWideEventBuilder = (base, log) => {
+  const ctx = { ...base };
+  return {
+    enrich: (fields) => Object.assign(ctx, fields),
+    emit: (level, message, terminal) => log[level]({ ...ctx, ...terminal }, message)
+  };
+};
+var createLogger = (config) => {
+  const log = pino({
+    level: process.env.LOG_LEVEL ?? "info",
+    base: { service: config.service, environment: config.environment },
+    formatters: {
+      level: (label) => ({ level: label })
+    },
+    timestamp: pino.stdTimeFunctions.isoTime,
+    redact: {
+      paths: config.redactKeys ?? [],
+      censor: "[REDACTED]"
+    }
+  });
+  return {
+    startOperation: (functionName, base = {}) => createWideEventBuilder({ function: functionName, ...base }, log)
+  };
+};
+
+// src/constants.ts
+var LOG_LEVELS = ["info", "warn", "error", "debug"];
+var OUTCOMES = [
+  "success",
+  "error",
+  "validation_failed",
+  "not_found",
+  "conflict",
+  "timeout",
+  "skipped"
+];
+export {
+  LOG_LEVELS,
+  OUTCOMES,
+  createLogger,
+  serializeError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logger.ts","../src/constants.ts"],"sourcesContent":["import pino from 'pino';\nimport type { Logger, LoggerConfig, SerializedError, TerminalFields, WideEventBuilder } from './types.js';\n\nexport const serializeError = (err: unknown): SerializedError =>\n  err instanceof Error\n    ? {\n        type: err.name,\n        message: err.message,\n        code: (err as { code?: string }).code,\n        stack: err.stack,\n      }\n    : { type: 'UnknownError', message: String(err) };\n\nconst createWideEventBuilder = (\n  base: Record<string, unknown>,\n  log: pino.Logger,\n): WideEventBuilder => {\n  const ctx = { ...base };\n  return {\n    enrich: (fields) => Object.assign(ctx, fields),\n    emit: (level, message, terminal: TerminalFields) => log[level]({ ...ctx, ...terminal }, message),\n  };\n};\n\nexport const createLogger = (config: LoggerConfig): Logger => {\n  const log = pino({\n    level: process.env.LOG_LEVEL ?? 'info',\n    base: { service: config.service, environment: config.environment },\n    formatters: {\n      level: (label) => ({ level: label }),\n    },\n    timestamp: pino.stdTimeFunctions.isoTime,\n    redact: {\n      paths: (config.redactKeys as string[]) ?? [],\n      censor: '[REDACTED]',\n    },\n  });\n\n  return {\n    startOperation: (functionName, base = {}) =>\n      createWideEventBuilder({ function: functionName, ...base }, log),\n  };\n};\n","export const LOG_LEVELS = ['info', 'warn', 'error', 'debug'] as const;\n\nexport const OUTCOMES = [\n  'success',\n  'error',\n  'validation_failed',\n  'not_found',\n  'conflict',\n  'timeout',\n  'skipped',\n] as const;\n"],"mappings":";AAAA,OAAO,UAAU;AAGV,IAAM,iBAAiB,CAAC,QAC7B,eAAe,QACX;AAAA,EACE,MAAM,IAAI;AAAA,EACV,SAAS,IAAI;AAAA,EACb,MAAO,IAA0B;AAAA,EACjC,OAAO,IAAI;AACb,IACA,EAAE,MAAM,gBAAgB,SAAS,OAAO,GAAG,EAAE;AAEnD,IAAM,yBAAyB,CAC7B,MACA,QACqB;AACrB,QAAM,MAAM,EAAE,GAAG,KAAK;AACtB,SAAO;AAAA,IACL,QAAQ,CAAC,WAAW,OAAO,OAAO,KAAK,MAAM;AAAA,IAC7C,MAAM,CAAC,OAAO,SAAS,aAA6B,IAAI,KAAK,EAAE,EAAE,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO;AAAA,EACjG;AACF;AAEO,IAAM,eAAe,CAAC,WAAiC;AAC5D,QAAM,MAAM,KAAK;AAAA,IACf,OAAO,QAAQ,IAAI,aAAa;AAAA,IAChC,MAAM,EAAE,SAAS,OAAO,SAAS,aAAa,OAAO,YAAY;AAAA,IACjE,YAAY;AAAA,MACV,OAAO,CAAC,WAAW,EAAE,OAAO,MAAM;AAAA,IACpC;AAAA,IACA,WAAW,KAAK,iBAAiB;AAAA,IACjC,QAAQ;AAAA,MACN,OAAQ,OAAO,cAA2B,CAAC;AAAA,MAC3C,QAAQ;AAAA,IACV;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL,gBAAgB,CAAC,cAAc,OAAO,CAAC,MACrC,uBAAuB,EAAE,UAAU,cAAc,GAAG,KAAK,GAAG,GAAG;AAAA,EACnE;AACF;;;AC1CO,IAAM,aAAa,CAAC,QAAQ,QAAQ,SAAS,OAAO;AAEpD,IAAM,WAAW;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "tpaga-logger",
+  "version": "0.0.1",
+  "description": "Structured logging SDK for Tpaga microservices (wide events → CloudWatch)",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "pino": "^10.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@types/node": "^22.15.0",
+    "eslint": "^9.28.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.33.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests",
+    "typecheck": "tsc --noEmit"
+  }
+}