@evumi/berth 0.0.0-stage → 0.0.3

package/dist/cjs/handler.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHandler = createHandler;
+exports.toNodeHandler = toNodeHandler;
+const body_js_1 = require("./body.js");
+const signature_js_1 = require("./signature.js");
+const util_js_1 = require("./util.js");
+function snapshotEnv() {
+    const g = globalThis;
+    return { ...(g.process?.env ?? {}) };
+}
+const json = (status, v) => new Response(JSON.stringify(v), { status, headers: { 'content-type': 'application/json' } });
+const text = (status, s) => new Response(s, { status, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+function makeBatch(raw) {
+    const settle = { acks: [], retries: [] };
+    const decided = new Set();
+    const delay = (o) => (o?.delaySeconds === undefined ? {} : { delaySeconds: o.delaySeconds });
+    const list = Array.isArray(raw.messages) ? raw.messages : [];
+    const messages = list.map((m) => {
+        const id = String(m.id);
+        const contentType = (m.contentType || 'json');
+        return {
+            id,
+            timestamp: new Date(Number(m.timestamp)),
+            body: (0, body_js_1.decodeBody)(m.body, contentType),
+            contentType,
+            attempts: Number(m.attempts ?? 1),
+            // The first call on a message wins, as in Workers.
+            ack() {
+                if (decided.has(id))
+                    return;
+                decided.add(id);
+                settle.acks.push(id);
+            },
+            retry(o) {
+                if (decided.has(id))
+                    return;
+                decided.add(id);
+                settle.retries.push({ id, ...delay(o) });
+            },
+        };
+    });
+    const batch = {
+        queue: String(raw.queue ?? ''),
+        messages,
+        ackAll() {
+            settle.ackAll = true;
+            delete settle.retryAll;
+        },
+        retryAll(o) {
+            settle.retryAll = delay(o);
+            delete settle.ackAll;
+        },
+    };
+    return { batch, settle };
+}
+/**
+ * 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.
+ */
+function createHandler(handlers) {
+    return async (request) => {
+        const secret = handlers.secret ?? (0, util_js_1.env)('BERTH_SIGNING_SECRET') ?? '';
+        const raw = new Uint8Array(await request.arrayBuffer());
+        if (!secret)
+            return text(401, 'BERTH_SIGNING_SECRET is not set');
+        const bad = (0, signature_js_1.checkSignature)(secret, request.headers.get('Berth-Signature'), raw, { toleranceSeconds: handlers.toleranceSeconds });
+        if (bad)
+            return text(401, `invalid signature: ${bad}`);
+        let payload;
+        try {
+            payload = JSON.parse(new TextDecoder().decode(raw)) ?? {};
+        }
+        catch {
+            return text(400, 'body is not JSON');
+        }
+        const env = snapshotEnv();
+        const pending = [];
+        const ctx = { waitUntil: (p) => void pending.push(Promise.resolve(p).catch(() => { })) };
+        const source = request.headers.get('Berth-Source');
+        try {
+            switch (source) {
+                case 'queue': {
+                    if (!handlers.queue)
+                        return text(404, 'no queue handler');
+                    const { batch, settle } = makeBatch(payload);
+                    await handlers.queue(batch, env, ctx);
+                    await Promise.all(pending);
+                    return json(200, settle);
+                }
+                case 'alarm': {
+                    if (!handlers.alarm)
+                        return text(404, 'no alarm handler');
+                    await handlers.alarm({
+                        key: String(payload.key ?? ''),
+                        scheduledTime: Number(payload.scheduledTime),
+                        data: payload.data,
+                        retryCount: Number(payload.retryCount ?? 0),
+                        isRetry: Boolean(payload.isRetry),
+                    }, env, ctx);
+                    break;
+                }
+                case 'cron': {
+                    if (!handlers.scheduled)
+                        return text(404, 'no scheduled handler');
+                    await handlers.scheduled({ cron: String(payload.cron ?? ''), scheduledTime: Number(payload.scheduledTime), name: String(payload.name ?? ''), noRetry() { } }, env, ctx);
+                    break;
+                }
+                default:
+                    return text(404, `unknown Berth-Source ${JSON.stringify(source)}`);
+            }
+            await Promise.all(pending);
+            return new Response(null, { status: 204 });
+        }
+        catch (e) {
+            await Promise.all(pending);
+            return text(500, `handler failed: ${e?.message ?? e}`);
+        }
+    };
+}
+async function readNodeBody(req) {
+    if (req.body instanceof Uint8Array)
+        return new Uint8Array(req.body); // Buffer, e.g. express.raw()
+    if (typeof req.body === 'string')
+        return new TextEncoder().encode(req.body);
+    if (req.readableEnded) {
+        throw new Error('the request body was already read by a parser; mount this handler before express.json() or use express.raw()');
+    }
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(typeof c === 'string' ? new TextEncoder().encode(c) : c);
+    let len = 0;
+    for (const c of chunks)
+        len += c.length;
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}
+/** Adapts a Fetch handler to node:http / Express: `app.post('/berth', toNodeHandler(handler))`. */
+function toNodeHandler(handler) {
+    return async (req, res) => {
+        let response;
+        try {
+            const body = await readNodeBody(req);
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers)) {
+                if (v === undefined)
+                    continue;
+                headers.set(k, Array.isArray(v) ? v.join(', ') : v);
+            }
+            const host = headers.get('host') ?? 'localhost';
+            const method = req.method ?? 'POST';
+            response = await handler(new Request(new URL(req.url ?? '/', `http://${host}`), { method, headers, body: method === 'GET' || method === 'HEAD' ? undefined : body }));
+        }
+        catch (e) {
+            response = text(400, e?.message ?? String(e));
+        }
+        res.statusCode = response.status;
+        response.headers.forEach((v, k) => void res.setHeader(k, v));
+        res.end(new Uint8Array(await response.arrayBuffer()));
+    };
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,4 @@
+export { BerthError, type ErrorCode } from './errors.js';
+export { type AckRequest, type AckResult, type Alarm, type BatchMessage, type Client, type ClientOptions, type ContentType, type FetchLike, type PulledMessage, type PullOptions, type Queue, type SendOptions, type SendResult, alarm, createClient, queue, } from './client.js';
+export { type AlarmInfo, type Env, type ExecutionContext, type FetchHandler, type Handlers, type Message, type MessageBatch, type NodeRequest, type NodeResponse, type ScheduledController, createHandler, toNodeHandler, } from './handler.js';
+export { type RawBody, type SignatureError, type VerifyOptions, checkSignature, verifySignature } from './signature.js';

package/dist/cjs/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifySignature = exports.checkSignature = exports.toNodeHandler = exports.createHandler = exports.queue = exports.createClient = exports.alarm = exports.BerthError = void 0;
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "BerthError", { enumerable: true, get: function () { return errors_js_1.BerthError; } });
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "alarm", { enumerable: true, get: function () { return client_js_1.alarm; } });
+Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_js_1.createClient; } });
+Object.defineProperty(exports, "queue", { enumerable: true, get: function () { return client_js_1.queue; } });
+var handler_js_1 = require("./handler.js");
+Object.defineProperty(exports, "createHandler", { enumerable: true, get: function () { return handler_js_1.createHandler; } });
+Object.defineProperty(exports, "toNodeHandler", { enumerable: true, get: function () { return handler_js_1.toNodeHandler; } });
+var signature_js_1 = require("./signature.js");
+Object.defineProperty(exports, "checkSignature", { enumerable: true, get: function () { return signature_js_1.checkSignature; } });
+Object.defineProperty(exports, "verifySignature", { enumerable: true, get: function () { return signature_js_1.verifySignature; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/sha256.d.ts

@@ -0,0 +1,5 @@
+/** SHA-256 of the concatenation of parts. */
+export declare function sha256(...parts: Uint8Array[]): Uint8Array;
+/** HMAC-SHA256(key, concatenation of parts). */
+export declare function hmacSha256(key: Uint8Array, ...parts: Uint8Array[]): Uint8Array;
+export declare function toHex(b: Uint8Array): string;

package/dist/cjs/sha256.js

@@ -0,0 +1,98 @@
+"use strict";
+// Synchronous HMAC-SHA256 in plain JS. verifySignature has to be synchronous and run in edge
+// runtimes too, where node:crypto is absent and WebCrypto is async only. Bodies are at most
+// 256 KiB, so speed does not matter much. Checked against node:crypto in the tests.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256 = sha256;
+exports.hmacSha256 = hmacSha256;
+exports.toHex = toHex;
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** SHA-256 of the concatenation of parts. */
+function sha256(...parts) {
+    let len = 0;
+    for (const p of parts)
+        len += p.length;
+    // Message + 0x80 + zero padding + 64-bit big-endian bit length, a multiple of 64 bytes.
+    const total = Math.ceil((len + 9) / 64) * 64;
+    const buf = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) {
+        buf.set(p, off);
+        off += p.length;
+    }
+    buf[len] = 0x80;
+    const view = new DataView(buf.buffer);
+    const bits = len * 8;
+    view.setUint32(total - 8, Math.floor(bits / 0x100000000));
+    view.setUint32(total - 4, bits >>> 0);
+    const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const w = new Uint32Array(64);
+    for (let i = 0; i < total; i += 64) {
+        for (let t = 0; t < 16; t++)
+            w[t] = view.getUint32(i + t * 4);
+        for (let t = 16; t < 64; t++) {
+            const a = w[t - 15];
+            const b = w[t - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[t] = (w[t - 16] + s0 + w[t - 7] + s1) | 0;
+        }
+        let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], hh = h[7];
+        for (let t = 0; t < 64; t++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (hh + S1 + ch + K[t] + w[t]) | 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) | 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h[0] = (h[0] + a) | 0;
+        h[1] = (h[1] + b) | 0;
+        h[2] = (h[2] + c) | 0;
+        h[3] = (h[3] + d) | 0;
+        h[4] = (h[4] + e) | 0;
+        h[5] = (h[5] + f) | 0;
+        h[6] = (h[6] + g) | 0;
+        h[7] = (h[7] + hh) | 0;
+    }
+    const out = new Uint8Array(32);
+    const ov = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++)
+        ov.setUint32(i * 4, h[i]);
+    return out;
+}
+/** HMAC-SHA256(key, concatenation of parts). */
+function hmacSha256(key, ...parts) {
+    const k = key.length > 64 ? sha256(key) : key;
+    const block = new Uint8Array(64);
+    block.set(k);
+    const ipad = new Uint8Array(64);
+    const opad = new Uint8Array(64);
+    for (let i = 0; i < 64; i++) {
+        ipad[i] = block[i] ^ 0x36;
+        opad[i] = block[i] ^ 0x5c;
+    }
+    return sha256(opad, sha256(ipad, ...parts));
+}
+const HEX = '0123456789abcdef';
+function toHex(b) {
+    let s = '';
+    for (const x of b)
+        s += HEX[x >> 4] + HEX[x & 15];
+    return s;
+}

package/dist/cjs/signature.d.ts

@@ -0,0 +1,20 @@
+/** Why a signature was rejected. */
+export type SignatureError = 'missing' | 'malformed' | 'expired' | 'mismatch';
+export interface VerifyOptions {
+    /** The receiver's clock: a Date or unix seconds. Default: now. */
+    now?: Date | number;
+    /** How far the signature's timestamp may be from now, both ways. Default 300. */
+    toleranceSeconds?: number;
+}
+export type RawBody = string | Uint8Array | ArrayBuffer;
+/**
+ * Checks a Berth-Signature header (`t=<unix>,v1=<hex>`) against the raw request body and says
+ * why it fails, or null when it is valid. Synchronous; never throws. Several v1 values are
+ * accepted (one must match), so the secret can be rotated; unknown keys are ignored.
+ */
+export declare function checkSignature(secret: string | Uint8Array, header: string | null | undefined, rawBody: RawBody, opts?: VerifyOptions): SignatureError | null;
+/**
+ * Whether a Berth-Signature header is valid for the raw request body. Verify the bytes as they
+ * arrived, before any JSON parsing. Synchronous; never throws.
+ */
+export declare function verifySignature(secret: string | Uint8Array, header: string | null | undefined, rawBody: RawBody, opts?: VerifyOptions): boolean;

package/dist/cjs/signature.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSignature = checkSignature;
+exports.verifySignature = verifySignature;
+const sha256_js_1 = require("./sha256.js");
+const utf8 = new TextEncoder();
+const bytes = (v) => (typeof v === 'string' ? utf8.encode(v) : v instanceof Uint8Array ? v : new Uint8Array(v));
+const INT64_MAX = (1n << 63n) - 1n;
+const INT64_MIN = -(1n << 63n);
+/**
+ * Checks a Berth-Signature header (`t=<unix>,v1=<hex>`) against the raw request body and says
+ * why it fails, or null when it is valid. Synchronous; never throws. Several v1 values are
+ * accepted (one must match), so the secret can be rotated; unknown keys are ignored.
+ */
+function checkSignature(secret, header, rawBody, opts = {}) {
+    try {
+        if (typeof header !== 'string' || header.trim() === '')
+            return 'missing';
+        let t;
+        const sigs = [];
+        for (const part of header.split(',')) {
+            const p = part.trim();
+            const i = p.indexOf('=');
+            if (i < 0)
+                return 'malformed';
+            const k = p.slice(0, i);
+            const v = p.slice(i + 1);
+            if (k === 't') {
+                if (t !== undefined || !/^[+-]?[0-9]+$/.test(v))
+                    return 'malformed';
+                t = BigInt(v);
+                if (t > INT64_MAX || t < INT64_MIN)
+                    return 'malformed';
+            }
+            else if (k === 'v1') {
+                sigs.push(v);
+            }
+        }
+        if (t === undefined || sigs.length === 0)
+            return 'malformed';
+        const nowOpt = opts.now ?? Date.now() / 1000;
+        const now = BigInt(Math.floor(nowOpt instanceof Date ? nowOpt.getTime() / 1000 : nowOpt));
+        const tolerance = BigInt(Math.floor(opts.toleranceSeconds ?? 300));
+        const d = now - t;
+        if ((d < 0n ? -d : d) > tolerance)
+            return 'expired';
+        const key = typeof secret === 'string' ? utf8.encode(secret) : secret;
+        const want = (0, sha256_js_1.toHex)((0, sha256_js_1.hmacSha256)(key, utf8.encode(t.toString() + '.'), bytes(rawBody)));
+        let ok = false;
+        for (const s of sigs)
+            if (equal(s.toLowerCase(), want))
+                ok = true;
+        return ok ? null : 'mismatch';
+    }
+    catch {
+        return 'malformed';
+    }
+}
+/** Constant time for equal lengths; the length of a hex HMAC is public. */
+function equal(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * Whether a Berth-Signature header is valid for the raw request body. Verify the bytes as they
+ * arrived, before any JSON parsing. Synchronous; never throws.
+ */
+function verifySignature(secret, header, rawBody, opts) {
+    return checkSignature(secret, header, rawBody, opts) === null;
+}

package/dist/cjs/util.d.ts

@@ -0,0 +1,3 @@
+export declare function env(name: string): string | undefined;
+export declare function toBase64(b: Uint8Array): string;
+export declare function fromBase64(s: string): Uint8Array;

package/dist/cjs/util.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.env = env;
+exports.toBase64 = toBase64;
+exports.fromBase64 = fromBase64;
+function env(name) {
+    const g = globalThis;
+    try {
+        return g.process?.env?.[name] ?? g.Deno?.env.get(name) ?? undefined;
+    }
+    catch {
+        return undefined; // Deno without --allow-env
+    }
+}
+function toBase64(b) {
+    let s = '';
+    for (let i = 0; i < b.length; i += 0x8000)
+        s += String.fromCharCode(...b.subarray(i, i + 0x8000));
+    return btoa(s);
+}
+function fromBase64(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}

package/dist/esm/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/esm/body.js

@@ -0,0 +1,31 @@
+import { BerthError } from './errors.js';
+import { fromBase64, toBase64 } from './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. */
+export function encodeBody(body, contentType) {
+    if (isBytes(body))
+        return { body: toBase64(body instanceof Uint8Array ? body : new Uint8Array(body)), content_type: 'bytes' };
+    if (body === undefined)
+        throw new 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 BerthError('bad_request', 'contentType "text" needs a string body');
+            return { body, content_type: 'text' };
+        case 'bytes':
+            throw new BerthError('bad_request', 'contentType "bytes" needs a Uint8Array or ArrayBuffer body');
+        default:
+            throw new BerthError('bad_request', `unsupported contentType ${JSON.stringify(contentType)}`);
+    }
+}
+/** The body as the app sees it: JSON value, string, or Uint8Array. */
+export function decodeBody(body, contentType) {
+    if (contentType !== 'bytes')
+        return body;
+    if (typeof body !== 'string')
+        throw new BerthError('invalid_response', 'bytes body is not a base64 string');
+    return fromBase64(body);
+}

package/dist/esm/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;