@kids-reporter/logger 0.0.1

package/README.md

@@ -0,0 +1,64 @@
+# @kids-reporter/logger
+
+Shared structured logger and trace utilities for Kids Reporter services. Uses Google Cloud `X-Cloud-Trace-Context` to propagate a single `traceId` so that logs can be correlated in GCP Cloud Logging via `logging.googleapis.com/trace`.
+
+## Types
+
+- **`LogSeverity`** — `'DEBUG' | 'INFO' | 'NOTICE' | 'WARNING' | 'ERROR' | 'ALERT' | 'CRITICAL'`
+- **`StructuredLogPayload`** — `{ severity: LogSeverity; message?: string } & Record<string, unknown>`
+- **`TraceHeaderInput`** — `Headers | Record<string, string | undefined | unknown> | undefined`
+- **`NormalizedTraceContext`** — `{ traceId: string; traceHeaders: { 'X-Cloud-Trace-Context': string } }`
+
+## API
+
+### `normalizeTraceContext(headersInput?, options?)`
+
+Parses trace context from the `X-Cloud-Trace-Context` header (GCP format). Optionally generates a new trace ID when the header is missing.
+
+- **`headersInput`** — Request headers (e.g. `Headers` or plain object).
+- **`options.generateIfMissing`** — If `true` (default), creates a new trace ID when the header is missing; if `false`, returns `undefined` in that case.
+
+**Returns:** `NormalizedTraceContext` or `undefined`.
+
+```ts
+import { normalizeTraceContext } from '@kids-reporter/logger'
+
+const ctx = normalizeTraceContext(request.headers)
+// ctx.traceId, ctx.traceHeaders['X-Cloud-Trace-Context']
+```
+
+### `getTraceLogFields(headersInput?, options?)`
+
+Builds an object of trace-related fields for structured logging. Includes `logging.googleapis.com/trace` when `projectId` is set for GCP log correlation.
+
+- **`headersInput`** — Same as `normalizeTraceContext`.
+- **`options.projectId`** — GCP project ID for the trace field; falls back to `GOOGLE_CLOUD_PROJECT` or `GCP_PROJECT` env vars.
+- **`options.generateIfMissing`** — Same as `normalizeTraceContext` (default `false` here).
+
+**Returns:** Object with `traceId` and optionally `logging.googleapis.com/trace`.
+
+```ts
+import { getTraceLogFields } from '@kids-reporter/logger'
+
+const fields = getTraceLogFields(req.headers, { projectId: 'my-gcp-project' })
+console.log(JSON.stringify({ ...fields, message: 'Request processed' }))
+```
+
+### `getGcpTraceField({ projectId, traceId })`
+
+Returns the GCP trace resource name: `projects/{projectId}/traces/{traceId}`. Returns `undefined` if `projectId` or `traceId` is missing.
+
+### `emitStructured(payload)`
+
+Writes a structured log entry to the console as JSON. Uses `console.error` for ERROR/ALERT/CRITICAL, `console.warn` for WARNING, and `console.log` for others.
+
+```ts
+import { emitStructured } from '@kids-reporter/logger'
+
+emitStructured({
+  severity: 'INFO',
+  message: 'User signed in',
+  userId: 'usr_123',
+  ...getTraceLogFields(request.headers),
+})
+```

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export type LogSeverity = 'DEBUG' | 'INFO' | 'NOTICE' | 'WARNING' | 'ERROR' | 'ALERT' | 'CRITICAL';
+export type StructuredLogPayload = {
+    severity: LogSeverity;
+    message?: string;
+} & Record<string, unknown>;
+/** Supports Express req.headers where values can be string | string[]. */
+export type TraceHeaderInput = Headers | Record<string, string | string[] | undefined | unknown> | undefined;
+/** Trace context for GCP Cloud Logging correlation. Only traceId is propagated. */
+export type NormalizedTraceContext = {
+    traceId: string;
+    traceHeaders: {
+        'X-Cloud-Trace-Context': string;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,OAAO,GACP,UAAU,CAAA;AAEd,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,WAAW,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE3B,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,GACvD,SAAS,CAAA;AAEb,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE;QACZ,uBAAuB,EAAE,MAAM,CAAA;KAChC,CAAA;CACF,CAAA"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+import { NormalizedTraceContext, StructuredLogPayload, TraceHeaderInput } from './types.js';
+export declare function normalizeTraceContext(headersInput: TraceHeaderInput | undefined, options: {
+    generateIfMissing: true;
+}): NormalizedTraceContext;
+export declare function normalizeTraceContext(headersInput?: TraceHeaderInput, options?: {
+    generateIfMissing?: boolean;
+}): NormalizedTraceContext | undefined;
+export declare function getGcpTraceField({ projectId, traceId, }: {
+    projectId?: string;
+    traceId: string;
+}): string | undefined;
+export declare function getTraceLogFields(headersInput?: TraceHeaderInput, options?: {
+    projectId?: string;
+    generateIfMissing?: boolean;
+}): {};
+export declare function emitStructured(payload: StructuredLogPayload): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAuFnB,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,gBAAgB,GAAG,SAAS,EAC1C,OAAO,EAAE;IAAE,iBAAiB,EAAE,IAAI,CAAA;CAAE,GACnC,sBAAsB,CAAA;AACzB,wBAAgB,qBAAqB,CACnC,YAAY,CAAC,EAAE,gBAAgB,EAC/B,OAAO,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GACxC,sBAAsB,GAAG,SAAS,CAAA;AAyBrC,wBAAgB,gBAAgB,CAAC,EAC/B,SAAS,EACT,OAAO,GACR,EAAE;IACD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;CAChB,sBAKA;AAED,wBAAgB,iBAAiB,CAC/B,YAAY,CAAC,EAAE,gBAAgB,EAC/B,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAO,MAsBlE;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,oBAAoB,QAiB3D"}

package/dist/utils.js

@@ -0,0 +1,129 @@
+const XCLOUD_TRACE_HEADER = 'x-cloud-trace-context';
+const TRACE_ID_REGEX = /^[a-f0-9]{32}$/i;
+const CONSOLE_BY_SEVERITY = {
+    ALERT: 'error',
+    CRITICAL: 'error',
+    ERROR: 'error',
+    WARNING: 'warn',
+    NOTICE: 'log',
+    INFO: 'log',
+    DEBUG: 'log',
+};
+function normalizeHeaderValue(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (Array.isArray(value) &&
+        value.length > 0 &&
+        typeof value[0] === 'string') {
+        return value[0];
+    }
+    return undefined;
+}
+function getHeaderValue(input, headerName) {
+    if (!input) {
+        return undefined;
+    }
+    if (typeof Headers !== 'undefined' && input instanceof Headers) {
+        return input.get(headerName) || undefined;
+    }
+    const lowered = headerName.toLowerCase();
+    for (const [key, value] of Object.entries(input)) {
+        if (key.toLowerCase() === lowered) {
+            return normalizeHeaderValue(value);
+        }
+    }
+    return undefined;
+}
+function getRandomHex(length) {
+    const bytes = new Uint8Array(Math.ceil(length / 2));
+    if (globalThis.crypto &&
+        typeof globalThis.crypto.getRandomValues === 'function') {
+        globalThis.crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < bytes.length; i += 1) {
+            bytes[i] = Math.floor(Math.random() * 256);
+        }
+    }
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, '0'))
+        .join('')
+        .slice(0, length);
+}
+/**
+ * Parses traceId from GCP X-Cloud-Trace-Context.
+ * Accepts "traceId;o=1" or "traceId/spanId;o=1" (spanId is ignored).
+ */
+function parseXCloudTraceContext(xCloudTraceContext) {
+    if (!xCloudTraceContext) {
+        return undefined;
+    }
+    const [traceAndSpan] = xCloudTraceContext.trim().split(';');
+    const traceId = traceAndSpan.split('/')[0]?.trim();
+    if (!traceId || !TRACE_ID_REGEX.test(traceId)) {
+        return undefined;
+    }
+    return traceId.toLowerCase();
+}
+export function normalizeTraceContext(headersInput, options = {}) {
+    /* eslint-enable no-redeclare */
+    const shouldGenerate = options.generateIfMissing !== false;
+    const xCloudTraceContext = getHeaderValue(headersInput, XCLOUD_TRACE_HEADER);
+    const traceId = parseXCloudTraceContext(xCloudTraceContext);
+    if (!traceId && !shouldGenerate) {
+        return undefined;
+    }
+    const resolvedTraceId = traceId ?? getRandomHex(32);
+    const xCloudValue = `${resolvedTraceId};o=1`;
+    return {
+        traceId: resolvedTraceId,
+        traceHeaders: {
+            'X-Cloud-Trace-Context': xCloudValue,
+        },
+    };
+}
+export function getGcpTraceField({ projectId, traceId, }) {
+    if (!projectId || !traceId) {
+        return undefined;
+    }
+    return `projects/${projectId}/traces/${traceId}`;
+}
+export function getTraceLogFields(headersInput, options = {}) {
+    const traceContext = normalizeTraceContext(headersInput, {
+        generateIfMissing: options.generateIfMissing ?? false,
+    });
+    if (!traceContext) {
+        return {};
+    }
+    const projectId = options.projectId ||
+        process.env.GOOGLE_CLOUD_PROJECT ||
+        process.env.GCP_PROJECT;
+    const traceField = getGcpTraceField({
+        projectId,
+        traceId: traceContext.traceId,
+    });
+    return {
+        ...(traceField ? { 'logging.googleapis.com/trace': traceField } : {}),
+        traceId: traceContext.traceId,
+    };
+}
+export function emitStructured(payload) {
+    const severity = typeof payload?.severity === 'string'
+        ? payload.severity.toUpperCase()
+        : 'INFO';
+    const method = CONSOLE_BY_SEVERITY[severity] || 'log';
+    const message = JSON.stringify(payload);
+    if (method === 'error') {
+        console.error(message);
+        return;
+    }
+    if (method === 'warn') {
+        console.warn(message);
+        return;
+    }
+    console.log(message);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/eslint.config.mjs

@@ -0,0 +1,22 @@
+import baseConfig, {
+  nodeConfig,
+  typescriptConfig,
+} from '../../eslint.base.config.mjs'
+
+export default [
+  ...baseConfig,
+  {
+    ...typescriptConfig,
+    files: ['src/**/*.ts'],
+    rules: {
+      ...typescriptConfig.rules,
+    },
+  },
+  {
+    ...nodeConfig,
+    files: ['**/*.config.{js,mjs,cjs}'],
+  },
+  {
+    ignores: ['node_modules/**', 'dist/**'],
+  },
+]

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kids-reporter/logger",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "description": "Shared structured logger for Kids Reporter services",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "postinstall": "yarn build",
+    "lint:check": "eslint src --config ./eslint.config.mjs --ext .ts",
+    "type-check": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "typescript": "^5.9.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './types.js'
+export * from './utils.js'

package/src/types.ts

@@ -0,0 +1,27 @@
+export type LogSeverity =
+  | 'DEBUG'
+  | 'INFO'
+  | 'NOTICE'
+  | 'WARNING'
+  | 'ERROR'
+  | 'ALERT'
+  | 'CRITICAL'
+
+export type StructuredLogPayload = {
+  severity: LogSeverity
+  message?: string
+} & Record<string, unknown>
+
+/** Supports Express req.headers where values can be string | string[]. */
+export type TraceHeaderInput =
+  | Headers
+  | Record<string, string | string[] | undefined | unknown>
+  | undefined
+
+/** Trace context for GCP Cloud Logging correlation. Only traceId is propagated. */
+export type NormalizedTraceContext = {
+  traceId: string
+  traceHeaders: {
+    'X-Cloud-Trace-Context': string
+  }
+}

package/src/utils.ts

@@ -0,0 +1,180 @@
+import {
+  NormalizedTraceContext,
+  StructuredLogPayload,
+  TraceHeaderInput,
+} from './types.js'
+
+const XCLOUD_TRACE_HEADER = 'x-cloud-trace-context'
+const TRACE_ID_REGEX = /^[a-f0-9]{32}$/i
+
+const CONSOLE_BY_SEVERITY: Record<string, 'log' | 'warn' | 'error'> = {
+  ALERT: 'error',
+  CRITICAL: 'error',
+  ERROR: 'error',
+  WARNING: 'warn',
+  NOTICE: 'log',
+  INFO: 'log',
+  DEBUG: 'log',
+}
+
+function normalizeHeaderValue(
+  value: string | string[] | undefined | unknown
+): string | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+  if (typeof value === 'string') {
+    return value
+  }
+  if (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    typeof value[0] === 'string'
+  ) {
+    return value[0]
+  }
+  return undefined
+}
+
+function getHeaderValue(input: TraceHeaderInput, headerName: string) {
+  if (!input) {
+    return undefined
+  }
+  if (typeof Headers !== 'undefined' && input instanceof Headers) {
+    return input.get(headerName) || undefined
+  }
+  const lowered = headerName.toLowerCase()
+  for (const [key, value] of Object.entries(input)) {
+    if (key.toLowerCase() === lowered) {
+      return normalizeHeaderValue(value)
+    }
+  }
+  return undefined
+}
+
+function getRandomHex(length: number) {
+  const bytes = new Uint8Array(Math.ceil(length / 2))
+  if (
+    globalThis.crypto &&
+    typeof globalThis.crypto.getRandomValues === 'function'
+  ) {
+    globalThis.crypto.getRandomValues(bytes)
+  } else {
+    for (let i = 0; i < bytes.length; i += 1) {
+      bytes[i] = Math.floor(Math.random() * 256)
+    }
+  }
+  return Array.from(bytes, (value) => value.toString(16).padStart(2, '0'))
+    .join('')
+    .slice(0, length)
+}
+
+/**
+ * Parses traceId from GCP X-Cloud-Trace-Context.
+ * Accepts "traceId;o=1" or "traceId/spanId;o=1" (spanId is ignored).
+ */
+function parseXCloudTraceContext(
+  xCloudTraceContext?: string
+): string | undefined {
+  if (!xCloudTraceContext) {
+    return undefined
+  }
+  const [traceAndSpan] = xCloudTraceContext.trim().split(';')
+  const traceId = traceAndSpan.split('/')[0]?.trim()
+  if (!traceId || !TRACE_ID_REGEX.test(traceId)) {
+    return undefined
+  }
+  return traceId.toLowerCase()
+}
+
+// Overloads: when generateIfMissing is true, return is always NormalizedTraceContext
+/* eslint-disable no-redeclare -- overload signatures + implementation */
+export function normalizeTraceContext(
+  headersInput: TraceHeaderInput | undefined,
+  options: { generateIfMissing: true }
+): NormalizedTraceContext
+export function normalizeTraceContext(
+  headersInput?: TraceHeaderInput,
+  options?: { generateIfMissing?: boolean }
+): NormalizedTraceContext | undefined
+export function normalizeTraceContext(
+  headersInput?: TraceHeaderInput,
+  options: { generateIfMissing?: boolean } = {}
+) {
+  /* eslint-enable no-redeclare */
+  const shouldGenerate = options.generateIfMissing !== false
+  const xCloudTraceContext = getHeaderValue(headersInput, XCLOUD_TRACE_HEADER)
+  const traceId = parseXCloudTraceContext(xCloudTraceContext)
+
+  if (!traceId && !shouldGenerate) {
+    return undefined
+  }
+
+  const resolvedTraceId = traceId ?? getRandomHex(32)
+  const xCloudValue = `${resolvedTraceId};o=1`
+
+  return {
+    traceId: resolvedTraceId,
+    traceHeaders: {
+      'X-Cloud-Trace-Context': xCloudValue,
+    },
+  }
+}
+
+export function getGcpTraceField({
+  projectId,
+  traceId,
+}: {
+  projectId?: string
+  traceId: string
+}) {
+  if (!projectId || !traceId) {
+    return undefined
+  }
+  return `projects/${projectId}/traces/${traceId}`
+}
+
+export function getTraceLogFields(
+  headersInput?: TraceHeaderInput,
+  options: { projectId?: string; generateIfMissing?: boolean } = {}
+) {
+  const traceContext = normalizeTraceContext(headersInput, {
+    generateIfMissing: options.generateIfMissing ?? false,
+  })
+  if (!traceContext) {
+    return {}
+  }
+
+  const projectId =
+    options.projectId ||
+    process.env.GOOGLE_CLOUD_PROJECT ||
+    process.env.GCP_PROJECT
+  const traceField = getGcpTraceField({
+    projectId,
+    traceId: traceContext.traceId,
+  })
+
+  return {
+    ...(traceField ? { 'logging.googleapis.com/trace': traceField } : {}),
+    traceId: traceContext.traceId,
+  }
+}
+
+export function emitStructured(payload: StructuredLogPayload) {
+  const severity =
+    typeof payload?.severity === 'string'
+      ? payload.severity.toUpperCase()
+      : 'INFO'
+  const method = CONSOLE_BY_SEVERITY[severity] || 'log'
+  const message = JSON.stringify(payload)
+
+  if (method === 'error') {
+    console.error(message)
+    return
+  }
+  if (method === 'warn') {
+    console.warn(message)
+    return
+  }
+  console.log(message)
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noEmit": false,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}