@evumi/berth 0.0.0-stage → 0.0.3

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# @evumi/berth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Berth 项目 Queues（队列）和 Alarms（定时器）的客户端，用法照 Cloudflare Queues 和 Durable Object alarms。也负责处理平台推给应用的请求（队列批次、定时器、Cron HTTP 目标），并校验签名。零运行时依赖，支持 Node ≥ 18、Bun、Deno 和 edge 运行时。
+
+项目开了 `queues` 或 `alarms` 能力后，Berth 会给容器注入 `BERTH_CONFIG_URL`、`BERTH_CONFIG_TOKEN` 和 `BERTH_SIGNING_SECRET`。环境是请求来源的那个环境：预览环境只会用到自己的队列和定时器。
+
+## 发消息（producer）
+
+```ts
+import { queue } from '@evumi/berth';
+
+const EMAILS = queue('emails'); // 放在模块顶层即可：环境变量到发请求时才读
+
+await EMAILS.send({ to: 'a@example.com', template: 'welcome' });
+await EMAILS.send({ to: 'b@example.com' }, { delaySeconds: 600, dedupId: 'welcome:42' }); // 24 小时内同一 dedupId 只存一次
+await EMAILS.send('plain text', { contentType: 'text' });
+await EMAILS.send(new Uint8Array(png)); // 自动用 bytes
+
+const { ids } = await EMAILS.sendBatch([{ body: { n: 1 } }, { body: { n: 2 }, delaySeconds: 30 }], { delaySeconds: 5 });
+```
+
+`contentType` 是 `json`（默认，任意 JSON 值）、`text`（字符串）或 `bytes`（`Uint8Array` / `ArrayBuffer`）。`send` 返回 `{ id, deduplicated }`。
+
+自己建客户端：
+
+```ts
+import { createClient } from '@evumi/berth';
+
+const berth = createClient({ url: process.env.BERTH_CONFIG_URL, token: process.env.BERTH_CONFIG_TOKEN, timeoutMs: 10_000 });
+const EMAILS = berth.queue('emails');
+const trialEnd = berth.alarm('trial-end:42');
+```
+
+## 接收推送（consumer）
+
+队列的消费者（push 模式）、定时器的目标服务和 Cron HTTP 目标都指向同一个处理器即可，靠 `Berth-Source` 区分。`createHandler` 会先用原始请求体校验 `Berth-Signature`（默认读 `BERTH_SIGNING_SECRET`，失败回 401），再调用对应函数：
+
+```ts
+import { createHandler } from '@evumi/berth';
+
+export const handler = createHandler({
+  async queue(batch, env) {
+    for (const m of batch.messages) {
+      try {
+        await sendEmail(m.body);   // m.id, m.timestamp (Date), m.attempts, m.contentType
+        m.ack();
+      } catch {
+        m.retry({ delaySeconds: 60 }); // 不传则按队列退避
+      }
+    }
+    // 没 ack 也没 retry 的消息在函数正常返回后算确认；也可以 batch.ackAll() / batch.retryAll({ delaySeconds })
+  },
+  async alarm(info) {
+    // info.key, info.scheduledTime (ms), info.data, info.retryCount, info.isRetry
+    await endTrial(info.data);
+  },
+  async scheduled(controller) {
+    // controller.cron, controller.name, controller.scheduledTime (ms)
+    await cleanup();
+  },
+});
+```
+
+函数抛异常时回 500，平台会重试：队列是整批重试，定时器最多重试 6 次。某个来源没有对应函数时回 404。`env` 是 `process.env` 的快照；第三个参数 `ctx.waitUntil(promise)` 会让响应等这些 promise 结束。
+
+Next.js（App Router）、Hono、Bun、Deno：处理器就是 `(request: Request) => Promise<Response>`：
+
+```ts
+// app/api/berth/route.ts
+import { handler } from '@/lib/berth';
+export const POST = handler;
+```
+
+Node `http` / Express：用 `toNodeHandler`。它直接读原始请求流，不依赖 body parser。前面如果已经用了 `express.raw()`，它会用 `req.body`（Buffer 或字符串）。不要把它挂在 `express.json()` 后面：
+
+```ts
+import express from 'express';
+import { toNodeHandler } from '@evumi/berth';
+import { handler } from './berth.js';
+
+const app = express();
+app.post('/berth', toNodeHandler(handler)); // 放在 app.use(express.json()) 之前
+```
+
+只想自己校验签名时用 `verifySignature(secret, header, rawBody, { toleranceSeconds = 300 })`。它是同步的，返回布尔值，不抛异常。`checkSignature(...)` 返回失败原因：`'missing' | 'malformed' | 'expired' | 'mismatch'`，通过时返回 `null`。
+
+## 拉取（pull 队列）
+
+和 Cloudflare 的 HTTP pull 一样：
+
+```ts
+import { queue } from '@evumi/berth';
+
+const JOBS = queue('jobs');
+for (;;) {
+  const { messages } = await JOBS.pull({ batchSize: 10, visibilityTimeoutMs: 60_000 });
+  if (messages.length === 0) {
+    await new Promise((r) => setTimeout(r, 1000));
+    continue;
+  }
+  const acks: string[] = [];
+  const retries: { leaseId: string; delaySeconds?: number }[] = [];
+  for (const m of messages) {
+    try {
+      await handle(m.body); // m.id, m.leaseId, m.attempts, m.timestamp (ms), m.contentType
+      acks.push(m.leaseId);
+    } catch {
+      retries.push({ leaseId: m.leaseId, delaySeconds: 30 });
+    }
+  }
+  await JOBS.ack({ acks, retries }); // → { acked, retried, dead }
+}
+```
+
+`visibilityTimeoutMs` 内没 ack 的消息会换一个新 `leaseId` 再发一次。过期的 lease 会被忽略。
+
+## 定时器（Alarms）
+
+每个 key 一个，作用范围是整个环境，和 Durable Object 的 `storage.setAlarm` 一样：再设一次就是改时间，删掉就是取消。
+
+```ts
+import { alarm } from '@evumi/berth';
+
+const trialEnd = alarm(`trial-end:${userId}`);
+await trialEnd.setAlarm(Date.now() + 14 * 86_400_000, { data: { userId } }); // ms 或 Date；最多 365 天后
+const when = await trialEnd.getAlarm();   // ms，没有则为 null
+const pending = await trialEnd.get();     // { key, scheduledTime, data } 或 null
+await trialEnd.deleteAlarm();             // 没有也不报错
+```
+
+## 错误
+
+请求失败抛 `BerthError`，带 `status`、`code`、`message`（429 时还有 `retryAfterMs`）。`code` 取服务器返回的值：`unauthorized`、`capability_disabled`、`not_found`、`bad_request`、`conflict`、`too_large`、`rate_limited`、`quota_exceeded`、`unavailable`、`queue_full`。客户端自己的 `code`：`timeout`、`network`、`invalid_response`、`missing_env`。错误信息里不含令牌。
+
+## 开发
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test   # 先构建，再跑 vitest（含 sdk/testdata 的共享签名向量）
+```

package/dist/cjs/body.d.ts

@@ -0,0 +1,9 @@
+/** How a message body travels: a JSON value, a string, or bytes (base64 on the wire). */
+export type ContentType = 'json' | 'text' | 'bytes';
+/** body + content_type for the wire. Bytes bodies are sent as bytes whatever contentType says. */
+export declare function encodeBody(body: unknown, contentType?: ContentType): {
+    body: unknown;
+    content_type?: ContentType;
+};
+/** The body as the app sees it: JSON value, string, or Uint8Array. */
+export declare function decodeBody(body: unknown, contentType: string | undefined): unknown;

package/dist/cjs/body.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeBody = encodeBody;
+exports.decodeBody = decodeBody;
+const errors_js_1 = require("./errors.js");
+const util_js_1 = require("./util.js");
+const isBytes = (v) => v instanceof Uint8Array || v instanceof ArrayBuffer;
+/** body + content_type for the wire. Bytes bodies are sent as bytes whatever contentType says. */
+function encodeBody(body, contentType) {
+    if (isBytes(body))
+        return { body: (0, util_js_1.toBase64)(body instanceof Uint8Array ? body : new Uint8Array(body)), content_type: 'bytes' };
+    if (body === undefined)
+        throw new errors_js_1.BerthError('bad_request', 'body is required');
+    switch (contentType) {
+        case undefined:
+        case 'json':
+            return contentType ? { body, content_type: 'json' } : { body };
+        case 'text':
+            if (typeof body !== 'string')
+                throw new errors_js_1.BerthError('bad_request', 'contentType "text" needs a string body');
+            return { body, content_type: 'text' };
+        case 'bytes':
+            throw new errors_js_1.BerthError('bad_request', 'contentType "bytes" needs a Uint8Array or ArrayBuffer body');
+        default:
+            throw new errors_js_1.BerthError('bad_request', `unsupported contentType ${JSON.stringify(contentType)}`);
+    }
+}
+/** The body as the app sees it: JSON value, string, or Uint8Array. */
+function decodeBody(body, contentType) {
+    if (contentType !== 'bytes')
+        return body;
+    if (typeof body !== 'string')
+        throw new errors_js_1.BerthError('invalid_response', 'bytes body is not a base64 string');
+    return (0, util_js_1.fromBase64)(body);
+}

package/dist/cjs/client.d.ts

@@ -0,0 +1,111 @@
+import { type ContentType } from './body.js';
+export type { ContentType } from './body.js';
+export interface SendOptions {
+    /** json (default; any JSON value), text (a string) or bytes (Uint8Array/ArrayBuffer). Bytes bodies pick bytes themselves. */
+    contentType?: ContentType;
+    /** Delay before the first delivery, 0–604800. */
+    delaySeconds?: number;
+    /** The same dedupId on the same queue within 24 h stores nothing and returns the first id. */
+    dedupId?: string;
+}
+export interface SendResult {
+    id: string;
+    /** The dedupId was seen within 24 h: id is the first message's and nothing was stored. */
+    deduplicated: boolean;
+}
+export interface BatchMessage extends SendOptions {
+    body: unknown;
+}
+export interface PullOptions {
+    /** 1–100, default 10. */
+    batchSize?: number;
+    /** A message not acknowledged within this is handed out again with a new leaseId. 1000–43200000, default 30000. */
+    visibilityTimeoutMs?: number;
+}
+export interface PulledMessage<T = unknown> {
+    id: string;
+    /** Pass it to ack(). */
+    leaseId: string;
+    /** JSON value (json), string (text) or Uint8Array (bytes). */
+    body: T;
+    contentType: ContentType;
+    /** Starts at 1. */
+    attempts: number;
+    /** Send time, Unix milliseconds. */
+    timestamp: number;
+}
+export interface AckRequest {
+    acks?: string[];
+    /** Without delaySeconds the queue's backoff applies. */
+    retries?: {
+        leaseId: string;
+        delaySeconds?: number;
+    }[];
+}
+export interface AckResult {
+    acked: number;
+    retried: number;
+    /** Out of attempts: moved to the dead-letter list. */
+    dead: number;
+}
+/** A queue producer (and pull consumer), like a Workers Queue binding. */
+export interface Queue {
+    readonly name: string;
+    send(body: unknown, opts?: SendOptions): Promise<SendResult>;
+    /** Up to 100 messages; validation is all or nothing. opts.delaySeconds applies to messages without their own. */
+    sendBatch(messages: BatchMessage[], opts?: {
+        delaySeconds?: number;
+    }): Promise<{
+        ids: string[];
+        items: SendResult[];
+    }>;
+    /** Pull queues only. Maybe empty. */
+    pull<T = unknown>(opts?: PullOptions): Promise<{
+        messages: PulledMessage<T>[];
+    }>;
+    ack(req: AckRequest): Promise<AckResult>;
+}
+/** A named alarm of the environment, like a Durable Object's storage alarm. */
+export interface Alarm {
+    readonly key: string;
+    /** Sets (or moves) the alarm. scheduledTime: a Date or Unix milliseconds; a past time fires at once. */
+    setAlarm(scheduledTime: number | Date, opts?: {
+        data?: unknown;
+    }): Promise<void>;
+    /** The scheduled time in Unix milliseconds, or null when none is pending. */
+    getAlarm(): Promise<number | null>;
+    /** The pending alarm with its data, or null. */
+    get<T = unknown>(): Promise<{
+        key: string;
+        scheduledTime: number;
+        data: T;
+    } | null>;
+    /** Cancels the alarm; fine when there is none. */
+    deleteAlarm(): Promise<void>;
+}
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignal;
+}) => Promise<Response>;
+export interface ClientOptions {
+    /** Base URL without /v1. Default: env BERTH_CONFIG_URL, read at each request. */
+    url?: string;
+    /** Bearer token. Default: env BERTH_CONFIG_TOKEN, read at each request. */
+    token?: string;
+    /** Per request. Default 10000. */
+    timeoutMs?: number;
+    /** Custom fetch. Default: globalThis.fetch. */
+    fetch?: FetchLike;
+}
+export interface Client {
+    queue(name: string): Queue;
+    alarm(key: string): Alarm;
+}
+/** A client for queues and alarms. URL and token default to the environment, read lazily. */
+export declare function createClient(opts?: ClientOptions): Client;
+/** A queue of this environment, using BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN (read at each request). */
+export declare const queue: (name: string) => Queue;
+/** A named alarm of this environment, using BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN (read at each request). */
+export declare const alarm: (key: string) => Alarm;

package/dist/cjs/client.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alarm = exports.queue = void 0;
+exports.createClient = createClient;
+const errors_js_1 = require("./errors.js");
+const body_js_1 = require("./body.js");
+const util_js_1 = require("./util.js");
+function wireMessage(body, o) {
+    const out = (0, body_js_1.encodeBody)(body, o.contentType);
+    if (o.delaySeconds !== undefined)
+        out.delay_seconds = o.delaySeconds;
+    if (o.dedupId !== undefined)
+        out.dedup_id = o.dedupId;
+    return out;
+}
+/** Scheduled time from the wire: Unix ms, or an RFC 3339 string. */
+function toMs(v) {
+    if (typeof v === 'number')
+        return v;
+    const t = typeof v === 'string' ? Date.parse(v) : Number.NaN;
+    if (Number.isNaN(t))
+        throw new errors_js_1.BerthError('invalid_response', 'scheduled_time is neither Unix ms nor RFC 3339');
+    return t;
+}
+const seg = (s) => encodeURIComponent(s);
+/** A client for queues and alarms. URL and token default to the environment, read lazily. */
+function createClient(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    async function request(method, path, body) {
+        const url = opts.url ?? (0, util_js_1.env)('BERTH_CONFIG_URL');
+        const token = opts.token ?? (0, util_js_1.env)('BERTH_CONFIG_TOKEN');
+        if (!url || !token)
+            throw new errors_js_1.BerthError('missing_env', 'BERTH_CONFIG_URL and BERTH_CONFIG_TOKEN are not set');
+        const base = url.replace(/\/+$/, '').replace(/\/v1$/, '') + '/v1';
+        const f = opts.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new errors_js_1.BerthError('network', 'no fetch available: pass one in createClient({ fetch })');
+        const headers = { authorization: `Bearer ${token}`, accept: 'application/json' };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        const ctrl = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => ((timedOut = true), ctrl.abort()), timeoutMs);
+        timer.unref?.();
+        let status;
+        let text;
+        let retryAfter;
+        try {
+            const res = await f(base + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: ctrl.signal });
+            status = res.status;
+            retryAfter = res.headers.get('retry-after');
+            text = await res.text();
+        }
+        catch (e) {
+            if (timedOut)
+                throw new errors_js_1.BerthError('timeout', `request timed out after ${timeoutMs} ms`);
+            throw new errors_js_1.BerthError('network', `request failed: ${e?.message ?? e}`, { cause: e });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (status < 200 || status > 299)
+            throw (0, errors_js_1.responseError)(status, text, retryAfter);
+        if (status === 204 || text === '')
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch (e) {
+            throw new errors_js_1.BerthError('invalid_response', 'response is not JSON', { status, cause: e });
+        }
+    }
+    function queue(name) {
+        const p = `/queues/${seg(name)}/messages`;
+        return {
+            name,
+            async send(body, o = {}) {
+                return request('POST', p, wireMessage(body, o));
+            },
+            async sendBatch(messages, o = {}) {
+                const req = {
+                    messages: messages.map((m) => {
+                        if (m === null || typeof m !== 'object' || !('body' in m))
+                            throw new errors_js_1.BerthError('bad_request', 'a batch message is { body, contentType?, delaySeconds?, dedupId? }');
+                        return wireMessage(m.body, m);
+                    }),
+                };
+                if (o.delaySeconds !== undefined)
+                    req.delay_seconds = o.delaySeconds;
+                const r = await request('POST', `${p}/batch`, req);
+                const items = r?.items ?? [];
+                return { ids: items.map((i) => i.id), items };
+            },
+            async pull(o = {}) {
+                const req = {};
+                if (o.batchSize !== undefined)
+                    req.batch_size = o.batchSize;
+                if (o.visibilityTimeoutMs !== undefined)
+                    req.visibility_timeout_ms = o.visibilityTimeoutMs;
+                const r = await request('POST', `${p}/pull`, req);
+                return {
+                    messages: (r?.messages ?? []).map((m) => {
+                        const contentType = (m.content_type || 'json');
+                        return {
+                            id: String(m.id),
+                            leaseId: String(m.lease_id),
+                            body: (0, body_js_1.decodeBody)(m.body, contentType),
+                            contentType,
+                            attempts: Number(m.attempts ?? 0),
+                            timestamp: Number(m.timestamp_ms ?? 0),
+                        };
+                    }),
+                };
+            },
+            async ack(req) {
+                const body = {
+                    acks: (req.acks ?? []).map((lease_id) => ({ lease_id })),
+                    retries: (req.retries ?? []).map((r) => (r.delaySeconds === undefined ? { lease_id: r.leaseId } : { lease_id: r.leaseId, delay_seconds: r.delaySeconds })),
+                };
+                return request('POST', `${p}/ack`, body);
+            },
+        };
+    }
+    function alarm(key) {
+        const p = `/alarms/${seg(key)}`;
+        const get = async () => {
+            try {
+                const a = await request('GET', p);
+                return { key: a.key, scheduledTime: toMs(a.scheduled_time), data: a.data };
+            }
+            catch (e) {
+                if (e instanceof errors_js_1.BerthError && e.status === 404 && e.code === 'not_found')
+                    return null;
+                throw e;
+            }
+        };
+        return {
+            key,
+            async setAlarm(scheduledTime, o = {}) {
+                const ms = scheduledTime instanceof Date ? scheduledTime.getTime() : scheduledTime;
+                if (typeof ms !== 'number' || !Number.isFinite(ms))
+                    throw new errors_js_1.BerthError('bad_request', 'scheduledTime must be a Date or Unix milliseconds');
+                const body = { scheduled_time: Math.round(ms) };
+                if (o.data !== undefined)
+                    body.data = o.data;
+                await request('PUT', p, body);
+            },
+            async getAlarm() {
+                return (await get())?.scheduledTime ?? null;
+            },
+            get,
+            async deleteAlarm() {
+                await request('DELETE', p);
+            },
+        };
+    }
+    return { queue, alarm };
+}
+const defaultClient = createClient();
+/** A queue of this environment, using BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN (read at each request). */
+const queue = (name) => defaultClient.queue(name);
+exports.queue = queue;
+/** A named alarm of this environment, using BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN (read at each request). */
+const alarm = (key) => defaultClient.alarm(key);
+exports.alarm = alarm;

package/dist/cjs/errors.d.ts

@@ -0,0 +1,19 @@
+/** Error codes. Server codes come from the response body; the last four are raised by the client. */
+export type ErrorCode = 'unauthorized' | 'capability_disabled' | 'not_found' | 'bad_request' | 'conflict' | 'too_large' | 'rate_limited' | 'quota_exceeded' | 'unavailable' | 'queue_full' | 'timeout' | 'network' | 'invalid_response' | 'missing_env' | (string & {});
+export declare class BerthError extends Error {
+    name: string;
+    readonly code: ErrorCode;
+    /** HTTP status, when the error came from a response. */
+    readonly status?: number;
+    /** Parsed Retry-After, for 429 responses. */
+    readonly retryAfterMs?: number;
+    constructor(code: ErrorCode, message: string, extra?: {
+        status?: number;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+/** Builds an error from a non-2xx response body of the form {"error":{"code","message"}}. */
+export declare function responseError(status: number, body: string, retryAfter: string | null): BerthError;
+/** Retry-After is either delta-seconds or an HTTP date. */
+export declare function parseRetryAfter(v: string | null): number | undefined;

package/dist/cjs/errors.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BerthError = void 0;
+exports.responseError = responseError;
+exports.parseRetryAfter = parseRetryAfter;
+class BerthError extends Error {
+    name = 'BerthError';
+    code;
+    /** HTTP status, when the error came from a response. */
+    status;
+    /** Parsed Retry-After, for 429 responses. */
+    retryAfterMs;
+    constructor(code, message, extra = {}) {
+        super(message, extra.cause === undefined ? undefined : { cause: extra.cause });
+        this.code = code;
+        this.status = extra.status;
+        this.retryAfterMs = extra.retryAfterMs;
+    }
+}
+exports.BerthError = BerthError;
+const statusCodes = {
+    400: 'bad_request',
+    401: 'unauthorized',
+    403: 'unauthorized',
+    404: 'not_found',
+    409: 'conflict',
+    413: 'too_large',
+    429: 'rate_limited',
+    507: 'queue_full',
+};
+/** Builds an error from a non-2xx response body of the form {"error":{"code","message"}}. */
+function responseError(status, body, retryAfter) {
+    let code = statusCodes[status] ?? (status >= 500 ? 'unavailable' : 'bad_request');
+    let message = `request failed with HTTP ${status}`;
+    try {
+        const e = JSON.parse(body)?.error;
+        if (typeof e?.code === 'string' && e.code)
+            code = e.code;
+        if (typeof e?.message === 'string' && e.message)
+            message = e.message;
+    }
+    catch {
+        // Non-JSON error body (proxy page etc.): keep the generic message.
+    }
+    return new BerthError(code, message, { status, retryAfterMs: status === 429 ? parseRetryAfter(retryAfter) : undefined });
+}
+/** Retry-After is either delta-seconds or an HTTP date. */
+function parseRetryAfter(v) {
+    if (!v)
+        return undefined;
+    const s = Number(v);
+    if (Number.isFinite(s))
+        return Math.max(0, s * 1000);
+    const t = Date.parse(v);
+    return Number.isNaN(t) ? undefined : Math.max(0, t - Date.now());
+}

package/dist/cjs/handler.d.ts

@@ -0,0 +1,83 @@
+import { type ContentType } from './body.js';
+export type Env = Record<string, string | undefined>;
+/** One message of a pushed batch, like a Workers Queue Message. */
+export interface Message<T = unknown> {
+    readonly id: string;
+    /** Send time. */
+    readonly timestamp: Date;
+    /** JSON value (json), string (text) or Uint8Array (bytes). */
+    readonly body: T;
+    readonly contentType: ContentType;
+    /** Starts at 1. */
+    readonly attempts: number;
+    /** Acknowledge this message even if the batch is retried. */
+    ack(): void;
+    /** Retry this message (after delaySeconds, else with the backoff). */
+    retry(opts?: {
+        delaySeconds?: number;
+    }): void;
+}
+/** A pushed batch, like a Workers MessageBatch. Messages not acked or retried are acknowledged when the handler returns. */
+export interface MessageBatch<T = unknown> {
+    readonly queue: string;
+    readonly messages: readonly Message<T>[];
+    ackAll(): void;
+    retryAll(opts?: {
+        delaySeconds?: number;
+    }): void;
+}
+export interface AlarmInfo<T = unknown> {
+    key: string;
+    /** Unix milliseconds. */
+    scheduledTime: number;
+    data: T;
+    retryCount: number;
+    isRetry: boolean;
+}
+/** A Cron HTTP target call, like a Workers ScheduledController. */
+export interface ScheduledController {
+    cron: string;
+    /** Unix milliseconds. */
+    scheduledTime: number;
+    name: string;
+    /** Accepted for Workers compatibility; does nothing. */
+    noRetry(): void;
+}
+export interface ExecutionContext {
+    /** The response waits for these (failures are ignored). */
+    waitUntil(p: Promise<unknown>): void;
+}
+export interface Handlers {
+    queue?(batch: MessageBatch<any>, env: Env, ctx: ExecutionContext): unknown | Promise<unknown>;
+    alarm?(alarm: AlarmInfo<any>, env: Env, ctx: ExecutionContext): unknown | Promise<unknown>;
+    scheduled?(controller: ScheduledController, env: Env, ctx: ExecutionContext): unknown | Promise<unknown>;
+    /** Default: env BERTH_SIGNING_SECRET, read at each request. */
+    secret?: string;
+    /** Default 300. */
+    toleranceSeconds?: number;
+}
+export type FetchHandler = (request: Request) => Promise<Response>;
+/**
+ * A Fetch API handler for everything the platform pushes: queue batches, alarms and Cron HTTP
+ * targets, told apart by Berth-Source. It verifies Berth-Signature (401 when it fails), calls the
+ * matching handler and answers the platform: 200 with the batch settlement, 204 for an alarm or
+ * cron call, 500 when the handler throws (the platform retries), 404 when there is no handler.
+ */
+export declare function createHandler(handlers: Handlers): FetchHandler;
+/** The parts of node:http's IncomingMessage (or an Express request) toNodeHandler uses. */
+export interface NodeRequest extends AsyncIterable<unknown> {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** Set by body parsers. A Buffer or string is used as the raw body; anything else is ignored. */
+    body?: unknown;
+    readableEnded?: boolean;
+}
+/** The parts of node:http's ServerResponse used. */
+export interface NodeResponse {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(chunk?: Uint8Array | string): unknown;
+}
+/** Adapts a Fetch handler to node:http / Express: `app.post('/berth', toNodeHandler(handler))`. */
+export declare function toNodeHandler(handler: FetchHandler): (req: NodeRequest, res: NodeResponse) => Promise<void>;