Unnbound Events SDK

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

Install

bun add unnbound-events

Quick Start

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:

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<string, string> }

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.

// 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

HTTP Port

Set via PORT environment variable (default: 3000):

export PORT=8080

Queue Options

Configure SQS polling behavior:

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

SQS Environment Variables

The queue adapter reads from:

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

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

S3 Large Payload Support

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:

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

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

const server = createServer({
  logger,
});

The logger is used for internal events and traces.