unnbound-events 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# Unnbound Events SDK
+
+Unified routing for HTTP and SQS with one handler registration API.
+
+## Install
+
+```bash
+pnpm add unnbound-events-sdk
+```
+
+## Usage
+
+### Simple Start (Recommended)
+
+Register handlers and start with automatic graceful shutdown:
+
+```ts
+import { createEventsClient } from 'unnbound-events-sdk';
+
+const client = createEventsClient();
+
+// Register handlers
+client.post('/email', async (req) => ({ status: 200, body: { ok: true } }));
+client.get('/health', async () => ({ status: 200, body: { status: 'ok' } }));
+
+// Start with defaults (HTTP on port 3000, SQS from environment variables)
+await client.start();
+```
+
+### Custom Configuration
+
+Configure specific transports as needed:
+
+```ts
+// HTTP only
+await client.start({ http: { port: 8080 } });
+
+// SQS only
+await client.start({
+  sqs: { queueUrl: 'https://sqs.us-west-2.amazonaws.com/123456789012/my-queue' },
+});
+
+// Both with custom settings
+await client.start({
+  http: { port: 8080 },
+  sqs: {
+    queueUrl: 'https://sqs.us-west-2.amazonaws.com/123456789012/my-queue',
+    region: 'us-west-2',
+  },
+});
+```
+
+### Manual Control
+
+For more control over individual transports:
+
+```ts
+import { createEventsClient } from 'unnbound-events-sdk';
+
+const client = createEventsClient();
+client.post('/email', async (req) => ({ status: 200, body: { ok: true } }));
+
+// Built-in HTTP server
+await client.http({ port: 3000 });
+
+// SQS Lambda handler
+export const handler = client.sqs();
+
+// SQS long-poll listener (env-driven)
+// Env: SQS_QUEUE_URL, AWS_REGION, AWS_SQS_ENDPOINT (optional)
+await client.sqsListen();
+```
+
+## Message envelope
+
+The SQS record `body` should be a JSON string matching this shape:
+
+```ts
+interface QueueEnvelope {
+  id: string;
+  timestamp: number;
+  version: string;
+  workflow: string;
+  priority: number;
+  payload: { type: string; size: number; compressed: boolean };
+  request: {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+    path: string;
+    headers: Record<string, string>;
+    query: Record<string, unknown>;
+    body: unknown;
+  };
+  metadata?: Record<string, unknown>;
+  addons?: Record<string, unknown>;
+}
+```

package/dist/events/src/index.d.ts

@@ -0,0 +1,4 @@
+export { createEventsClient } from './lib/client';
+export type { EventsClient, EventRequest, EventResponse, RouteHandler, RouteMatcher, RegisteredRoute, SqsBatchEvent, StartOptions, } from './lib/types';
+export { createExpressMiddleware } from './lib/adapters/express';
+export { createSqsConsumer } from './lib/adapters/sqs';

package/dist/events/src/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSqsConsumer = exports.createExpressMiddleware = exports.createEventsClient = void 0;
+var client_1 = require("./lib/client");
+Object.defineProperty(exports, "createEventsClient", { enumerable: true, get: function () { return client_1.createEventsClient; } });
+var express_1 = require("./lib/adapters/express");
+Object.defineProperty(exports, "createExpressMiddleware", { enumerable: true, get: function () { return express_1.createExpressMiddleware; } });
+var sqs_1 = require("./lib/adapters/sqs");
+Object.defineProperty(exports, "createSqsConsumer", { enumerable: true, get: function () { return sqs_1.createSqsConsumer; } });

package/dist/events/src/lib/adapters/express.d.ts

@@ -0,0 +1,16 @@
+type Request = {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    query: Record<string, unknown>;
+    body: unknown;
+};
+type Response = {
+    status: (code: number) => Response;
+    setHeader: (name: string, value: string) => void;
+    send: (body: unknown) => void;
+    end: () => void;
+};
+import type { EventsClient } from '../types';
+export declare function createExpressMiddleware(client: EventsClient): (req: Request, res: Response) => Promise<void>;
+export {};

package/dist/events/src/lib/adapters/express.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExpressMiddleware = createExpressMiddleware;
+function toEventRequest(req) {
+    const method = req.method.toUpperCase();
+    const headers = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === 'string')
+            headers[key] = value;
+        else if (Array.isArray(value))
+            headers[key] = value.join(',');
+    }
+    return {
+        method,
+        path: req.path,
+        headers,
+        query: req.query,
+        body: req.body,
+        metadata: { source: 'http' },
+    };
+}
+function applyResponse(res, response) {
+    res.status(response.status);
+    if (response.headers) {
+        for (const [k, v] of Object.entries(response.headers))
+            res.setHeader(k, v);
+    }
+    if (response.body !== undefined)
+        return res.send(response.body);
+    return res.end();
+}
+function createExpressMiddleware(client) {
+    return async function eventsMiddleware(req, res) {
+        const eventReq = toEventRequest(req);
+        const eventRes = await client.handle(eventReq);
+        applyResponse(res, eventRes);
+    };
+}

package/dist/events/src/lib/adapters/sqs.d.ts

@@ -0,0 +1,36 @@
+import type { EventsClient, HttpMethod } from '../types';
+export interface QueueEnvelope {
+    id: string;
+    timestamp: number;
+    version: string;
+    workflow: string;
+    priority: number;
+    payload: {
+        type: string;
+        size: number;
+        compressed: boolean;
+    };
+    request: {
+        method: HttpMethod;
+        path: string;
+        headers: Record<string, string>;
+        query: Record<string, unknown>;
+        body: unknown;
+    };
+    metadata?: Record<string, unknown>;
+    addons?: Record<string, unknown>;
+}
+export type SqsRecord = {
+    messageId: string;
+    body: string;
+};
+export interface SqsBatchEvent {
+    Records: SqsRecord[];
+}
+export declare function createSqsConsumer(client: EventsClient): (event: SqsBatchEvent) => Promise<{
+    successes: number;
+    failures: Array<{
+        messageId: string;
+        reason: string;
+    }>;
+}>;

package/dist/events/src/lib/adapters/sqs.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSqsConsumer = createSqsConsumer;
+function createSqsConsumer(client) {
+    return async function consume(event) {
+        let successes = 0;
+        const failures = [];
+        await Promise.all(event.Records.map(async (record) => {
+            try {
+                const envelope = JSON.parse(record.body);
+                const req = {
+                    method: envelope.request.method,
+                    path: envelope.request.path,
+                    headers: envelope.request.headers,
+                    query: envelope.request.query,
+                    body: envelope.request.body,
+                    metadata: {
+                        source: 'sqs',
+                        id: envelope.id,
+                        workflow: envelope.workflow,
+                        timestamp: envelope.timestamp,
+                        version: envelope.version,
+                        ...envelope.metadata,
+                    },
+                };
+                const res = await client.handle(req);
+                if (res.status >= 200 && res.status < 300)
+                    successes += 1;
+                else
+                    failures.push({
+                        messageId: record.messageId,
+                        reason: `Handler returned status ${res.status}`,
+                    });
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                failures.push({ messageId: record.messageId, reason: err.message ?? 'Unknown error' });
+            }
+        }));
+        return { successes, failures };
+    };
+}

package/dist/events/src/lib/client.d.ts

@@ -0,0 +1,2 @@
+import type { EventsClient } from './types';
+export declare function createEventsClient(): EventsClient;

package/dist/events/src/lib/client.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEventsClient = createEventsClient;
+const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
+const http = (() => {
+    try {
+        return (require && require('http'));
+    }
+    catch {
+        return null;
+    }
+})();
+function matchPath(matcher, path) {
+    if (typeof matcher === 'string') {
+        return matcher === path;
+    }
+    if (matcher instanceof RegExp) {
+        return matcher.test(path);
+    }
+    return matcher(path);
+}
+function createEventsClient() {
+    const routes = [];
+    return {
+        on(method, matcher, handler) {
+            routes.push({ method, matcher, handler });
+        },
+        get(matcher, handler) {
+            routes.push({ method: 'GET', matcher, handler });
+        },
+        post(matcher, handler) {
+            routes.push({ method: 'POST', matcher, handler });
+        },
+        put(matcher, handler) {
+            routes.push({ method: 'PUT', matcher, handler });
+        },
+        patch(matcher, handler) {
+            routes.push({ method: 'PATCH', matcher, handler });
+        },
+        delete(matcher, handler) {
+            routes.push({ method: 'DELETE', matcher, handler });
+        },
+        options(matcher, handler) {
+            routes.push({ method: 'OPTIONS', matcher, handler });
+        },
+        head(matcher, handler) {
+            routes.push({ method: 'HEAD', matcher, handler });
+        },
+        async handle(request) {
+            const route = routes.find((r) => r.method === request.method && matchPath(r.matcher, request.path));
+            if (!route) {
+                unnbound_logger_sdk_1.logger.warn({ path: request.path, method: request.method }, 'No route match');
+                return { status: 404, body: { message: 'Not Found' } };
+            }
+            try {
+                const response = await route.handler(request);
+                return response;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                unnbound_logger_sdk_1.logger.error({ err, path: request.path }, 'Handler error');
+                return { status: 500, body: { message: 'Internal Server Error' } };
+            }
+        },
+        async http(options) {
+            const port = options?.port ?? 3000;
+            const server = http.createServer((req, res) => {
+                const method = (req.method || 'GET').toUpperCase();
+                const url = new URL(req.url || '/', 'http://localhost');
+                const path = url.pathname;
+                const query = {};
+                url.searchParams.forEach((value, key) => {
+                    query[key] = value;
+                });
+                const headers = {};
+                for (const [k, v] of Object.entries(req.headers)) {
+                    if (typeof v === 'string')
+                        headers[k] = v;
+                    else if (Array.isArray(v))
+                        headers[k] = v.join(',');
+                }
+                let raw = '';
+                req.setEncoding('utf8');
+                req.on('data', (chunk) => {
+                    raw += String(chunk);
+                });
+                req.on('end', async () => {
+                    let body = undefined;
+                    const contentType = headers['content-type'] || headers['Content-Type'];
+                    if (raw) {
+                        if (contentType && contentType.includes('application/json')) {
+                            try {
+                                body = JSON.parse(raw);
+                            }
+                            catch {
+                                body = raw;
+                            }
+                        }
+                        else {
+                            body = raw;
+                        }
+                    }
+                    const eventReq = {
+                        method,
+                        path,
+                        headers,
+                        query,
+                        body,
+                        metadata: { source: 'http' },
+                    };
+                    const eventRes = await this.handle(eventReq);
+                    res.statusCode = eventRes.status;
+                    if (eventRes.headers) {
+                        for (const [k, v] of Object.entries(eventRes.headers))
+                            res.setHeader(k, v);
+                    }
+                    if (eventRes.body !== undefined) {
+                        const bodyStr = typeof eventRes.body === 'string' ? eventRes.body : JSON.stringify(eventRes.body);
+                        res.end(bodyStr);
+                    }
+                    else {
+                        res.end();
+                    }
+                });
+            });
+            await new Promise((resolve) => server.listen(port, resolve));
+            unnbound_logger_sdk_1.logger.info({ port }, 'HTTP server started');
+            return {
+                close() {
+                    return new Promise((resolve, reject) => {
+                        server.close((err) => {
+                            if (err instanceof Error) {
+                                reject(err);
+                                return;
+                            }
+                            if (typeof err === 'string') {
+                                reject(new Error(err));
+                                return;
+                            }
+                            if (err != null) {
+                                reject(new Error('Server close failed'));
+                                return;
+                            }
+                            resolve();
+                        });
+                    });
+                },
+            };
+        },
+        sqs() {
+            return async (event) => {
+                let successes = 0;
+                const failures = [];
+                await Promise.all(event.Records.map(async (record) => {
+                    try {
+                        const envelope = JSON.parse(record.body);
+                        const req = {
+                            method: envelope.request.method,
+                            path: envelope.request.path,
+                            headers: envelope.request.headers,
+                            query: envelope.request.query,
+                            body: envelope.request.body,
+                            metadata: { source: 'sqs', ...envelope.metadata },
+                        };
+                        const res = await this.handle(req);
+                        if (res.status >= 200 && res.status < 300)
+                            successes += 1;
+                        else
+                            failures.push({
+                                messageId: record.messageId,
+                                reason: `Handler returned status ${res.status}`,
+                            });
+                    }
+                    catch (error) {
+                        const err = error instanceof Error ? error : new Error(String(error));
+                        failures.push({
+                            messageId: record.messageId,
+                            reason: err.message ?? 'Unknown error',
+                        });
+                    }
+                }));
+                return { successes, failures };
+            };
+        },
+        sqsListen(options) {
+            const awsSqs = (() => {
+                try {
+                    return require('@aws-sdk/client-sqs');
+                }
+                catch {
+                    return null;
+                }
+            })();
+            if (!awsSqs) {
+                throw new Error('@aws-sdk/client-sqs is required to use sqsListen');
+            }
+            const env = globalThis
+                .process?.env ?? {};
+            const queueUrl = options?.queueUrl || env.SQS_QUEUE_URL || env.QUEUE_URL;
+            if (!queueUrl || queueUrl === undefined) {
+                throw new Error('SQS queue URL not provided. Set SQS_QUEUE_URL env or pass options.queueUrl');
+            }
+            const region = options?.region || env.AWS_REGION || 'us-east-1';
+            const endpoint = env.AWS_SQS_ENDPOINT || env.AWS_ENDPOINT_URL || undefined;
+            const waitTimeSeconds = options?.waitTimeSeconds ?? 10;
+            const maxMessages = options?.maxMessages ?? 10;
+            const visibilityTimeout = options?.visibilityTimeoutSeconds;
+            const sqs = new awsSqs.SQSClient({ region, endpoint });
+            let stopped = false;
+            const consume = this.sqs();
+            async function loop() {
+                while (!stopped) {
+                    try {
+                        const params = {
+                            QueueUrl: queueUrl,
+                            MaxNumberOfMessages: maxMessages,
+                            WaitTimeSeconds: waitTimeSeconds,
+                            ...(visibilityTimeout && { VisibilityTimeout: visibilityTimeout }),
+                        };
+                        const resp = (await sqs.send(new awsSqs.ReceiveMessageCommand(params)));
+                        const messages = (resp.Messages ?? []).map((m) => ({
+                            id: m.MessageId ?? '',
+                            body: String(m.Body ?? ''),
+                            receiptHandle: String(m.ReceiptHandle ?? ''),
+                        }));
+                        if (messages.length === 0)
+                            continue;
+                        const result = await consume({
+                            Records: messages.map((m) => ({ messageId: m.id, body: m.body })),
+                        });
+                        const failed = new Set(result.failures.map((f) => f.messageId));
+                        const toDelete = messages
+                            .filter((m) => !failed.has(m.id))
+                            .map((m) => ({ Id: m.id, ReceiptHandle: m.receiptHandle }));
+                        for (let i = 0; i < toDelete.length; i += 10) {
+                            const chunk = toDelete.slice(i, i + 10);
+                            if (chunk.length > 0) {
+                                await sqs.send(new awsSqs.DeleteMessageBatchCommand({ QueueUrl: queueUrl, Entries: chunk }));
+                            }
+                        }
+                    }
+                    catch (err) {
+                        unnbound_logger_sdk_1.logger.error({ err }, 'SQS listen loop error');
+                    }
+                }
+            }
+            // Start async loop without awaiting
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            loop();
+            return Promise.resolve({
+                stop() {
+                    stopped = true;
+                    return Promise.resolve();
+                },
+            });
+        },
+        async start(options) {
+            // Default to starting both HTTP and SQS if no options provided
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            const httpOptions = options?.http ?? { port: 3000 };
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            const sqsOptions = options?.sqs ?? {};
+            // Start HTTP server
+            let httpServer;
+            try {
+                httpServer = await this.http(httpOptions);
+            }
+            catch (error) {
+                unnbound_logger_sdk_1.logger.warn({ error }, 'Failed to start HTTP server, continuing without it');
+            }
+            // Start SQS listener
+            let sqsListener;
+            try {
+                sqsListener = await this.sqsListen(sqsOptions);
+            }
+            catch (error) {
+                unnbound_logger_sdk_1.logger.warn({ error }, 'Failed to start SQS listener, continuing without it');
+            }
+            // If neither HTTP nor SQS started successfully, throw an error
+            if (!httpServer && !sqsListener) {
+                throw new Error('Failed to start any transport. Please check your configuration and try again.');
+            }
+            // Set up graceful shutdown
+            const g = globalThis;
+            const shutdown = async () => {
+                unnbound_logger_sdk_1.logger.info('Received shutdown signal, closing servers...');
+                const promises = [];
+                if (httpServer)
+                    promises.push(httpServer.close());
+                if (sqsListener)
+                    promises.push(sqsListener.stop());
+                await Promise.all(promises);
+                unnbound_logger_sdk_1.logger.info('All servers closed');
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                g.process?.exit?.(0);
+            };
+            // Handle SIGINT and SIGTERM
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            g.process?.on?.('SIGINT', shutdown);
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            g.process?.on?.('SIGTERM', shutdown);
+            // Log startup information
+            const services = [];
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            if (httpServer)
+                services.push(`HTTP on port ${httpOptions?.port ?? 3000}`);
+            if (sqsListener)
+                services.push('SQS listener');
+            unnbound_logger_sdk_1.logger.info({ services: services.join(' and ') }, 'Services started. Press Ctrl+C to stop.');
+        },
+    };
+}

package/dist/events/src/lib/types.d.ts

@@ -0,0 +1,73 @@
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+export interface EventRequest<Body = unknown, Query = Record<string, unknown>> {
+    method: HttpMethod;
+    path: string;
+    headers: Record<string, string>;
+    query: Query;
+    body: Body;
+    metadata?: Record<string, unknown>;
+}
+export interface EventResponse<Body = unknown> {
+    status: number;
+    headers?: Record<string, string>;
+    body?: Body;
+}
+export type RouteHandler<ReqBody = unknown, ResBody = unknown> = (request: EventRequest<ReqBody>) => Promise<EventResponse<ResBody>> | EventResponse<ResBody>;
+export type RouteMatcher = string | RegExp | ((path: string) => boolean);
+export interface RegisteredRoute {
+    method: HttpMethod;
+    matcher: RouteMatcher;
+    handler: RouteHandler<any, any>;
+}
+export type SqsRecord = {
+    messageId: string;
+    body: string;
+};
+export interface SqsBatchEvent {
+    Records: SqsRecord[];
+}
+export interface StartOptions {
+    http?: {
+        port?: number;
+    };
+    sqs?: {
+        queueUrl?: string;
+        region?: string;
+        waitTimeSeconds?: number;
+        maxMessages?: number;
+        visibilityTimeoutSeconds?: number;
+    };
+}
+export interface EventsClient {
+    on: (method: HttpMethod, matcher: RouteMatcher, handler: RouteHandler<any, any>) => void;
+    handle: (request: EventRequest<any>) => Promise<EventResponse<any>>;
+    get: (matcher: RouteMatcher, handler: RouteHandler<any, any>) => void;
+    post: (matcher: RouteMatcher, handler: RouteHandler<any, any>) => void;
+    put: (matcher: RouteMatcher, handler: RouteHandler<any, any>) => void;
+    patch: (matcher: RouteMatcher, handler: RouteHandler<any, any>) => void;
+    delete: (matcher: RouteMatcher, handler: RouteHandler<any, any>) => void;
+    options: (matcher: RouteMatcher, handler: RouteHandler<any, any>) => void;
+    head: (matcher: RouteMatcher, handler: RouteHandler<any, any>) => void;
+    http: (options?: {
+        port?: number;
+    }) => Promise<{
+        close: () => Promise<void>;
+    }>;
+    sqs: () => (event: SqsBatchEvent) => Promise<{
+        successes: number;
+        failures: Array<{
+            messageId: string;
+            reason: string;
+        }>;
+    }>;
+    sqsListen: (options?: {
+        queueUrl?: string;
+        region?: string;
+        waitTimeSeconds?: number;
+        maxMessages?: number;
+        visibilityTimeoutSeconds?: number;
+    }) => Promise<{
+        stop: () => Promise<void>;
+    }>;
+    start: (options?: StartOptions) => Promise<void>;
+}

package/dist/events/src/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/logger/src/axios.d.ts

@@ -0,0 +1,9 @@
+import { Axios } from 'axios';
+import { HttpOptions } from './types';
+/**
+ * Wraps an axios instance to add tracing and span tracking
+ * @param axios - The axios instance to wrap
+ * @param options - Configuration options for HTTP tracing
+ * @returns The wrapped axios instance with span tracking
+ */
+export declare const traceAxios: (client: Axios, { ignoreTraceRoutes, traceHeaderKey, }?: HttpOptions) => Axios;

package/dist/logger/src/axios.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceAxios = void 0;
+const axios_1 = require("axios");
+const types_1 = require("./types");
+const storage_1 = require("./storage");
+const utils_1 = require("./utils");
+const span_1 = require("./span");
+const buildOutgoingHttpPayload = (config, res) => ({
+    type: 'http',
+    http: {
+        url: [config.baseURL, config.url].filter(Boolean).join(''),
+        method: config.method?.toLowerCase() ?? 'get',
+        incoming: false,
+        request: {
+            headers: config.headers,
+            body: (0, utils_1.safeJsonParse)(config.data),
+        },
+        response: res
+            ? {
+                headers: res?.headers,
+                status: res.status,
+                body: (0, utils_1.safeJsonParse)(res.data),
+            }
+            : undefined,
+    },
+});
+/**
+ * Wraps an axios instance to add tracing and span tracking
+ * @param axios - The axios instance to wrap
+ * @param options - Configuration options for HTTP tracing
+ * @returns The wrapped axios instance with span tracking
+ */
+const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes, traceHeaderKey = types_1.defaultTraceHeaderKey, } = {
+    ignoreTraceRoutes: types_1.defaultIgnoreTraceRoutes,
+    traceHeaderKey: types_1.defaultTraceHeaderKey,
+}) => {
+    const createSpanWrappedRequest = (originalMethod, method) => {
+        const { headers: defaultHeaders, ...partialDefaultConfig } = client.defaults;
+        const headers = { ...defaultHeaders.common, ...(method && defaultHeaders[method]) };
+        const defaultConfig = { ...partialDefaultConfig, headers };
+        return async (config) => {
+            config = (0, axios_1.mergeConfig)(defaultConfig, config);
+            // Determine the actual config and URL
+            const url = [config.baseURL, config.url].filter(Boolean).join('');
+            // Check if this request should be ignored
+            if ((0, utils_1.shouldIgnorePath)(url, ignoreTraceRoutes))
+                return originalMethod(config);
+            const traceId = storage_1.storage.getStore()?.traceId;
+            config = { ...config, headers: { ...config.headers, [traceHeaderKey]: traceId } };
+            // Execute the request within a span
+            return (0, span_1.startSpan)(`Outgoing HTTP request`, () => originalMethod(config), (options) => {
+                if (!options)
+                    return buildOutgoingHttpPayload(config);
+                if (options.error)
+                    return buildOutgoingHttpPayload(config, (0, axios_1.isAxiosError)(options.error) ? options.error.response : undefined);
+                return buildOutgoingHttpPayload(config, options.result);
+            });
+        };
+    };
+    const request = client.request.bind(client);
+    const tracedRequest = createSpanWrappedRequest(request);
+    client.request = tracedRequest;
+    ['post', 'put', 'patch'].forEach((method) => {
+        const func = createSpanWrappedRequest(request, method);
+        client[method] = (url, data, config) => func({ ...config, method, url, data });
+    });
+    ['delete', 'get', 'head', 'options'].forEach((method) => {
+        const func = createSpanWrappedRequest(request, method);
+        client[method] = (url, config) => func({ ...config, method, url });
+    });
+    return client;
+};
+exports.traceAxios = traceAxios;

package/dist/logger/src/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * unnbound-logger
+ *
+ * A structured logging library built on Pino with TypeScript support.
+ * Provides consistent, well-typed logging across different operational contexts.
+ */
+export type { LogLevel, LogType, HttpMethod, Log, HttpPayload, SftpPayload } from './types';
+export type { UnnboundLogger } from './logger';
+export { logger } from './logger';
+export { withTrace, getTraceId } from './trace';
+export { startSpan } from './span';
+export { traceAxios } from './axios';
+export { traceMiddleware } from './middleware';

package/dist/logger/src/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceMiddleware = exports.traceAxios = exports.startSpan = exports.getTraceId = exports.withTrace = exports.logger = void 0;
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
+var trace_1 = require("./trace");
+Object.defineProperty(exports, "withTrace", { enumerable: true, get: function () { return trace_1.withTrace; } });
+Object.defineProperty(exports, "getTraceId", { enumerable: true, get: function () { return trace_1.getTraceId; } });
+var span_1 = require("./span");
+Object.defineProperty(exports, "startSpan", { enumerable: true, get: function () { return span_1.startSpan; } });
+var axios_1 = require("./axios");
+Object.defineProperty(exports, "traceAxios", { enumerable: true, get: function () { return axios_1.traceAxios; } });
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "traceMiddleware", { enumerable: true, get: function () { return middleware_1.traceMiddleware; } });

package/dist/logger/src/logger.d.ts

@@ -0,0 +1,15 @@
+import pino from 'pino';
+export interface UnnboundLogger extends Omit<pino.Logger, 'trace' | 'debug' | 'error' | 'info' | 'warn'> {
+    trace(object: {}, message: string): void;
+    trace(message: string): void;
+    debug(object: {}, message: string): void;
+    debug(message: string): void;
+    info(object: {}, message: string): void;
+    info(message: string): void;
+    warn(object: {}, message: string): void;
+    warn(message: string): void;
+    error<O extends {
+        err: unknown;
+    }>(object: O, message: string): void;
+}
+export declare const logger: UnnboundLogger;

package/dist/logger/src/logger.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const pino_1 = __importDefault(require("pino"));
+const uuid_1 = require("uuid");
+const storage_1 = require("./storage");
+exports.logger = (0, pino_1.default)({
+    level: process.env.LOG_LEVEL ?? 'info',
+    base: {
+        environment: process.env.ENVIRONMENT,
+        workflowId: process.env.UNNBOUND_WORKFLOW_ID,
+        serviceId: process.env.UNNBOUND_SERVICE_ID,
+        deploymentId: process.env.UNNBOUND_DEPLOYMENT_ID,
+    },
+    mixin: () => ({ ...storage_1.storage.getStore(), logId: (0, uuid_1.v4)() }),
+    serializers: {
+        req: pino_1.default.stdSerializers.req,
+        res: pino_1.default.stdSerializers.res,
+        err: pino_1.default.stdSerializers.err,
+    },
+    // Let CloudWatch handle timestamps
+    timestamp: false,
+    // Change message field from 'msg' to 'message'
+    messageKey: 'message',
+    formatters: {
+        level: (level) => ({ level }),
+    },
+    redact: {
+        paths: [
+            'http.request.headers.authorization',
+            'http.response.headers.authorization',
+            'http.request.headers.Authorization',
+            'http.response.headers.Authorization',
+            'err.config',
+        ],
+        remove: true,
+    },
+});
+process.on('uncaughtException', (err, origin) => {
+    exports.logger.error({ err, origin }, `Uncaught exception.`);
+});

package/dist/logger/src/middleware.d.ts

@@ -0,0 +1,3 @@
+import { RequestHandler } from 'express';
+import { HttpOptions } from './types';
+export declare const traceMiddleware: ({ ignoreTraceRoutes, traceHeaderKey, }?: HttpOptions) => RequestHandler;

package/dist/logger/src/middleware.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceMiddleware = void 0;
+const span_1 = require("./span");
+const types_1 = require("./types");
+const utils_1 = require("./utils");
+const trace_1 = require("./trace");
+const getFullUrl = (req) => {
+    const url = req.originalUrl || req.url;
+    if (url?.startsWith('http://') || url?.startsWith('https://'))
+        return url;
+    // Check if we have a workflow URL configured (preferred method)
+    if (process.env.UNNBOUND_WORKFLOW_URL) {
+        // Use workflow URL as the base URL
+        return `${process.env.UNNBOUND_WORKFLOW_URL.replace(/\/$/, '')}${url}`;
+    }
+    // Fallback to constructing from request info for incoming requests
+    const protocol = req.protocol || (req.secure ? 'https' : 'http');
+    const host = req.get('host') || req.get('x-forwarded-host') || 'localhost';
+    return `${protocol}://${host}${url}`;
+};
+const buildIncomingHttpPayload = (req, res, body) => ({
+    type: 'http',
+    http: {
+        url: getFullUrl(req),
+        method: req.method.toLowerCase(),
+        ip: (0, utils_1.normalizeIp)(req.ip),
+        incoming: true,
+        request: {
+            headers: req.headers,
+            body: (0, utils_1.safeJsonParse)(req.body),
+        },
+        response: res
+            ? {
+                headers: res?.headers,
+                status: res.statusCode,
+                body: (0, utils_1.safeJsonParse)(body),
+            }
+            : undefined,
+    },
+});
+const traceMiddleware = ({ ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes, traceHeaderKey = types_1.defaultTraceHeaderKey, } = {
+    ignoreTraceRoutes: types_1.defaultIgnoreTraceRoutes,
+    traceHeaderKey: types_1.defaultTraceHeaderKey,
+}) => async (req, res, next) => {
+    if ((0, utils_1.shouldIgnorePath)(req.path, ignoreTraceRoutes))
+        return next();
+    const traceId = req.header(traceHeaderKey) || (0, trace_1.getTraceId)();
+    res.setHeader(traceHeaderKey, traceId);
+    return await (0, trace_1.withTrace)(async () => {
+        return await (0, span_1.startSpan)('Incoming HTTP request', async () => {
+            return new Promise((resolve) => {
+                // Capture response body for logging
+                const send = res.send.bind(res);
+                res.send = (body) => {
+                    res.locals.body = body;
+                    return send(body);
+                };
+                res.on('finish', () => resolve());
+                return next();
+            });
+        }, (o) => {
+            return buildIncomingHttpPayload(req, o
+                ? {
+                    statusCode: res.statusCode,
+                    headers: res.getHeaders(),
+                }
+                : undefined, res.locals.body);
+        });
+    }, { traceId });
+};
+exports.traceMiddleware = traceMiddleware;

package/dist/logger/src/span.d.ts

@@ -0,0 +1,16 @@
+type LogPayloadGetterOptions<T> = {
+    error: unknown;
+    result?: never;
+} | {
+    error?: never;
+    result: T;
+};
+type LogPayloadGetter<T> = object | ((o?: LogPayloadGetterOptions<T>) => object);
+/**
+ * Starts a span that tracks the duration of a callback
+ * @param spanName - The span name to use for logging
+ * @param callback - The async callback to execute
+ * @returns The result of the callback
+ */
+export declare const startSpan: <T>(spanName: string, callback: () => Promise<T>, getter?: LogPayloadGetter<T>) => Promise<T>;
+export {};

package/dist/logger/src/span.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSpan = void 0;
+const uuid_1 = require("uuid");
+const storage_1 = require("./storage");
+const trace_1 = require("./trace");
+const logger_1 = require("./logger");
+/**
+ * Starts a span that tracks the duration of a callback
+ * @param spanName - The span name to use for logging
+ * @param callback - The async callback to execute
+ * @returns The result of the callback
+ */
+const startSpan = async (spanName, callback, getter) => {
+    const spanId = (0, uuid_1.v4)();
+    const start = performance.now();
+    const previous = storage_1.storage.getStore();
+    return storage_1.storage.run({
+        ...previous,
+        traceId: previous?.traceId ?? (0, trace_1.getTraceId)(),
+        spanId: previous?.spanId ? `${spanId} ${previous?.spanId}` : spanId,
+    }, async () => {
+        logger_1.logger.info({ ...getLogPayload(getter) }, `${spanName} started.`);
+        try {
+            const result = await callback();
+            logger_1.logger.info({ ...getLogPayload(getter, { result }), duration: getDuration(start) }, `${spanName} completed.`);
+            return result;
+        }
+        catch (error) {
+            logger_1.logger.error({ ...getLogPayload(getter, { error }), err: error, duration: getDuration(start) }, `${spanName} failed.`);
+            throw error;
+        }
+    });
+};
+exports.startSpan = startSpan;
+const getLogPayload = (getter, o) => {
+    if (typeof getter !== 'function')
+        return getter;
+    return getter(o);
+};
+const getDuration = (start) => Math.round(performance.now() - start);

package/dist/logger/src/storage.d.ts

@@ -0,0 +1,6 @@
+import { AsyncLocalStorage } from 'async_hooks';
+export interface Context {
+    traceId?: string;
+    spanId?: string;
+}
+export declare const storage: AsyncLocalStorage<Context>;

package/dist/logger/src/storage.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storage = void 0;
+const async_hooks_1 = require("async_hooks");
+exports.storage = new async_hooks_1.AsyncLocalStorage();

package/dist/logger/src/trace.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generates a trace ID
+ * @returns A trace ID
+ */
+export declare const getTraceId: () => string;
+/**
+ * Runs a callback with a trace ID
+ * @param callback - The callback to run
+ * @param extra - Extra context to add to the trace
+ * @returns The result of the callback
+ */
+export declare const withTrace: <T, E extends {
+    traceId?: string;
+}>(callback: () => T, extra?: E) => T;

package/dist/logger/src/trace.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTrace = exports.getTraceId = void 0;
+const uuid_1 = require("uuid");
+const storage_1 = require("./storage");
+/**
+ * Generates a trace ID
+ * @returns A trace ID
+ */
+const getTraceId = () => (0, uuid_1.v4)();
+exports.getTraceId = getTraceId;
+/**
+ * Runs a callback with a trace ID
+ * @param callback - The callback to run
+ * @param extra - Extra context to add to the trace
+ * @returns The result of the callback
+ */
+const withTrace = (callback, extra) => {
+    return storage_1.storage.run({ ...storage_1.storage.getStore(), ...extra, traceId: extra?.traceId ?? (0, exports.getTraceId)() }, callback);
+};
+exports.withTrace = withTrace;

package/dist/logger/src/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Type definitions for structured logging library
+ */
+/**
+ * Available log levels
+ */
+export type LogLevel = 'info' | 'debug' | 'error' | 'warn';
+/**
+ * Available log types
+ */
+export type LogType = 'general' | 'http' | 'sftp';
+/**
+ * HTTP methods supported for HTTP logging
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+export interface Log<T extends LogType = 'general'> {
+    logId: string;
+    level: LogLevel;
+    message: string;
+    type: T;
+    traceId?: string;
+    spanId?: string;
+    serviceId?: string;
+    deploymentId?: string;
+    workflowId?: string;
+    http: T extends 'http' ? HttpPayload : never;
+    sftp: T extends 'sftp' ? SftpPayload : never;
+    duration?: number;
+    err?: unknown;
+}
+export interface HttpPayload {
+    url: string;
+    method: HttpMethod;
+    ip?: string;
+    request: {
+        headers: Record<string, string | string[]>;
+        body?: unknown;
+    };
+    response?: {
+        headers: Record<string, string | string[]>;
+        status: number;
+        body?: unknown;
+    };
+}
+export type SftpOperation = 'connect' | 'upload' | 'download' | 'list' | 'delete' | 'rename' | 'stat' | 'exists' | 'realPath' | 'get' | 'put' | 'cwd' | 'mkdir' | 'rmdir' | 'chmod' | 'append' | 'uploadDir' | 'downloadDir' | 'close';
+export interface SftpPayload {
+    host: string;
+    operation: SftpOperation;
+    path?: string;
+    bytes?: number;
+    destinationPath?: string;
+    files?: string[];
+    content?: string;
+    exists?: string | false;
+}
+export interface HttpOptions {
+    ignoreTraceRoutes?: string[];
+    traceHeaderKey?: string;
+}
+export declare const defaultIgnoreTraceRoutes: string[];
+export declare const defaultTraceHeaderKey = "x-unnbound-trace-id";

package/dist/logger/src/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Type definitions for structured logging library
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultTraceHeaderKey = exports.defaultIgnoreTraceRoutes = void 0;
+exports.defaultIgnoreTraceRoutes = ['/health', '/healthcheck'];
+exports.defaultTraceHeaderKey = 'x-unnbound-trace-id';

package/dist/logger/src/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Checks if a path matches any of the ignore patterns
+ * @param path - The path to check
+ * @param patterns - Array of glob patterns to match against
+ * @returns boolean indicating if the path should be ignored
+ */
+export declare const shouldIgnorePath: (path: string, patterns: string[]) => boolean;
+/**
+ * Safely parses JSON strings, returning the original data if parsing fails or if it's not a string.
+ * @param data The data to potentially parse as JSON.
+ * @returns Parsed JSON object or the original data.
+ */
+export declare function safeJsonParse(data: any): any;
+/**
+ * Normalizes IP addresses by removing IPv6 mapping prefix for IPv4 addresses.
+ * @param ip The IP address to normalize.
+ * @returns Normalized IP address string.
+ */
+export declare function normalizeIp(ip: string | undefined): string | undefined;

package/dist/logger/src/utils.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldIgnorePath = void 0;
+exports.safeJsonParse = safeJsonParse;
+exports.normalizeIp = normalizeIp;
+/**
+ * Checks if a path matches any of the ignore patterns
+ * @param path - The path to check
+ * @param patterns - Array of glob patterns to match against
+ * @returns boolean indicating if the path should be ignored
+ */
+const shouldIgnorePath = (path, patterns) => {
+    return patterns.some((pattern) => {
+        // Convert glob pattern to regex
+        const regexPattern = pattern
+            .replace(/\./g, '\\.') // Escape dots
+            .replace(/\*/g, '.*') // Convert * to .*
+            .replace(/\?/g, '.'); // Convert ? to .
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(path);
+    });
+};
+exports.shouldIgnorePath = shouldIgnorePath;
+/**
+ * Safely parses JSON strings, returning the original data if parsing fails or if it's not a string.
+ * @param data The data to potentially parse as JSON.
+ * @returns Parsed JSON object or the original data.
+ */
+function safeJsonParse(data) {
+    if (typeof data === 'string') {
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return data;
+        }
+    }
+    return data;
+}
+/**
+ * Normalizes IP addresses by removing IPv6 mapping prefix for IPv4 addresses.
+ * @param ip The IP address to normalize.
+ * @returns Normalized IP address string.
+ */
+function normalizeIp(ip) {
+    if (!ip)
+        return ip;
+    // Remove IPv4-mapped IPv6 prefix (::ffff:) to get clean IPv4 address
+    if (ip.startsWith('::ffff:')) {
+        return ip.substring(7);
+    }
+    return ip;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "unnbound-events",
+  "description": "Unified events SDK to handle HTTP routes and SQS messages with a single routing API.",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc -noEmit",
+    "lint": "eslint --cache --cache-location ./node_modules/.cache/eslint .",
+    "lint:fix": "pnpm lint --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "pnpm build",
+    "start:example:express": "npx --yes tsx --watch examples/express.ts",
+    "start:example:sqs": "npx --yes tsx --watch examples/sqs.ts",
+    "start:example:http-and-sqs": "npx --yes tsx --watch examples/http-and-sqs.ts"
+  },
+  "author": "Unnbound Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnbounddev/unnbound-sdks.git"
+  },
+  "homepage": "https://github.com/unnbounddev/unnbound-sdks#readme",
+  "bugs": {
+    "url": "https://github.com/unnbounddev/unnbound-sdks/issues"
+  },
+  "dependencies": {
+    "express": "^4.0.0 || ^5.0.0",
+    "@aws-sdk/client-sqs": "^3.0.0",
+    "unnbound-logger-sdk": "workspace:*"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false
+}