Unnbound Events SDK

Unified HTTP and SQS queue routing with a single API. Register handlers once, handle requests from both transports.

Install

``bash
pnpm add unnbound-events
`

Quick Start

`ts
import { createServer } from 'unnbound-events';

const server = createServer();

// Register route handlers
server.post('/email/:userId', async (c) => {
const { userId } = c.request.params;
const body = c.request.body;

return { status: 200, body: { sent: true } };
});

// Start both HTTP and queue listeners
server.start();
`

The server automatically:

- 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

Handlers

Routes receive a context object with request details:

`ts
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 {
status: 200,
body: { id, ...body },
headers: { 'x-custom': 'value' },
};
});
`

Response format: { status?: number, body?: object, headers?: Record }

Return undefined, null, or omit properties to default to 204 No Content.

Middleware

Add logic that runs before/after handlers. Works for both HTTP and queue requests.

`ts
// Global middleware
server.use(async (c, next) => {
console.log('Request:', c.request.method, c.request.path);
return next();
});

// 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();
});

// Handler-specific middleware
server.post(
'/email',
async (c, next) => {
// Runs only for this handler
return next();
},
async (c) => {
return { status: 200, body: { ok: true } };
}
);
`

Configuration

$3

Set via PORT environment variable (default: 3000):

`bash
export PORT=8080
`

$3

Configure SQS polling behavior:

`ts
const server = createServer({
queue: {
maxMessages: 10, // Messages per poll (default: 10)
visibilityTimeout: 30, // Seconds (default: SQS default)
},
});
`

$3

The queue adapter reads from:

- UNNBOUND_SQS_URL - Queue URL (required for queue listener)
- UNNBOUND_AWS_REGION - AWS region (default: us-west-1)
- UNNBOUND_SQS_ENDPOINT - Custom endpoint (optional)

`bash
export UNNBOUND_SQS_URL="https://sqs.us-west-2.amazonaws.com/123/my-queue"
export UNNBOUND_AWS_REGION="us-west-2"
`

$3

For messages >1MB, payloads can be stored in S3. The SDK automatically fetches and processes them.

Environment variables:

- UNNBOUND_S3_ENDPOINT - Custom S3 endpoint (optional)

The SDK supports AWS Extended Client Library format (S3 pointer messages).

Queue Message Format

SQS message body should be JSON:

`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": {}
}
`

The adapter extracts method, path, headers, query, and body to route the message through your handlers.

Logger Integration

Pass a custom logger:

`ts
import { logger } from 'unnbound-logger-sdk';

const server = createServer({
logger,
});
``

The logger is used for internal events and traces.