@remit/logger-lambda 0.0.1

package/README.md

@@ -0,0 +1,45 @@
+# @remit/logger-lambda
+
+Shared logging package for Remit Lambda workers. Wraps [Pino](https://getpino.io/) with Lambda-specific configuration and environment-aware formatting.
+
+## Features
+
+- **Structured Logging**: JSON output for CloudWatch ingestion in production.
+- **Pretty Print**: Human-readable output for local development.
+- **Request Context**: Automatically correlates logs with Lambda request IDs.
+- **Zero Configuration**: Sensible defaults based on `NODE_ENV`.
+
+## Installation
+
+```bash
+npm install @remit/logger-lambda
+```
+
+## Usage
+
+```typescript
+import { createLogger } from "@remit/logger-lambda";
+import type { SQSEvent, Context } from "aws-lambda";
+
+export const handler = async (event: SQSEvent, context: Context) => {
+  // Initialize logger with Lambda context
+  const log = createLogger(context);
+
+  log.info({ event }, "Processing SQS event");
+
+  try {
+    // ... business logic
+    log.info("Success");
+  } catch (error) {
+    log.error({ error }, "Processing failed");
+    throw error;
+  }
+};
+```
+
+## Environment Variables
+
+| Variable    | Default      | Description                                             |
+| ----------- | ------------ | ------------------------------------------------------- |
+| `LOG_LEVEL` | `info`       | Pino log level (trace, debug, info, warn, error, fatal) |
+| `NODE_ENV`  | `production` | If `development`, enables pretty printing               |

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@remit/logger-lambda",
+	"version": "0.0.1",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"test:typecheck": "tsgo --noEmit",
+		"test": "vitest run",
+		"build": "npm run test:typecheck"
+	},
+	"dependencies": {
+		"@aws-lambda-powertools/logger": "^2",
+		"@aws-lambda-powertools/metrics": "^2"
+	},
+	"devDependencies": {
+		"@types/aws-lambda": "*",
+		"vitest": "*"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/remit-mail/remit.git",
+		"directory": "packages/logger-lambda"
+	}
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { MetricUnit } from "@aws-lambda-powertools/metrics";
+export * from "./logger.js";

package/src/logger.test.ts

@@ -0,0 +1,196 @@
+import type { Context } from "aws-lambda";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockPublishStoredMetrics = vi.fn();
+const mockAddMetric = vi.fn();
+const mockCaptureColdStartMetric = vi.fn();
+const mockAddContext = vi.fn();
+const mockLogTrace = vi.fn();
+const mockLogDebug = vi.fn();
+const mockLogInfo = vi.fn();
+const mockLogWarn = vi.fn();
+const mockLogError = vi.fn();
+const mockLogCritical = vi.fn();
+const mockAppendPersistentKeys = vi.fn();
+const mockCreateChild = vi.fn();
+
+vi.mock("@aws-lambda-powertools/metrics", () => {
+	class MockMetrics {
+		addMetric = mockAddMetric;
+		publishStoredMetrics = mockPublishStoredMetrics;
+		captureColdStartMetric = mockCaptureColdStartMetric;
+	}
+
+	return {
+		Metrics: MockMetrics,
+		MetricUnit: {
+			Count: "Count",
+			Milliseconds: "Milliseconds",
+		},
+	};
+});
+
+vi.mock("@aws-lambda-powertools/logger", () => {
+	class MockLogger {
+		addContext = mockAddContext;
+		trace = mockLogTrace;
+		debug = mockLogDebug;
+		info = mockLogInfo;
+		warn = mockLogWarn;
+		error = mockLogError;
+		critical = mockLogCritical;
+		appendPersistentKeys = mockAppendPersistentKeys;
+		createChild = mockCreateChild;
+	}
+
+	return { Logger: MockLogger };
+});
+
+const makeContext = (): Context =>
+	({
+		awsRequestId: "test-request-id",
+		functionName: "test-function",
+		invokedFunctionArn: "arn:aws:lambda:us-east-1:123:function:test",
+		memoryLimitInMB: "128",
+		logGroupName: "/aws/lambda/test",
+		logStreamName: "test-stream",
+		getRemainingTimeInMillis: () => 30000,
+		callbackWaitsForEmptyEventLoop: false,
+		functionVersion: "$LATEST",
+		done: vi.fn(),
+		fail: vi.fn(),
+		succeed: vi.fn(),
+	}) as unknown as Context;
+
+describe("remit-logger-lambda", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockCreateChild.mockImplementation(() => {
+			const child = {
+				trace: mockLogTrace,
+				debug: mockLogDebug,
+				info: mockLogInfo,
+				warn: mockLogWarn,
+				error: mockLogError,
+				critical: mockLogCritical,
+				appendPersistentKeys: mockAppendPersistentKeys,
+				createChild: mockCreateChild,
+			};
+			return child;
+		});
+	});
+
+	it("exports metrics as a Metrics instance", async () => {
+		const { metrics } = await import("./logger.js");
+		const { Metrics } = await import("@aws-lambda-powertools/metrics");
+		expect(metrics).toBeInstanceOf(Metrics);
+	});
+
+	it("object-first call maps to Powertools message + attributes", async () => {
+		const { createLogger } = await import("./logger.js");
+		const log = createLogger(makeContext());
+		log.error({ error: "boom", messageId: "m1" }, "Failed to parse message");
+		expect(mockLogError).toHaveBeenCalledWith("Failed to parse message", {
+			error: "boom",
+			messageId: "m1",
+		});
+	});
+
+	it("object-first call without message uses empty string", async () => {
+		const { createLogger } = await import("./logger.js");
+		const log = createLogger();
+		log.info({ count: 3 });
+		expect(mockLogInfo).toHaveBeenCalledWith("", { count: 3 });
+	});
+
+	it("string-first call passes message then attributes", async () => {
+		const { createLogger } = await import("./logger.js");
+		const log = createLogger();
+		log.warn("watch out", { reason: "slow" });
+		expect(mockLogWarn).toHaveBeenCalledWith("watch out", { reason: "slow" });
+	});
+
+	it("string-first call without attributes passes only the message", async () => {
+		const { createLogger } = await import("./logger.js");
+		const log = createLogger();
+		log.debug("hello");
+		expect(mockLogDebug).toHaveBeenCalledWith("hello");
+	});
+
+	it("fatal maps to Powertools critical", async () => {
+		const { createLogger } = await import("./logger.js");
+		const log = createLogger();
+		log.fatal({ fatal: true }, "the end");
+		expect(mockLogCritical).toHaveBeenCalledWith("the end", { fatal: true });
+	});
+
+	it("trace maps to Powertools trace", async () => {
+		const { createLogger } = await import("./logger.js");
+		const log = createLogger();
+		log.trace("trace me");
+		expect(mockLogTrace).toHaveBeenCalledWith("trace me");
+	});
+
+	it("child creates a Powertools child and appends bindings", async () => {
+		const { createLogger } = await import("./logger.js");
+		const log = createLogger();
+		const child = log.child({ queue: "imap" });
+		expect(mockCreateChild).toHaveBeenCalledOnce();
+		expect(mockAppendPersistentKeys).toHaveBeenCalledWith({ queue: "imap" });
+		child.info({ done: true }, "child log");
+		expect(mockLogInfo).toHaveBeenCalledWith("child log", { done: true });
+	});
+
+	it("setBindings appends persistent keys", async () => {
+		const { createLogger } = await import("./logger.js");
+		const log = createLogger();
+		log.setBindings({ requestId: "r1" });
+		expect(mockAppendPersistentKeys).toHaveBeenCalledWith({ requestId: "r1" });
+	});
+
+	it("withTelemetry calls the handler and returns its result", async () => {
+		const { withTelemetry } = await import("./logger.js");
+		const handler = vi.fn().mockResolvedValue("hello");
+		const wrapped = withTelemetry(handler);
+		const result = await wrapped({ key: "value" }, makeContext());
+		expect(result).toBe("hello");
+		expect(handler).toHaveBeenCalledOnce();
+	});
+
+	it("withTelemetry re-throws handler errors", async () => {
+		const { withTelemetry } = await import("./logger.js");
+		const boom = new Error("boom");
+		const handler = vi.fn().mockRejectedValue(boom);
+		const wrapped = withTelemetry(handler);
+		await expect(wrapped({}, makeContext())).rejects.toThrow("boom");
+	});
+
+	it("withTelemetry publishes metrics in finally even on error", async () => {
+		const { withTelemetry } = await import("./logger.js");
+		const handler = vi.fn().mockRejectedValue(new Error("fail"));
+		const wrapped = withTelemetry(handler);
+		await expect(wrapped({}, makeContext())).rejects.toThrow();
+		expect(mockPublishStoredMetrics).toHaveBeenCalled();
+	});
+
+	it("withTelemetry emits errorCount on handler failure", async () => {
+		const { withTelemetry } = await import("./logger.js");
+		const handler = vi.fn().mockRejectedValue(new Error("fail"));
+		const wrapped = withTelemetry(handler);
+		await expect(wrapped({}, makeContext())).rejects.toThrow();
+		expect(mockAddMetric).toHaveBeenCalledWith("errorCount", "Count", 1);
+	});
+
+	it("withTelemetry emits invocationCount and invocationLatency on success", async () => {
+		const { withTelemetry } = await import("./logger.js");
+		const handler = vi.fn().mockResolvedValue(42);
+		const wrapped = withTelemetry(handler);
+		await wrapped({}, makeContext());
+		expect(mockAddMetric).toHaveBeenCalledWith("invocationCount", "Count", 1);
+		expect(mockAddMetric).toHaveBeenCalledWith(
+			"invocationLatency",
+			"Milliseconds",
+			expect.any(Number),
+		);
+	});
+});

package/src/logger.ts

@@ -0,0 +1,125 @@
+import { Logger as PowertoolsLogger } from "@aws-lambda-powertools/logger";
+import { Metrics, MetricUnit } from "@aws-lambda-powertools/metrics";
+import type { Context } from "aws-lambda";
+
+type LogBindings = Record<string, unknown>;
+
+type PowertoolsLevel =
+	| "trace"
+	| "debug"
+	| "info"
+	| "warn"
+	| "error"
+	| "critical";
+
+const isBindings = (value: unknown): value is LogBindings =>
+	typeof value === "object" && value !== null;
+
+const emit = (
+	target: PowertoolsLogger,
+	level: PowertoolsLevel,
+	first: LogBindings | string,
+	second?: LogBindings | string,
+): void => {
+	if (typeof first !== "string") {
+		const message = typeof second === "string" ? second : "";
+		target[level](message, first);
+		return;
+	}
+	if (second === undefined) {
+		target[level](first);
+		return;
+	}
+	if (typeof second === "string") {
+		target[level](first, second);
+		return;
+	}
+	target[level](first, second);
+};
+
+export interface Logger {
+	trace(obj: LogBindings, msg?: string): void;
+	trace(msg: string, obj?: LogBindings): void;
+	debug(obj: LogBindings, msg?: string): void;
+	debug(msg: string, obj?: LogBindings): void;
+	info(obj: LogBindings, msg?: string): void;
+	info(msg: string, obj?: LogBindings): void;
+	warn(obj: LogBindings, msg?: string): void;
+	warn(msg: string, obj?: LogBindings): void;
+	error(obj: LogBindings, msg?: string): void;
+	error(msg: string, obj?: LogBindings): void;
+	fatal(obj: LogBindings, msg?: string): void;
+	fatal(msg: string, obj?: LogBindings): void;
+	child(bindings: LogBindings): Logger;
+	setBindings(bindings: LogBindings): void;
+}
+
+const createAdapter = (target: PowertoolsLogger): Logger => ({
+	trace: (first: LogBindings | string, second?: LogBindings | string): void =>
+		emit(target, "trace", first, second),
+	debug: (first: LogBindings | string, second?: LogBindings | string): void =>
+		emit(target, "debug", first, second),
+	info: (first: LogBindings | string, second?: LogBindings | string): void =>
+		emit(target, "info", first, second),
+	warn: (first: LogBindings | string, second?: LogBindings | string): void =>
+		emit(target, "warn", first, second),
+	error: (first: LogBindings | string, second?: LogBindings | string): void =>
+		emit(target, "error", first, second),
+	fatal: (first: LogBindings | string, second?: LogBindings | string): void =>
+		emit(target, "critical", first, second),
+	child: (bindings: LogBindings): Logger => {
+		const childLogger = target.createChild();
+		if (isBindings(bindings)) {
+			childLogger.appendPersistentKeys(bindings);
+		}
+		return createAdapter(childLogger);
+	},
+	setBindings: (bindings: LogBindings): void => {
+		target.appendPersistentKeys(bindings);
+	},
+});
+
+const powertoolsLogger = new PowertoolsLogger({
+	serviceName: process.env.POWERTOOLS_SERVICE_NAME ?? "remit",
+});
+
+export const logger: Logger = createAdapter(powertoolsLogger);
+
+export const metrics = new Metrics({
+	namespace: process.env.POWERTOOLS_METRICS_NAMESPACE ?? "Remit",
+	serviceName: process.env.POWERTOOLS_SERVICE_NAME ?? "remit",
+});
+
+export const createLogger = (_context?: Context): Logger =>
+	createAdapter(powertoolsLogger);
+
+export const withTelemetry = <TEvent, TResult>(
+	handler: (event: TEvent, context: Context) => Promise<TResult>,
+): ((event: TEvent, context: Context) => Promise<TResult>) => {
+	return async (event: TEvent, context: Context): Promise<TResult> => {
+		powertoolsLogger.addContext(context);
+		logger.debug("Lambda invocation started", {
+			functionName: context.functionName,
+		});
+
+		metrics.captureColdStartMetric();
+
+		const start = Date.now();
+
+		try {
+			const result = await handler(event, context);
+			const duration = Date.now() - start;
+
+			metrics.addMetric("invocationCount", MetricUnit.Count, 1);
+			metrics.addMetric("invocationLatency", MetricUnit.Milliseconds, duration);
+
+			return result;
+		} catch (err) {
+			metrics.addMetric("errorCount", MetricUnit.Count, 1);
+			logger.error("Lambda invocation failed", { error: String(err) });
+			throw err;
+		} finally {
+			metrics.publishStoredMetrics();
+		}
+	};
+};

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../../tsconfig.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src/**/*.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({ test: { environment: "node" } });