unnbound-events 1.0.22 → 2.0.2

package/README.md

@@ -1,340 +1,173 @@
 # Unnbound Events SDK
 
-Unified routing for HTTP and SQS with one handler registration API.
+Unified HTTP and SQS queue routing with a single API. Register handlers once, handle requests from both transports.
 
 ## Install
 
 ```bash
-pnpm add unnbound-events-sdk
+pnpm add unnbound-events
 ```
 
-## Usage
-
-### Simple Start (Recommended)
-
-Register handlers and start with automatic graceful shutdown:
+## Quick Start
 
 ```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();
-```
+import { createServer } from 'unnbound-events';
 
-The client provides a built-in `GET /healthcheck` handler that responds with `204`, so you can skip registering it unless you need custom logic. Add your own handler with the same path to override the default.
+const server = createServer();
 
-### Custom Configuration
+// Register route handlers
+server.post('/email/:userId', async (c) => {
+  const { userId } = c.request.params;
+  const body = c.request.body;
 
-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' },
+  return { status: 200, body: { sent: true } };
 });
 
-// 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',
-  },
-});
+// Start both HTTP and queue listeners
+server.start();
 ```
 
-### Manual Control
+The server automatically:
 
-For more control over individual transports:
+- Starts HTTP server on `PORT` (default: `3000`)
+- Starts SQS long-polling if `UNNBOUND_SQS_URL` is set
+- Provides `/healthcheck` endpoint (returns `200 { status: 'ok' }`)
+- Handles graceful shutdown on `SIGINT`/`SIGTERM`
 
-```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 });
+## Handlers
 
-// SQS Lambda handler
-export const handler = client.sqs();
-
-// SQS long-poll listener (env-driven)
-// Env: UNNBOUND_SQS_QUEUE_URL (or SQS_QUEUE_URL), AWS_REGION, AWS_SQS_ENDPOINT (optional)
-await client.sqsListen();
-```
-
-## Middleware
-
-Add cross-cutting logic that runs before/after your handlers. Works for both HTTP and SQS.
+Routes receive a context object with request details:
 
 ```ts
-import { createEventsClient } from 'unnbound-events-sdk';
-
-const client = createEventsClient();
-
-// Global middleware
-client.use(async (req, next) => {
-  const startedAt = Date.now();
-  const res = await next(req);
+server.post('/users/:id', async (c) => {
+  // Access request data
+  const { id } = c.request.params;
+  const query = c.request.query;
+  const headers = c.request.headers;
+  const body = c.request.body;
+
+  // Return response
   return {
-    ...res,
-    headers: { ...(res.headers ?? {}), 'x-duration-ms': String(Date.now() - startedAt) },
+    status: 200,
+    body: { id, ...body },
+    headers: { 'x-custom': 'value' },
   };
 });
-
-// Path-scoped middleware (string | RegExp | (path)=>boolean)
-client.use(/^\/admin\//, async (req, next) => {
-  const token = req.headers['authorization'] || req.headers['Authorization'];
-  if (!token || !String(token).startsWith('Bearer ')) {
-    return { status: 401, body: { message: 'Unauthorized' } };
-  }
-  return next(req);
-});
-
-client.get('/health', async () => ({ status: 200, body: { status: 'ok' } }));
-client.post('/echo', async (req) => ({ status: 200, body: req.body }));
-
-await client.start();
 ```
 
-SQS-specific example:
-
-```ts
-const client = createEventsClient();
-
-client.use(async (req, next) => {
-  const rid = String(req.headers['x-request-id'] ?? crypto.randomUUID());
-  return next({
-    ...req,
-    headers: { ...req.headers, 'x-request-id': rid },
-    metadata: { ...(req.metadata ?? {}), requestId: rid },
-  });
-});
-
-client.post('/jobs/process', async (req) => ({ status: 200, body: { ok: true } }));
-
-await client.sqsListen();
-```
+**Response format:** `{ status?: number, body?: object, headers?: Record<string, string> }`
 
-API:
+Return `undefined`, `null`, or omit properties to default to `204 No Content`.
 
-- `use(middleware)`
-- `use(matcher, middleware)` where matcher is `string | RegExp | (path) => boolean`
-- `middleware(req, next) -> Promise<EventResponse>`
-
-## Enqueue Events
-
-The `enqueue` function allows you to send events to the queue by using the async endpoint.
+## Middleware
 
-### Basic Usage
+Add logic that runs before/after handlers. Works for both HTTP and queue requests.
 
 ```ts
-import { createEventsClient } from 'unnbound-events-sdk';
-
-const client = createEventsClient();
-
-client.post('/process-job', async (req) => {
-  console.log('Handle job:', req.body);
-
-  // Split job into multiple tasks
-  const tasks = [...];
-
-  tasks.map(async (task) => {
-    await client.enqueue({
-      method: 'POST',
-      path: '/process-task',
-      body: { jobId: '123', data: 'important data' }
-    });
-  });
-
-  return { status: 200, body: { processed: true } };
+// Global middleware
+server.use(async (c, next) => {
+  console.log('Request:', c.request.method, c.request.path);
+  return next();
 });
 
-client.post('/process-task', async (req) => {
-  console.log('Handle task:', req.body);
-
-  return { status: 200, body: { processed: true } };
+// Path-based middleware
+server.use('/admin/*', async (c, next) => {
+  const token = c.request.headers['authorization'];
+  if (!token?.startsWith('Bearer ')) {
+    return { status: 401, body: { error: 'Unauthorized' } };
+  }
+  return next();
 });
 
-await client.start();
+// Handler-specific middleware
+server.post(
+  '/email',
+  async (c, next) => {
+    // Runs only for this handler
+    return next();
+  },
+  async (c) => {
+    return { status: 200, body: { ok: true } };
+  }
+);
 ```
 
-### Scheduled Jobs
-
-```ts
-// Trigger scheduled processing
-setInterval(async () => {
-  await client.enqueue({
-    method: 'POST',
-    path: '/cleanup',
-    body: { timestamp: Date.now() },
-  });
-}, 60000); // Every minute
-```
+## Configuration
 
-## Message envelope
+### HTTP Port
 
-The SQS record `body` should be a JSON string matching this shape:
+Set via `PORT` environment variable (default: `3000`):
 
-```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>;
-}
+```bash
+export PORT=8080
 ```
 
-## S3 Payload Offloading for Large Messages
-
-The SDK supports automatic handling of large payloads (>256KB) stored in S3, which is necessary since SQS has a 256KB message size limit.
+### Queue Options
 
-The S3 SDK (`@aws-sdk/client-s3`) is included as a dependency, so no additional installation is required.
-
-### Automatic Configuration
-
-The SDK will automatically enable S3 support when environment variables are set:
-
-- `UNNBOUND_S3_PAYLOAD_BUCKET` or `S3_BUCKET` - S3 bucket name for payload storage
-
-No code changes needed! Just set the environment variable and the SDK will handle S3 payloads automatically.
-
-### Manual Configuration
-
-Configure S3 support when starting the client:
+Configure SQS polling behavior:
 
 ```ts
-await client.start({
-  sqs: { queueUrl: 'https://sqs.us-west-2.amazonaws.com/123456789012/my-queue' },
-  s3: {
-    bucketName: 'my-payload-bucket',
-    region: 'us-west-2',
+const server = createServer({
+  queue: {
+    maxMessages: 10, // Messages per poll (default: 10)
+    visibilityTimeout: 30, // Seconds (default: SQS default)
   },
 });
 ```
 
-Or with `sqsListen()`:
-
-```ts
-await client.sqsListen({
-  queueUrl: 'https://sqs.us-west-2.amazonaws.com/123456789012/my-queue',
-  s3: {
-    bucketName: 'my-payload-bucket',
-    region: 'us-west-2',
-  },
-});
-```
+### SQS Environment Variables
 
-### Supported Formats
+The queue adapter reads from:
 
-The SDK supports two S3 payload formats:
+- `UNNBOUND_SQS_URL` - Queue URL (required for queue listener)
+- `UNNBOUND_AWS_REGION` - AWS region (default: `us-west-1`)
+- `UNNBOUND_SQS_ENDPOINT` - Custom endpoint (optional)
 
-1. **ExtendedSQSClient Pointer Format** (AWS Extended Client Library compatible):
-
-   ```json
-   [
-     "software.amazon.payloadoffloading.PayloadS3Pointer",
-     {
-       "s3BucketName": "bucket-name",
-       "s3Key": "key-path"
-     }
-   ]
-   ```
-
-2. **Envelope-based S3 Payloads** (Unnbound format):
-
-   ```json
-   {
-     "payload": {
-       "type": "s3-single",
-       "size": 512000,
-       "compressed": true,
-       "compressionType": "gzip",
-       "location": {
-         "bucket": "bucket-name",
-         "key": "key-path",
-         "region": "us-west-2",
-         "versionId": "optional-version-id"
-       }
-     },
-     "request": { ... }
-   }
-   ```
-
-### Compression Support
-
-The SDK automatically decompresses payloads with:
-
-- `brotli` compression
-- `gzip` compression
-
-When the `compressed` flag is `true` and `compressionType` is specified, the SDK will automatically decompress the payload after fetching from S3.
-
-## Environment Variables
-
-### SQS Configuration
+```bash
+export UNNBOUND_SQS_URL="https://sqs.us-west-2.amazonaws.com/123/my-queue"
+export UNNBOUND_AWS_REGION="us-west-2"
+```
 
-The SDK looks for SQS configuration in this order:
+### S3 Large Payload Support
 
-1. **Options passed to `sqsListen()` or `start()`**
-2. **Environment variables** (in order of preference):
-   - `UNNBOUND_SQS_QUEUE_URL` (custom Unnbound variable)
-   - `SQS_QUEUE_URL` (standard variable)
-   - `QUEUE_URL` (fallback)
+For messages >1MB, payloads can be stored in S3. The SDK automatically fetches and processes them.
 
-**Required:**
+**Environment variables:**
 
-- `UNNBOUND_SQS_QUEUE_URL` or `SQS_QUEUE_URL` - The SQS queue URL
+- `UNNBOUND_S3_ENDPOINT` - Custom S3 endpoint (optional)
 
-**Optional:**
+The SDK supports AWS Extended Client Library format (S3 pointer messages).
 
-- `AWS_REGION` - AWS region (defaults to `us-east-1`)
-- `AWS_SQS_ENDPOINT` - Custom SQS endpoint (for LocalStack, etc.)
+## Queue Message Format
 
-**Example:**
+SQS message body should be JSON:
 
-```bash
-export UNNBOUND_SQS_QUEUE_URL="https://sqs.us-west-2.amazonaws.com/123456789012/my-queue"
-export AWS_REGION="us-west-2"
+```json
+{
+  "id": "unique-id",
+  "timestamp": 1234567890,
+  "request": {
+    "method": "POST",
+    "url": "https://example.com/path?query=value",
+    "headers": { "content-type": "application/json" },
+    "body": "base64-encoded-body"
+  },
+  "metadata": {}
+}
 ```
 
-### S3 Configuration
-
-For S3 payload support, configure:
-
-**Required:**
+The adapter extracts `method`, `path`, `headers`, `query`, and `body` to route the message through your handlers.
 
-- `UNNBOUND_S3_PAYLOAD_BUCKET` or `S3_BUCKET` - S3 bucket name for payload storage
+## Logger Integration
 
-**Optional:**
+Pass a custom logger:
 
-- `AWS_REGION` - AWS region (defaults to `us-east-1`)
-- `AWS_S3_ENDPOINT` - Custom S3 endpoint (for LocalStack, etc.)
-
-**Example:**
+```ts
+import { logger } from 'unnbound-logger-sdk';
 
-```bash
-export UNNBOUND_S3_PAYLOAD_BUCKET="my-payload-bucket"
-export AWS_REGION="us-west-2"
+const server = createServer({
+  logger,
+});
 ```
+
+The logger is used for internal events and traces.

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export { createEventsClient } from './lib/client';
-export type { EventsClient, EventRequest, EventResponse, RouteHandler, RouteMatcher, RegisteredRoute, SqsBatchEvent, StartOptions, Middleware, } from './lib/types';
-export { createExpressMiddleware } from './lib/adapters/express';
-export { createSqsConsumer } from './lib/adapters/sqs';
+export type { IncomingEvent, IncomingRequest, EventMetadata, EventSource } from './lib/types';
+export type { EventServerOptions, EventServer } from './lib/server';
+export { createServer } from './lib/server';

package/dist/index.js

@@ -1,9 +1,5 @@
 "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; } });
+exports.createServer = void 0;
+var server_1 = require("./lib/server");
+Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return server_1.createServer; } });

package/dist/lib/adapters/adapter.d.ts

@@ -0,0 +1,40 @@
+import { UnnboundLogger } from 'unnbound-logger-sdk';
+import { EventHandlerResult, EventMetadata, EventSource, IncomingEvent, IncomingRequest } from '../types';
+export type EventHandler = (event: IncomingEvent) => Promise<EventHandlerResult>;
+export interface EventAdapterOptions {
+    logger?: UnnboundLogger;
+    source: EventSource;
+    handler: EventHandler;
+}
+export declare abstract class EventAdapter<E> {
+    protected readonly logger: UnnboundLogger;
+    protected readonly source: EventSource;
+    private readonly handler;
+    protected constructor(options: EventAdapterOptions);
+    protected abstract parseEvent(event: E): IncomingEvent;
+    abstract listen(): () => Promise<void>;
+    protected getMetadataFromRequest(request: IncomingRequest): EventMetadata;
+    protected normalizeHeaders(headers: Record<string, string | string[]>): Record<string, string>;
+    protected handle(event: IncomingEvent): Promise<EventHandlerResult>;
+    protected buildIncomingPayload(req: IncomingRequest, res?: EventHandlerResult): {
+        type: string;
+        source: EventSource;
+        http: {
+            url: string;
+            method: string;
+            query: Record<string, any>;
+            ip: string | undefined;
+            incoming: boolean;
+            request: {
+                headers: Record<string, string>;
+                body: any;
+            };
+            response: {
+                status: import("hono/utils/http-status").StatusCode;
+                headers: Record<string, string> | undefined;
+                body: any;
+            } | undefined;
+        };
+    };
+    protected handleError(error: unknown): EventHandlerResult;
+}

package/dist/lib/adapters/adapter.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventAdapter = void 0;
+const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
+const trace_1 = require("unnbound-logger-sdk/dist/trace");
+const types_1 = require("unnbound-logger-sdk/dist/types");
+const utils_1 = require("unnbound-logger-sdk/dist/utils");
+const error_1 = require("../error");
+class EventAdapter {
+    logger;
+    source;
+    handler;
+    constructor(options) {
+        this.logger = options.logger ?? unnbound_logger_sdk_1.logger;
+        this.source = options.source;
+        this.handler = options.handler;
+    }
+    getMetadataFromRequest(request) {
+        return {
+            traceId: request.headers[types_1.defaultTraceHeaderKey] ?? unnbound_logger_sdk_1.getTraceId,
+            messageId: request.headers[types_1.defaultMessageHeaderKey] ?? (0, trace_1.getMessageId)(),
+            source: this.source,
+        };
+    }
+    normalizeHeaders(headers) {
+        return Object.fromEntries(Object.entries(headers).map(([key, value]) => [
+            key,
+            Array.isArray(value) ? value.join(',') : (value?.toString() ?? ''),
+        ]));
+    }
+    async handle(event) {
+        return await (0, trace_1.withTrace)(() => this.handler(event), event.metadata);
+    }
+    buildIncomingPayload(req, res) {
+        return {
+            type: 'http',
+            source: this.source,
+            http: {
+                url: req.url,
+                method: req.method.toLowerCase(),
+                query: req.query,
+                ip: (0, utils_1.normalizeIp)(req.headers['cf-connecting-ip'] ??
+                    req.headers['x-forwarded-for'] ??
+                    req.headers['x-real-ip']),
+                incoming: true,
+                request: {
+                    headers: req.headers,
+                    body: (0, utils_1.safeJsonParse)(req.body),
+                },
+                response: res
+                    ? {
+                        status: res.status ?? 204,
+                        headers: res.headers ? this.normalizeHeaders(res.headers) : undefined,
+                        body: res.body ? (0, utils_1.safeJsonParse)(res.body) : undefined,
+                    }
+                    : undefined,
+            },
+        };
+    }
+    handleError(error) {
+        if (error instanceof error_1.HandlerError) {
+            return {
+                status: error.status,
+                body: error.toJson(),
+            };
+        }
+        return this.handleError(new error_1.HandlerError({ message: 'Internal server error', status: 500, cause: error }));
+    }
+}
+exports.EventAdapter = EventAdapter;

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

@@ -1,4 +1,6 @@
+import type { EventsClient } from '../types';
 type Request = {
+    url: string;
     method: string;
     path: string;
     headers: Record<string, string | string[] | undefined>;
@@ -11,6 +13,5 @@ type Response = {
     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/lib/adapters/express.js

@@ -11,6 +11,7 @@ function toEventRequest(req) {
             headers[key] = value.join(',');
     }
     return {
+        url: req.url,
         method,
         path: req.path,
         headers,

package/dist/lib/adapters/extended-sqs-client.d.ts

@@ -0,0 +1,20 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import { ReceiveMessageCommand, ReceiveMessageCommandOutput, SQSClient } from '@aws-sdk/client-sqs';
+export interface S3Pointer {
+    bucket: string;
+    key: string;
+}
+export type S3PointerMessage = ['software.amazon.payloadoffloading.PayloadS3Pointer', S3Pointer];
+type SQSClientConfig = ConstructorParameters<typeof SQSClient>[0];
+export type ExtendedSQSClientConfig = SQSClientConfig & {
+    s3: S3Client;
+};
+export declare class ExtendedSQSClient extends SQSClient {
+    private readonly s3;
+    private readonly S3_POINTER_CLASS;
+    constructor(config: ExtendedSQSClientConfig);
+    private isS3PointerMessage;
+    private retrieveMessage;
+    receive(command: ReceiveMessageCommand): Promise<ReceiveMessageCommandOutput>;
+}
+export {};

package/dist/lib/adapters/extended-sqs-client.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtendedSQSClient = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const client_sqs_1 = require("@aws-sdk/client-sqs");
+const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
+const internal_1 = require("unnbound-logger-sdk/dist/internal");
+class ExtendedSQSClient extends client_sqs_1.SQSClient {
+    s3;
+    S3_POINTER_CLASS = 'software.amazon.payloadoffloading.PayloadS3Pointer';
+    constructor(config) {
+        super(config);
+        this.s3 = config.s3;
+    }
+    isS3PointerMessage(body) {
+        return Array.isArray(body) && body.length === 2 && body[0] === this.S3_POINTER_CLASS;
+    }
+    async retrieveMessage(message) {
+        if (!message.Body)
+            return message;
+        if (!message.Body.startsWith(`["${this.S3_POINTER_CLASS}",`))
+            return message;
+        const parsed = JSON.parse(message.Body);
+        if (!this.isS3PointerMessage(parsed))
+            return message;
+        const { bucket, key } = parsed[1];
+        unnbound_logger_sdk_1.logger.debug({ bucket, key, ...(0, internal_1.internal)() }, 'Retrieving message from storage.');
+        const payload = await this.s3.send(new client_s3_1.GetObjectCommand({ Bucket: bucket, Key: key }));
+        const body = await payload.Body?.transformToString();
+        if (!body)
+            throw new Error('Failed to retrieve queue message from storage.');
+        return { ...message, Body: body };
+    }
+    async receive(command) {
+        const result = await this.send(command);
+        return {
+            ...result,
+            Messages: await Promise.all(result.Messages?.map(this.retrieveMessage.bind(this)) ?? []),
+        };
+    }
+}
+exports.ExtendedSQSClient = ExtendedSQSClient;