@vyriy/handler 0.7.8 → 0.8.0

package/README.md

@@ -4,7 +4,7 @@ Composable AWS Lambda handler chains and wrappers for Vyriy projects.
 
 ## Purpose
 
-This package provides ready-made Lambda handler chains for common Vyriy workloads and a small set of reusable wrappers for logging, timeouts, smoke checks, development chaos injection, context setup, and error handling. It also ships a native Node HTTP chain (`httpApi`) with matching `httpWith*` wrappers for handlers that work directly with `IncomingMessage` and `ServerResponse`.
+`@vyriy/handler` provides ready-made handler chains for common AWS Lambda workloads and small reusable wrappers for logging, timeouts, smoke checks, development chaos injection, context setup, headers, CORS, healthchecks, and error handling.
 
 It is designed for projects that want a consistent handler pipeline without repeating the same boilerplate in every Lambda entrypoint.
 
@@ -30,9 +30,9 @@ yarn add @types/aws-lambda
 
 The `awslambda` response streaming helper is a global provided by the AWS Lambda Node.js runtime. It is not imported from `aws-lambda`; `@types/aws-lambda` only lets TypeScript type-check that global.
 
-## Usage
+## API
 
-Use a prebuilt API Gateway handler chain:
+Use `api` for API Gateway-style Lambda handlers:
 
 ```ts
 import { api } from '@vyriy/handler';
@@ -45,60 +45,124 @@ export const handler = api(async (event) => ({
 }));
 ```
 
-For Lambda response streaming, use the separate stream chain:
+`api` includes error handling, logging, timeout handling, context setup, smoke checks, healthcheck handling, default headers, CORS preflight handling, and development chaos injection.
+
+Use `create.api(...)` when a project needs a configured API chain. Passing `headers` replaces the default API headers:
 
 ```ts
-// handler.ts
-import { streamApi } from '@vyriy/handler';
+import { create } from '@vyriy/handler';
 
-export const handler = streamApi(async (event, responseStream) => {
-  responseStream.setContentType?.('text/plain');
-  responseStream.write(`Request path: ${event.path}\n`);
-  responseStream.write('Part 1 of the response...');
-  responseStream.end('Part 2 of the response...');
+const api = create.api({
+  headers: {
+    'access-control-allow-origin': '*',
+    'content-type': 'application/json',
+  },
+  healthcheck: {
+    path: '/ready',
+  },
 });
+
+export const handler = api(async () => ({
+  statusCode: 200,
+  body: JSON.stringify({ ok: true }),
+}));
+```
+
+The API-specific entrypoint exposes the same chain as `api`:
+
+```ts
+import { api, create } from '@vyriy/handler/api';
 ```
 
-`streamApi(...)` handlers receive `(event, responseStream, context)` and write directly to the response stream.
+## Event Sources
 
-Use the same handler locally, in Docker, or in a Fargate-style HTTP runtime:
+The event-source chains share the Lambda wrapper set: `withError`, `withLogger`, `withTimeout`, `withContext`, and `withSmoke`. Failures are rethrown so AWS event-source retry behavior still works.
+
+### S3
 
 ```ts
-// server.ts
-import { streamServer } from '@vyriy/server';
+import { s3 } from '@vyriy/handler';
 
-import { handler } from './handler.js';
+export const handler = s3(async (event) => {
+  for (const record of event.Records) {
+    console.info(record.s3.bucket.name, record.s3.object.key);
+  }
+});
+```
 
-streamServer(handler);
+### SQS
+
+```ts
+import { sqs } from '@vyriy/handler';
+
+export const handler = sqs(async (event) => {
+  for (const record of event.Records) {
+    console.info(record.body);
+  }
+});
 ```
 
-Use the same handler in AWS Lambda response streaming:
+### SNS
 
 ```ts
-// lambda.ts
-import { handler } from './handler.js';
+import { sns } from '@vyriy/handler';
 
-export const main = awslambda.streamifyResponse(handler);
+export const handler = sns(async (event) => {
+  for (const record of event.Records) {
+    console.info(record.Sns.Message);
+  }
+});
 ```
 
-That `handler.ts` shape already matches Lambda response streaming. For a standard non-streaming Lambda, export an `api(...)` handler directly without `responseStream`.
+### DynamoDB Streams
 
-You can also inline the same shape in one file when a separate local entrypoint is not needed:
+```ts
+import { dynamodb } from '@vyriy/handler';
+
+export const handler = dynamodb(async (event) => {
+  for (const record of event.Records) {
+    console.info(record.eventName);
+  }
+});
+```
+
+### EventBridge
 
 ```ts
-import { streamApi } from '@vyriy/handler';
+import { eventBridge } from '@vyriy/handler';
 
-export const main = awslambda.streamifyResponse(
-  streamApi(async (event, responseStream) => {
-    responseStream.setContentType?.('text/plain');
-    responseStream.write(`Request path: ${event.path}\n`);
-    responseStream.write('Part 1 of the response...');
-    responseStream.end('Part 2 of the response...');
-  }),
-);
+export const handler = eventBridge(async (event) => {
+  console.info('EventBridge event:', event.source, event['detail-type'], event.detail);
+});
+```
+
+### Schedule
+
+```ts
+import { schedule } from '@vyriy/handler';
+
+export const handler = schedule(async (event) => {
+  console.info('Scheduled event:', event['detail-type']);
+});
 ```
 
-For native Node HTTP handlers, use the HTTP chain. Handlers receive `(request, response)` and own the response lifecycle, which fits transports such as MCP Streamable HTTP:
+### SES
+
+```ts
+import { ses } from '@vyriy/handler';
+
+export const handler = ses(async (event) => {
+  for (const record of event.Records) {
+    console.info(record.ses.mail.messageId, record.ses.mail.source);
+  }
+});
+```
+
+`ses` targets SES receipt rule Lambda events for incoming email. SES event publishing notifications can still be handled through the `sns` chain when delivered via SNS.
+
+## HTTP
+
+Use `httpApi` for native Node HTTP handlers. Handlers receive `(request, response)` and own the response lifecycle, which fits transports such as MCP Streamable HTTP:
 
 ```ts
 import { httpApi } from '@vyriy/handler';
@@ -112,6 +176,33 @@ export const handler = httpApi(async (request, response) => {
 });
 ```
 
+`httpApi` includes error handling, request logging, healthcheck handling, default headers, and CORS preflight handling. It sets no default `content-type` because native handlers own the response body format.
+
+Use the runtime-specific entrypoint when that reads better:
+
+```ts
+import { api, create } from '@vyriy/handler/api/http';
+```
+
+Configure a native HTTP chain with `create.httpApi(...)`. Passing `headers` replaces the default HTTP headers:
+
+```ts
+import { create } from '@vyriy/handler';
+
+const httpApi = create.httpApi({
+  headers: {
+    'access-control-allow-headers': 'content-type, mcp-protocol-version',
+    'access-control-allow-methods': 'GET, POST, OPTIONS',
+    'access-control-allow-origin': '*',
+    'x-content-type-options': 'nosniff',
+  },
+});
+
+export const handler = httpApi(async (_request, response) => {
+  response.writeHead(200).end('ok');
+});
+```
+
 Run it locally or in a container with `httpServer` from `@vyriy/server`:
 
 ```ts
@@ -122,89 +213,188 @@ import { handler } from './handler.js';
 httpServer(handler);
 ```
 
-Use a prebuilt queue or event handler chain:
+Build a custom native HTTP pipeline with `httpCompose(...)` and `httpFactory(...)`:
 
 ```ts
-import { sqs } from '@vyriy/handler';
+import { httpCompose, httpFactory, httpWithError } from '@vyriy/handler';
 
-export const handler = sqs(async (event) => {
-  for (const record of event.Records) {
-    console.info(record.body);
+const httpWithRequestId = httpFactory<{ headerName?: string }>(async (handler, args, options = {}) => {
+  const [request] = args;
+  const requestId = request.headers[options.headerName ?? 'x-request-id'];
+
+  if (requestId) {
+    console.info('Request ID:', requestId);
   }
+
+  await handler(...args);
+});
+
+export const handler = httpCompose(
+  httpWithError(),
+  httpWithRequestId(),
+)(async (_request, response) => {
+  response.writeHead(200).end('ok');
 });
 ```
 
-Use a prebuilt SNS handler chain:
+The lower-level helpers are also available from runtime subpaths:
 
 ```ts
-import { sns } from '@vyriy/handler';
+import { compose } from '@vyriy/handler/api/http/compose';
+import { factory } from '@vyriy/handler/api/http/factory';
+```
 
-export const handler = sns(async (event) => {
-  for (const record of event.Records) {
-    console.info(record.Sns.Message);
-  }
+## Stream
+
+Use `streamApi` for Lambda response streaming. Stream handlers receive `(event, responseStream, context)` and write directly to the response stream:
+
+```ts
+import { streamApi } from '@vyriy/handler';
+
+export const handler = streamApi(async (event, responseStream) => {
+  responseStream.setContentType?.('text/plain');
+  responseStream.write(`Request path: ${event.path}\n`);
+  responseStream.write('Part 1 of the response...');
+  responseStream.end('Part 2 of the response...');
 });
 ```
 
-Use a prebuilt DynamoDB Streams handler chain:
+Use the same handler in AWS Lambda response streaming:
 
 ```ts
-import { dynamodb } from '@vyriy/handler';
+import { handler } from './handler.js';
 
-export const handler = dynamodb(async (event) => {
-  for (const record of event.Records) {
-    console.info(record.eventName);
-  }
-});
+export const main = awslambda.streamifyResponse(handler);
 ```
 
-Use a prebuilt S3 event handler chain:
+Run the same handler locally, in Docker, or in a Fargate-style HTTP runtime:
 
 ```ts
-import { s3 } from '@vyriy/handler';
+import { streamServer } from '@vyriy/server';
 
-export const handler = s3(async (event) => {
-  for (const record of event.Records) {
-    console.info(record.s3.bucket.name, record.s3.object.key);
-  }
-});
+import { handler } from './handler.js';
+
+streamServer(handler);
 ```
 
-Use a prebuilt SES receipt handler chain:
+You can also inline the same shape in one file:
 
 ```ts
-import { ses } from '@vyriy/handler';
+import { streamApi } from '@vyriy/handler';
 
-export const handler = ses(async (event) => {
-  for (const record of event.Records) {
-    console.info(record.ses.mail.messageId, record.ses.mail.source);
+export const main = awslambda.streamifyResponse(
+  streamApi(async (event, responseStream) => {
+    responseStream.setContentType?.('text/plain');
+    responseStream.write(`Request path: ${event.path}\n`);
+    responseStream.end('ok');
+  }),
+);
+```
+
+The runtime-specific entrypoint exposes the same chain as `api`:
+
+```ts
+import { api, create } from '@vyriy/handler/api/stream';
+```
+
+`streamApi` includes the same wrapper behavior as `api`, adapted for response streaming. Passing `headers` to `create.streamApi(...)` replaces the default stream headers.
+
+Custom stream pipelines use stream-specific compose and factory helpers:
+
+```ts
+import { streamCompose, streamFactory, streamWithApiError } from '@vyriy/handler';
+
+const streamWithRequestId = streamFactory<{ headerName?: string }>(async (handler, args, options = {}) => {
+  const [event] = args;
+  const requestId = event.headers?.[options.headerName ?? 'x-request-id'];
+
+  if (requestId) {
+    console.info('Request ID:', requestId);
   }
+
+  await handler(...args);
+});
+
+export const handler = streamCompose(
+  streamWithApiError(),
+  streamWithRequestId(),
+)(async (_event, responseStream) => {
+  responseStream.end('ok');
 });
 ```
 
-Use a prebuilt schedule handler chain:
+The lower-level helpers are also available from runtime subpaths:
 
 ```ts
-import { schedule } from '@vyriy/handler';
+import { compose } from '@vyriy/handler/api/stream/compose';
+import { factory } from '@vyriy/handler/api/stream/factory';
+```
 
-export const handler = schedule(async (event) => {
-  console.info('Scheduled event:', event['detail-type']);
+## Create
+
+`create` builds configured versions of the prebuilt chains while keeping the standard exports unchanged:
+
+```ts
+import { create } from '@vyriy/handler';
+
+const { api, httpApi, s3, sqs, streamApi } = create;
+```
+
+Each key is a factory:
+
+```ts
+import { create } from '@vyriy/handler';
+
+const httpApi = create.httpApi({
+  healthcheck: {
+    path: '/health',
+  },
+  headers: {
+    'access-control-allow-origin': '*',
+    'access-control-allow-methods': 'GET, POST, OPTIONS',
+    'access-control-allow-headers': 'content-type, mcp-protocol-version',
+    'x-content-type-options': 'nosniff',
+  },
+});
+
+export const handler = httpApi(async (_request, response) => {
+  response.writeHead(200).end('ok');
 });
 ```
 
-Use a prebuilt EventBridge custom event handler chain:
+Available factories:
+
+- `create.api(options?)`
+- `create.httpApi(options?)`
+- `create.streamApi(options?)`
+- `create.dynamodb(options?)`
+- `create.eventBridge(options?)`
+- `create.s3(options?)`
+- `create.schedule(options?)`
+- `create.ses(options?)`
+- `create.sns(options?)`
+- `create.sqs(options?)`
+
+For `api`, `httpApi`, and `streamApi`, passing `headers` replaces the default header set for that configured chain.
+
+Runtime subpaths also expose local factories:
 
 ```ts
-import { eventBridge } from '@vyriy/handler';
+import { create as createHttpApi } from '@vyriy/handler/api/http';
+import { create as createStreamApi } from '@vyriy/handler/api/stream';
 
-export const handler = eventBridge(async (event) => {
-  console.info('EventBridge event:', event.source, event['detail-type'], event.detail);
+const httpApi = createHttpApi({
+  headers: {
+    'access-control-allow-origin': '*',
+  },
 });
+
+const streamApi = createStreamApi();
 ```
 
-Each chain has its own composition and factory helpers: `compose`/`factory` for Lambda handlers, `streamCompose`/`streamFactory` for response streaming handlers, and `httpCompose`/`httpFactory` for native Node HTTP handlers.
+## Custom Wrappers
 
-Compose a custom handler pipeline from individual helpers:
+Use `compose(...)` to build a custom Lambda pipeline from decorators:
 
 ```ts
 import { compose, withChaos, withContext, withError, withLogger, withTimeout } from '@vyriy/handler';
@@ -223,7 +413,7 @@ export const handler = compose(
 });
 ```
 
-Create a custom wrapper with `factory(...)` and compose it with the built-in helpers:
+Use `factory(...)` to create a custom Lambda wrapper:
 
 ```ts
 import { compose, factory, withError, withLogger, withTimeout } from '@vyriy/handler';
@@ -258,59 +448,28 @@ export const handler = compose(
 });
 ```
 
-Compose a custom native HTTP pipeline with `httpCompose(...)` and the `httpWith*` wrappers:
-
-```ts
-import { httpCompose, httpWithCors, httpWithError, httpWithHealthcheck, httpWithLogger } from '@vyriy/handler';
-
-export const handler = httpCompose(
-  httpWithError(),
-  httpWithLogger(),
-  httpWithHealthcheck(),
-  httpWithCors(),
-)(async (request, response) => {
-  response
-    .writeHead(200, {
-      'content-type': 'application/json',
-    })
-    .end(JSON.stringify({ ok: true }));
-});
-```
-
-## Prebuilt Chains
-
-- `api`
-  API Gateway chain with error handling, logging, timeout handling, context setup, smoke checks, healthcheck handling, default headers, and CORS preflight handling.
-- `streamApi`
-  Response streaming API Gateway chain with the same wrapper behavior as `api`. Handlers receive `(event, responseStream, context)` and write directly to the Lambda response stream.
+Each runtime has matching helpers:
 
-- `httpApi`
-  Native Node HTTP chain with error handling, logging, healthcheck handling, default headers, and CORS preflight handling. Handlers receive `(request, response)` and write the response themselves. Unlike `api`, the chain sets no default `content-type` because native handlers own the response body format.
+- Lambda: `compose` and `factory` from `@vyriy/handler`
+- HTTP: `httpCompose` and `httpFactory` from `@vyriy/handler`, or `compose` / `factory` from `@vyriy/handler/api/http/compose` and `@vyriy/handler/api/http/factory`
+- Stream: `streamCompose` and `streamFactory` from `@vyriy/handler`, or `compose` / `factory` from `@vyriy/handler/api/stream/compose` and `@vyriy/handler/api/stream/factory`
 
-- `dynamodb`
-  DynamoDB Streams chain with logging, timeout handling, context setup, smoke checks, and rethrown errors.
-
-- `eventBridge`
-  EventBridge custom event chain with logging, timeout handling, context setup, smoke checks, and rethrown errors.
-
-- `s3`
-  S3 event chain with logging, timeout handling, context setup, smoke checks, and rethrown errors.
-
-- `ses`
-  SES receipt rule chain for incoming email processing with logging, timeout handling, context setup, smoke checks, and rethrown errors.
+## Wrappers
 
-- `schedule`
-  EventBridge schedule chain with logging, timeout handling, context setup, smoke checks, and rethrown errors.
+Wrapper exports are split by runtime:
 
-- `sns`
-  SNS chain with logging, timeout handling, context setup, smoke checks, and rethrown errors.
+```ts
+import { withError, withLogger } from '@vyriy/handler/wrappers';
+import { withHeaders } from '@vyriy/handler/api/wrappers';
+import { httpWithHeaders } from '@vyriy/handler/api/http/wrappers';
+import { streamWithHeaders } from '@vyriy/handler/api/stream/wrappers';
+```
 
-- `sqs`
-  SQS chain with logging, timeout handling, context setup, smoke checks, and rethrown errors.
+The root `@vyriy/handler` entrypoint re-exports the public wrappers for convenience.
 
-## Wrappers
+### Common Lambda Wrappers
 
-### `withError(options?)`
+#### `withError(options?)`
 
 Catches handler failures, optionally runs a side-effect `errorHandler`, and rethrows the original error.
 
@@ -322,28 +481,7 @@ Options:
 }
 ```
 
-- `errorHandler`
-  Callback invoked with the caught error and handler arguments before the original error is rethrown.
-
-Example:
-
-```ts
-import { withError } from '@vyriy/handler';
-
-export const handler = withError({
-  errorHandler: async (error) => {
-    console.error('Handler failed:', error);
-  },
-})(async () => {
-  throw new Error('boom');
-});
-```
-
-### `withApiError(options?)`
-
-Catches API handler failures and converts them to an API Gateway result. Without a custom `errorHandler`, it returns a JSON `500`.
-
-### `withLogger(options?)`
+#### `withLogger(options?)`
 
 Logs the incoming event and context, then logs either the result or the thrown error.
 
@@ -355,55 +493,21 @@ Options:
 }
 ```
 
-- `logger`
-  Console-compatible logger implementation. By default the wrapper creates one via `@vyriy/logger`.
-
-Example:
-
-```ts
-import { withLogger } from '@vyriy/handler';
+By default the wrapper creates a logger via `@vyriy/logger`.
 
-export const handler = withLogger({
-  logger: console,
-})(async (event) => {
-  return {
-    ok: true,
-    event,
-  };
-});
-```
-
-### `withTimeout()`
+#### `withTimeout()`
 
 Races the handler against a timeout scheduled one second before the Lambda runtime limit.
 
-Example:
-
-```ts
-import { withTimeout } from '@vyriy/handler';
-
-export const handler = withTimeout()(async () => {
-  await doWork();
-});
-```
-
-### `withContext()`
+#### `withContext()`
 
 Sets `context.callbackWaitsForEmptyEventLoop = false` before calling the handler.
 
-Example:
-
-```ts
-import { withContext } from '@vyriy/handler';
+#### `withSmoke()`
 
-export const handler = withContext()(async (_event, context) => {
-  return {
-    waitForEmptyLoop: context.callbackWaitsForEmptyEventLoop,
-  };
-});
-```
+Returns the smoke response when the incoming event has `isSmoke: true`. Matching is delegated to `@vyriy/smoke`.
 
-### `withChaos(options?)`
+#### `withChaos(options?)`
 
 Injects development-only random failures before the wrapped handler runs.
 
@@ -419,115 +523,133 @@ Options:
 }
 ```
 
-- `enabled`
-  Turns chaos injection on. By default the wrapper reads `CHAOS_ENABLED` through `@vyriy/config`.
-
-- `probability`
-  Probability from `0` to `1` that a failure is injected.
+`enabled` and `timeoutMs` can be read through `@vyriy/config` when they are not passed directly.
 
-- `strategy`
-  Chooses whether to throw an error, wait and time out, or pick one randomly. Defaults to `'random'`.
+### API Wrappers
 
-- `timeoutMs`
-  Timeout delay used when the timeout strategy is selected. By default the wrapper reads `CHAOS_TIMEOUT_MS` through `@vyriy/config`.
+#### `withApiError(options?)`
 
-- `error`
-  Error value normalized through `@vyriy/error` when the error strategy is selected.
+Catches API handler failures and converts them to an API Gateway result. Without a custom `errorHandler`, it returns a JSON `500`.
 
-Example:
+Options:
 
 ```ts
-import { withChaos } from '@vyriy/handler';
-
-export const handler = withChaos({
-  enabled: true,
-  probability: 0.2,
-  strategy: 'random',
-  timeoutMs: 1500,
-})(async () => {
-  return {
-    ok: true,
-  };
-});
+{
+  errorHandler?: (error: unknown, args: HandlerParams<ApiEvent>) => Promise<ApiResult> | ApiResult;
+}
 ```
 
-### `withSmoke()`
+#### `withHealthcheck(options?)`
 
-Returns the smoke response when the incoming event has `isSmoke: true`.
+Returns a JSON `200` response when `event.path` matches the configured `path`.
 
-Example:
+Options:
 
 ```ts
-import { withSmoke } from '@vyriy/handler';
+{
+  path?: string;
+  action?: () => Promise<void>;
+}
+```
 
-export const handler = withSmoke()(async () => {
-  return {
-    statusCode: 200,
-    body: JSON.stringify({
-      status: 'runtime',
-    }),
-  };
-});
+#### `withHeaders(options?)`
+
+Adds configured headers to the API result.
+
+Options:
+
+```ts
+Record<string, string>;
 ```
 
-`withSmoke()` is used by the API, DynamoDB Streams, S3, SES receipt, schedule, SNS, and SQS chains.
+#### `withCors()`
+
+Short-circuits API Gateway `OPTIONS` requests with a `204` response and delegates all other requests.
+
+### HTTP Wrappers
 
-### Native HTTP Wrappers
+#### `httpWithError(options?)`
 
-The `httpWith*` wrappers decorate native Node HTTP handlers and are composed with `httpCompose(...)`:
+Catches native HTTP handler failures and runs an optional side-effect `errorHandler`. When the response is still open it writes a JSON `500`; when headers were already sent it only ends the response.
+
+Options:
 
-- `httpWithError(options?)`
-  Catches handler failures and runs an optional side-effect `errorHandler`. When the response is still open it writes a JSON `500`; when headers were already sent it only ends the response.
+```ts
+{
+  errorHandler?: (error: unknown, args: HttpHandlerParams) => Promise<void> | void;
+}
+```
 
-- `httpWithLogger(options?)`
-  Logs the incoming request method and URL, then logs either the response status code or the thrown error. Accepts the same `logger` option as `withLogger`.
+#### `httpWithLogger(options?)`
 
-- `httpWithHealthcheck(options?)`
-  Writes a JSON `200` response when the request path matches the configured `path` (default `/healthcheck`). Besides `path` and `action`, it accepts an optional JSON-serializable `body` for the healthcheck response.
+Logs the incoming request method and URL, then logs either the final response status code or the thrown error. Accepts the same `logger` option as `withLogger`.
 
-- `httpWithHeaders(options?)`
-  Sets configured headers on the response before delegating, so handler-defined headers win on key conflicts.
+#### `httpWithHealthcheck(options?)`
 
-- `httpWithCors()`
-  Short-circuits `OPTIONS` preflight requests with a `204` response and delegates all other requests.
+Writes a JSON `200` response when the request path matches the configured `path`.
 
-Custom native HTTP wrappers are created with `httpFactory(...)`:
+Options:
 
 ```ts
-import { httpCompose, httpFactory, httpWithError } from '@vyriy/handler';
+{
+  path?: string;
+  action?: () => Promise<void>;
+  body?: unknown;
+}
+```
 
-const httpWithRequestId = httpFactory<{ headerName?: string }>(async (handler, args, options = {}) => {
-  const [request] = args;
-  const requestId = request.headers[options.headerName ?? 'x-request-id'];
+#### `httpWithHeaders(options?)`
 
-  if (requestId) {
-    console.info('Request ID:', requestId);
-  }
+Sets configured headers on the response before delegating, so handler-defined headers win on key conflicts.
 
-  await handler(...args);
-});
+Options:
 
-export const handler = httpCompose(
-  httpWithError(),
-  httpWithRequestId(),
-)(async (request, response) => {
-  response.writeHead(200).end('ok');
-});
+```ts
+Record<string, string>;
 ```
 
+#### `httpWithCors()`
+
+Short-circuits `OPTIONS` preflight requests with a `204` response and delegates all other requests.
+
+### Stream Wrappers
+
+The `streamWith*` wrappers mirror the API and common Lambda wrappers for response streaming handlers:
+
+- `streamWithApiError(options?)`
+- `streamWithLogger(options?)`
+- `streamWithTimeout()`
+- `streamWithContext()`
+- `streamWithSmoke()`
+- `streamWithHealthcheck(options?)`
+- `streamWithHeaders(options?)`
+- `streamWithCors()`
+- `streamWithChaos(options?)`
+
+Stream-specific wrappers write metadata through the response stream before or instead of delegating to the wrapped stream handler.
+
 ## Types
 
-The package also exports shared handler types:
+The package exports shared Lambda handler types from the root entrypoint:
 
 ```ts
 import type { Context, Decorator, Handler, HandlerParams, Response } from '@vyriy/handler';
-import type { HttpDecorator, HttpHandler, HttpHandlerParams } from '@vyriy/handler';
 ```
 
+Runtime-specific types are available from their runtime entrypoints:
+
+```ts
+import type { ApiEvent, ApiOptions, ApiResult } from '@vyriy/handler/api';
+import type { HttpApiOptions, HttpDecorator, HttpHandler, HttpHandlerParams } from '@vyriy/handler/api/http';
+import type { ResponseStream, StreamApiOptions, StreamHandler } from '@vyriy/handler/api/stream';
+```
+
+The root entrypoint still re-exports runtime-specific types for compatibility.
+
 ## Notes
 
 - `api` includes API-specific wrappers such as healthcheck handling, default headers, and CORS preflight handling
-- `httpApi` skips timeout, context, smoke, and chaos wrappers because they rely on the Lambda context and event shape; it also sets no default `content-type`
-- `dynamodb`, `s3`, `ses`, `schedule`, `sns`, and `sqs` use `withError()` so failures are rethrown for event-source retry behavior
-- `ses` targets SES receipt rule Lambda events for incoming email; SES event publishing notifications can still be handled through the `sns` chain when delivered via SNS
-- `withSmoke()` delegates matching to `@vyriy/smoke` and returns its API Gateway-compatible response
+- `httpApi` skips timeout, context, smoke, and chaos wrappers because they rely on the Lambda context and event shape
+- `streamApi` keeps the API-style behavior but adapts result writing to Lambda response streams
+- `dynamodb`, `s3`, `ses`, `schedule`, `sns`, `sqs`, and `eventBridge` use `withError()` so failures are rethrown for event-source retry behavior
+- Passing `headers` to `create.api`, `create.httpApi`, or `create.streamApi` replaces that chain's default headers