Unified events SDK to handle HTTP routes and queued messages with a single routing API.
npm install unnbound-eventsUnified HTTP and SQS queue routing with a single API. Register handlers once, handle requests from both transports.
``bash`
pnpm add unnbound-events
`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)UNNBOUND_SQS_URL
- Starts SQS long-polling if is set/healthcheck
- Provides endpoint (returns 200 { status: 'ok' })SIGINT
- Handles graceful shutdown on /SIGTERM
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.
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 } };
}
);
`
Set via PORT environment variable (default: 3000):
`bash`
export PORT=8080
Configure SQS polling behavior:
`ts`
const server = createServer({
queue: {
maxMessages: 10, // Messages per poll (default: 10)
visibilityTimeout: 30, // Seconds (default: SQS default)
},
});
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"
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).
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.
Pass a custom logger:
`ts
import { logger } from 'unnbound-logger-sdk';
const server = createServer({
logger,
});
``
The logger is used for internal events and traces.