@acid-cat/core-ts 0.9.0 → 0.10.1

package/dist/session.d.ts

@@ -1,5 +1,34 @@
-import type { Availability, CatalogDocument, Outcome, Result } from "@acid-cat/spec-ts";
-import type { App, Capability, FailureOf, Observable, ToJsonSchema } from "./app.js";
+import type { Availability, CallFailure, CatalogDocument, Outcome, Result } from "@acid-cat/spec-ts";
+import type { App, Capability, EventDefinition, FailureOf, Observable, ToJsonSchema } from "./app.js";
+import type { Occurrences } from "./subscription.js";
+/** The options of a subscription (spec/bindings/typescript.md#event-handles). */
+export interface SubscribeOptions {
+    /** Cancel the subscription. */
+    readonly signal?: AbortSignal | undefined;
+    /** Start after this position (spec/events.md#resuming). */
+    readonly cursor?: string | undefined;
+    /** Send no occurrence that is older than this number of milliseconds. */
+    readonly maxAgeMs?: number | undefined;
+}
+/**
+ * The handle of an event (spec/bindings/typescript.md#event-handles). `session.eventHandle` gives a handle with the
+ * types of the event. A handle of `session.eventHandles` has the input type `never`: only `subscribeExternal` can
+ * subscribe with it, because it decodes the input.
+ */
+export interface EventHandle<Input = never, Payload = unknown> {
+    readonly id: string;
+    readonly description: string;
+    readonly audience: readonly string[];
+    /**
+     * A subscription with an input that is already valid. The promise resolves when the subscription has started. A call
+     * failure before the first occurrence rejects with a `CallFailureError`.
+     */
+    subscribe(input: Input, options?: SubscribeOptions): Promise<Occurrences<Payload>>;
+    /** A subscription with an input that is not trusted. The handle validates it first. */
+    subscribeExternal(input: unknown, options?: SubscribeOptions): Promise<Occurrences<unknown>>;
+}
+/** The handle of an event, with the types of its schemas. `session.eventHandle` gives it. */
+export type EventHandleOf<E> = E extends EventDefinition<never, infer Input, infer Payload, string> ? EventHandle<Input, Payload> : never;
 /**
  * The handle of a capability (spec/bindings/typescript.md#handles). `Input`, `Value`, `Failure` and `State` are the
  * types of the schemas of the capability. `session.handle` gives a handle with these types. A handle of
@@ -47,6 +76,19 @@ export interface Session<Context = unknown> {
     readonly call: <Input, Value, Failures, State, Id extends string>(capability: Capability<Context, Input, Value, Failures, State, Id>, input: unknown, options?: {
         readonly signal?: AbortSignal | undefined;
     }) => Promise<Result<Value, FailureOf<Failures>>>;
+    /** The handles of the events in the view, by id. Bindings use them. */
+    readonly eventHandles: ReadonlyMap<string, EventHandle>;
+    /**
+     * The handle of an event, with the types of the event. Only the event object that the session serves gets a handle
+     * that subscribes to it. Any other event, also one with the same id, gets a handle whose subscriptions reject as
+     * `unknown-capability`.
+     */
+    readonly eventHandle: <Input, Payload, Id extends string>(event: EventDefinition<Context, Input, Payload, Id>) => EventHandle<Input, Payload>;
+    /**
+     * A subscription with an input that is not trusted. The promise never rejects: it gives the occurrences, or the call
+     * failure before the first occurrence.
+     */
+    readonly subscribe: (id: string, input: unknown, options?: SubscribeOptions) => Promise<Occurrences<unknown> | CallFailure>;
     /** A call with an input that is not trusted. The outcome is in its JSON form. The promise never rejects. */
     readonly invoke: (id: string, input: unknown, options?: {
         readonly signal?: AbortSignal | undefined;
@@ -60,7 +102,10 @@ export interface Session<Context = unknown> {
     };
     /** The signal of the session. It aborts when the session closes. */
     readonly signal: AbortSignal;
-    /** Close the session: accept no new calls, cancel the calls in progress, and wait for them. */
+    /**
+     * Close the session: accept no new calls and subscriptions, cancel the calls in progress, end each subscription as
+     * complete, and wait for the calls.
+     */
     readonly dispose: () => Promise<void>;
     /** Close the session, as `dispose` does, at the end of the block of `await using session = createSession(…)`. */
     readonly [Symbol.asyncDispose]: () => Promise<void>;
@@ -72,6 +117,16 @@ export interface SessionOptions<Context> {
     readonly toJsonSchema: ToJsonSchema;
     /** Record a defect. The default writes it to the console. */
     readonly onDefect?: ((id: string, cause: unknown) => void) | undefined;
+    /**
+     * The number of occurrences that each subscription keeps for a client that reads slowly. When the limit is full, the
+     * oldest occurrence goes, and the next occurrence that the client reads has `truncated: true`. The default is 256.
+     */
+    readonly bufferLimit?: number | undefined;
 }
+/**
+ * True if `maxAgeMs` is absent, or an integer that is 0 or more (spec/events.md#resuming). A session rejects another
+ * value as `invalid-input`, after it checks the id of the event.
+ */
+export declare const isMaxAgeMs: (maxAgeMs: number | undefined) => boolean;
 /** Open a session for a target. */
 export declare function createSession<Context>(app: App<Context>, options: SessionOptions<Context>): Session<Context>;

package/dist/session.js

@@ -1,9 +1,21 @@
 import { catalogOf } from "./app.js";
+import { runSubscription } from "./subscription.js";
 import { AVAILABLE, CallFailureError, callFailure, isCallFailure, viewOf } from "@acid-cat/spec-ts";
-//#region src/session.ts
+// src/session.ts
 /**
 * Sessions and handles (spec/invocation.md, spec/bindings/typescript.md).
 */
+/** The handle of an event that the session does not serve. Each subscription rejects as `unknown-capability`. */
+function eventOutsideView(event) {
+	const reject = () => Promise.reject(new CallFailureError(callFailure("unknown-capability", `There is no event ${event.id}.`)));
+	return {
+		id: event.id,
+		description: event.description,
+		audience: [],
+		subscribe: reject,
+		subscribeExternal: reject
+	};
+}
 /** The handle of a capability that the session does not serve. */
 function outsideView(capability) {
 	const failure = callFailure("unknown-capability", `There is no capability ${capability.id}.`);
@@ -24,6 +36,11 @@ function outsideView(capability) {
 		invokeExternal: reject
 	};
 }
+/**
+* True if `maxAgeMs` is absent, or an integer that is 0 or more (spec/events.md#resuming). A session rejects another
+* value as `invalid-input`, after it checks the id of the event.
+*/
+const isMaxAgeMs = (maxAgeMs) => maxAgeMs === void 0 || Number.isSafeInteger(maxAgeMs) && maxAgeMs >= 0;
 const always = {
 	getSnapshot: () => AVAILABLE,
 	subscribe: () => ({ unsubscribe() {} })
@@ -34,7 +51,7 @@ function createSession(app, options) {
 	const running = /* @__PURE__ */ new Set();
 	const listeners = /* @__PURE__ */ new Set();
 	let subscriptions = [];
-	const onDefect = options.onDefect ?? ((id, cause) => console.error(`A capability failed with a defect: ${id}`, cause));
+	const onDefect = options.onDefect ?? ((id, cause) => console.error(`A capability or an event failed with a defect: ${id}`, cause));
 	const served = /* @__PURE__ */ new Map();
 	for (const capability of app.capabilities) {
 		if (!capability.audience.includes(options.target)) continue;
@@ -53,7 +70,13 @@ function createSession(app, options) {
 		if (lifetime.signal.aborted || signal?.aborted) return callFailure("cancelled", "The call was cancelled.");
 		const availability = entry.availability.getSnapshot();
 		if (!availability.available) return callFailure("unavailable", availability.reason);
-		const prepared = await prepare();
+		let prepared;
+		try {
+			prepared = await prepare();
+		} catch (cause) {
+			onDefect(id, cause);
+			return callFailure("internal", "The capability failed.");
+		}
 		if ("issues" in prepared) return callFailure("invalid-input", issueMessage(prepared.issues));
 		const controller = new AbortController();
 		const abort = () => controller.abort();
@@ -145,6 +168,103 @@ function createSession(app, options) {
 			invokeExternal
 		});
 	}
+	const servedEvents = /* @__PURE__ */ new Map();
+	for (const event of app.events ?? []) {
+		if (!event.audience.includes(options.target)) continue;
+		if (served.has(event.id) || servedEvents.has(event.id)) throw new Error(`The id ${event.id} is declared two times.`);
+		servedEvents.set(event.id, event);
+	}
+	const bufferLimit = options.bufferLimit ?? 256;
+	/**
+	* Start a subscription to an event that the session serves: the decoded input, then the provider, with cancellation.
+	* The result is the occurrences, or the call failure before the first occurrence.
+	*/
+	async function start(id, prepare, check, subscribeOptions = {}) {
+		const { signal } = subscribeOptions;
+		const cancelled = () => lifetime.signal.aborted || signal?.aborted === true;
+		if (cancelled()) return callFailure("cancelled", "The subscription was cancelled.");
+		if (!isMaxAgeMs(subscribeOptions.maxAgeMs)) return callFailure("invalid-input", "maxAgeMs must be an integer that is 0 or more.");
+		let prepared;
+		try {
+			prepared = await prepare();
+		} catch (cause) {
+			onDefect(id, cause);
+			return callFailure("internal", "The event failed.");
+		}
+		if (cancelled()) return callFailure("cancelled", "The subscription was cancelled.");
+		if ("issues" in prepared) return callFailure("invalid-input", issueMessage(prepared.issues));
+		const controller = new AbortController();
+		let source;
+		try {
+			source = prepared.start({
+				signal: controller.signal,
+				context: options.context,
+				...subscribeOptions.cursor === void 0 ? {} : { cursor: subscribeOptions.cursor },
+				...subscribeOptions.maxAgeMs === void 0 ? {} : { maxAgeMs: subscribeOptions.maxAgeMs }
+			});
+			if (!isAsyncIterable(source)) throw new TypeError("subscribe did not give an async iterable.");
+		} catch (cause) {
+			onDefect(id, cause);
+			return callFailure("internal", "The event failed.");
+		}
+		const complete = () => running.complete();
+		const cancel = () => running.cancel();
+		const running = runSubscription({
+			name: id,
+			source,
+			check,
+			controller,
+			limit: bufferLimit,
+			onDefect: (cause) => onDefect(id, cause),
+			onEnd: () => {
+				lifetime.signal.removeEventListener("abort", complete);
+				signal?.removeEventListener("abort", cancel);
+			}
+		});
+		lifetime.signal.addEventListener("abort", complete);
+		signal?.addEventListener("abort", cancel);
+		return running.occurrences;
+	}
+	/** A subscription with an input that is not trusted. The data of each occurrence is a copy in its JSON form. */
+	async function subscribe(id, input, subscribeOptions) {
+		if (lifetime.signal.aborted || subscribeOptions?.signal?.aborted === true) return callFailure("cancelled", "The subscription was cancelled.");
+		const event = servedEvents.get(id);
+		if (event === void 0) return callFailure("unknown-capability", `There is no event ${id}.`);
+		return start(id, () => event.decode(input), (data) => checkPayload(event.payload, data, (value) => value), subscribeOptions);
+	}
+	/** Reject a call failure, as an event handle does. */
+	const opened = async (subscription) => {
+		const settled = await subscription;
+		if ("kind" in settled) throw new CallFailureError(settled);
+		return settled;
+	};
+	/** The typed handle of an event that the session serves, or the handle outside the view. */
+	function eventHandle(event) {
+		if (servedEvents.get(event.id) !== event) return eventOutsideView(event);
+		const source = (input, subscription) => event.input === void 0 ? event.subscribe({}, subscription) : event.subscribe(input, subscription);
+		const check = (data) => checkPayload(event.payload, data, () => data);
+		return {
+			id: event.id,
+			description: event.description,
+			audience: [options.target],
+			subscribe: (input, subscribeOptions) => {
+				if (lifetime.signal.aborted || subscribeOptions?.signal?.aborted === true) return Promise.reject(new CallFailureError(callFailure("cancelled", "The subscription was cancelled.")));
+				return opened(start(event.id, () => Promise.resolve({ start: (subscription) => source(input, subscription) }), check, subscribeOptions));
+			},
+			subscribeExternal: (input, subscribeOptions) => opened(subscribe(event.id, input, subscribeOptions))
+		};
+	}
+	const eventHandles = /* @__PURE__ */ new Map();
+	for (const [id, event] of servedEvents) {
+		const subscribeExternal = (input, subscribeOptions) => opened(subscribe(id, input, subscribeOptions));
+		eventHandles.set(id, {
+			id,
+			description: event.description,
+			audience: [options.target],
+			subscribe: subscribeExternal,
+			subscribeExternal
+		});
+	}
 	const unsubscribeAll = () => {
 		subscriptions.forEach((subscription) => subscription.unsubscribe());
 		subscriptions = [];
@@ -163,6 +283,9 @@ function createSession(app, options) {
 		},
 		handles,
 		handle,
+		eventHandles,
+		eventHandle,
+		subscribe,
 		call: (capability, input, callOptions) => call(capability, input, callOptions?.signal),
 		signal: lifetime.signal,
 		invoke: (id, input, callOptions) => invoke(id, input, callOptions?.signal),
@@ -185,6 +308,23 @@ function createSession(app, options) {
 function issueMessage(issues) {
 	return issues.map((issue) => `${(issue.path ?? []).map((key) => typeof key === "object" ? String(key.key) : String(key)).join(".") || "input"}: ${issue.message}`).join("; ");
 }
+/** True if a value is an async iterable. */
+function isAsyncIterable(value) {
+	return typeof value === "object" && value !== null && Symbol.asyncIterator in value && typeof value[Symbol.asyncIterator] === "function";
+}
+/**
+* Check the data of an occurrence against the payload schema, and give a copy of the output of the schema. With no
+* payload schema, the data must be an empty object, and `empty` gives the value. Data that does not agree is a defect.
+*/
+async function checkPayload(schema, data, empty) {
+	if (schema === void 0) {
+		if (typeof data !== "object" || data === null || Array.isArray(data) || Object.keys(data).length > 0) throw new Error("The data of an occurrence of an event with no payload schema is not an empty object.");
+		return structuredClone(empty(data));
+	}
+	const checked = await schema["~standard"].validate(data);
+	if (checked.issues !== void 0) throw new Error(`The data of an occurrence does not agree with the payload schema: ${checked.issues[0]?.message}`);
+	return structuredClone(checked.value);
+}
 /** An observable whose values are copies, so that a client cannot change the data of the provider. */
 function detached(source) {
 	return {
@@ -251,5 +391,4 @@ async function checkFailure(failure, tag, schemas) {
 		...checked.value
 	};
 }
-//#endregion
-export { createSession };
+export { createSession, isMaxAgeMs };

package/dist/stream.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Streams of messages for the bindings that serve events through a connection: the next occurrence or a sign that the
+ * stream is idle, and a web stream of text.
+ */
+import type { Occurrence } from "@acid-cat/spec-ts";
+import type { Occurrences } from "./subscription.js";
+/** One pull of a subscription: the next step, the error that ends it, or `idle` when nothing came in time. */
+export type Pulled<Payload> = {
+    readonly idle: true;
+} | {
+    readonly step: IteratorResult<Occurrence<Payload>, undefined>;
+} | {
+    readonly error: unknown;
+};
+/**
+ * A function that pulls the next step of a subscription. It gives `idle` when no step comes within `idleMs`
+ * milliseconds. The `next()` that waits is kept for the next pull, so no occurrence is lost.
+ */
+export declare function idlePuller<Payload>(occurrences: Occurrences<Payload>, idleMs: number): () => Promise<Pulled<Payload>>;
+/**
+ * A web stream of text. The stream calls `produce` each time that the client can take more: it gives the next messages,
+ * or `undefined` at the end. When the client cancels the stream, the stream calls `cancel`. `release` runs one time, when
+ * the stream ends in any way.
+ */
+export declare function textStream(produce: () => Promise<readonly string[] | undefined>, cancel: () => void, release: () => Promise<void>): ReadableStream<Uint8Array>;

package/dist/stream.js

@@ -0,0 +1,62 @@
+// src/stream.ts
+/**
+* A function that pulls the next step of a subscription. It gives `idle` when no step comes within `idleMs`
+* milliseconds. The `next()` that waits is kept for the next pull, so no occurrence is lost.
+*/
+function idlePuller(occurrences, idleMs) {
+	let pending;
+	return async () => {
+		const next = pending ??= occurrences.next().then((step) => ({ step }), (error) => ({ error }));
+		let timer;
+		const idle = new Promise((resolve) => {
+			timer = setTimeout(() => resolve({ idle: true }), idleMs);
+		});
+		try {
+			const pulled = await Promise.race([next, idle]);
+			if (!("idle" in pulled)) pending = void 0;
+			return pulled;
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+}
+/**
+* A web stream of text. The stream calls `produce` each time that the client can take more: it gives the next messages,
+* or `undefined` at the end. When the client cancels the stream, the stream calls `cancel`. `release` runs one time, when
+* the stream ends in any way.
+*/
+function textStream(produce, cancel, release) {
+	const encoder = new TextEncoder();
+	let released = false;
+	let cancelled = false;
+	const releaseOnce = async () => {
+		if (released) return;
+		released = true;
+		await release();
+	};
+	return new ReadableStream({
+		async pull(controller) {
+			let messages;
+			try {
+				messages = await produce();
+			} catch (error) {
+				if (!cancelled) controller.error(error);
+				await releaseOnce();
+				return;
+			}
+			if (cancelled) return;
+			if (messages === void 0) {
+				controller.close();
+				await releaseOnce();
+				return;
+			}
+			controller.enqueue(encoder.encode(messages.join("")));
+		},
+		async cancel() {
+			cancelled = true;
+			cancel();
+			await releaseOnce();
+		}
+	}, { highWaterMark: 0 });
+}
+export { idlePuller, textStream };

package/dist/subscription.d.ts

@@ -0,0 +1,39 @@
+import type { Emitted, Occurrence } from "@acid-cat/spec-ts";
+/**
+ * The occurrences of one subscription, as an async iterator (spec/bindings/typescript.md#event-handles). `return()`
+ * cancels the subscription, also while a `next()` waits: that `next()` then resolves with `done: true`. A `for await`
+ * loop that stops early calls `return()`. `await using` also cancels the subscription at the end of its block.
+ */
+export interface Occurrences<Payload> extends AsyncIterable<Occurrence<Payload>>, AsyncDisposable {
+    next(): Promise<IteratorResult<Occurrence<Payload>, undefined>>;
+    return(): Promise<IteratorResult<Occurrence<Payload>, undefined>>;
+    [Symbol.asyncIterator](): Occurrences<Payload>;
+}
+/** The number of occurrences that a subscription keeps for a client that reads slowly, if the session gives no limit. */
+export declare const DEFAULT_BUFFER_LIMIT = 256;
+export interface SubscriptionParts<Source, Payload> {
+    /** The id of the event. */
+    readonly name: string;
+    /** The occurrences of the provider. The pump starts to read them at once. */
+    readonly source: AsyncIterable<Emitted<Source>>;
+    /** Check the data of one occurrence against the payload schema, and give a copy in its JSON form. It throws if the data does not agree. */
+    readonly check: (data: Source) => Promise<Payload>;
+    /** The controller of the signal of the provider. The subscription aborts it when it ends. */
+    readonly controller: AbortController;
+    /** The maximum number of occurrences that wait for the client. */
+    readonly limit: number;
+    /** Record a defect of the provider. */
+    readonly onDefect: (cause: unknown) => void;
+    /** Called one time, when the subscription ends. */
+    readonly onEnd: () => void;
+}
+/** A subscription that runs: the iterator of the client, and the two ends that the session and the client cause. */
+export interface Running<Payload> {
+    readonly occurrences: Occurrences<Payload>;
+    /** End the subscription as cancelled: the client sees `done: true` at once. */
+    readonly cancel: () => void;
+    /** End the subscription as complete: the client reads the occurrences that wait, then sees `done: true`. */
+    readonly complete: () => void;
+}
+/** Start the pump of a subscription, and give the iterator of the client. */
+export declare function runSubscription<Source, Payload>(parts: SubscriptionParts<Source, Payload>): Running<Payload>;

package/dist/subscription.js

@@ -0,0 +1,144 @@
+import { CallFailureError, callFailure, occurrenceOf } from "@acid-cat/spec-ts";
+// src/subscription.ts
+/**
+* One subscription (spec/events.md): the pump that reads the occurrences of the provider, the bounded buffer for a slow
+* client, and the iterator that the client reads.
+*/
+/** The number of occurrences that a subscription keeps for a client that reads slowly, if the session gives no limit. */
+const DEFAULT_BUFFER_LIMIT = 256;
+/** The message of the call failure `internal` of a subscription. It shows no internal data. */
+const INTERNAL_MESSAGE = "The event failed.";
+const DONE = {
+	done: true,
+	value: void 0
+};
+/** Start the pump of a subscription, and give the iterator of the client. */
+function runSubscription(parts) {
+	const buffer = [];
+	const waiters = [];
+	/** True when the buffer removed occurrences: the next occurrence that the client reads has `truncated: true`. */
+	let dropped = false;
+	/** How the source ended. The client still reads the occurrences in the buffer before it sees the end. */
+	let ending;
+	/** True when the client sees only `done: true`. */
+	let closed = false;
+	let stopped = false;
+	let stopSource = () => {};
+	const take = (occurrence) => {
+		if (!dropped) return occurrence;
+		dropped = false;
+		return {
+			...occurrence,
+			truncated: true
+		};
+	};
+	/** Give each waiting `next()` an occurrence or the end, while there are some. */
+	const settle = () => {
+		for (let waiter = waiters.shift(); waiter !== void 0; waiter = waiters.shift()) {
+			const occurrence = buffer.shift();
+			if (occurrence !== void 0) waiter.resolve({
+				done: false,
+				value: take(occurrence)
+			});
+			else if (closed) waiter.resolve(DONE);
+			else if (ending !== void 0) {
+				closed = true;
+				if (ending.failure === void 0) waiter.resolve(DONE);
+				else waiter.reject(ending.failure);
+			} else {
+				waiters.unshift(waiter);
+				return;
+			}
+		}
+	};
+	/** Stop the provider one time: abort its signal, and close its iterator. */
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		parts.controller.abort();
+		stopSource();
+		parts.onEnd();
+	};
+	const end = (how) => {
+		if (stopped) return;
+		ending = how;
+		stop();
+		settle();
+	};
+	const cancel = () => {
+		if (closed) return;
+		closed = true;
+		buffer.length = 0;
+		stop();
+		settle();
+	};
+	const push = (occurrence) => {
+		buffer.push(occurrence);
+		if (buffer.length > parts.limit) {
+			buffer.shift();
+			dropped = true;
+		}
+		settle();
+	};
+	(async () => {
+		try {
+			const iterator = parts.source[Symbol.asyncIterator]();
+			stopSource = () => void Promise.resolve().then(() => iterator.return?.()).catch(() => void 0);
+			if (stopped) stopSource();
+			for (;;) {
+				const step = await iterator.next();
+				if (stopped) return;
+				if (step.done === true) return end({});
+				const emitted = checkEmitted(step.value);
+				const data = await parts.check(emitted.data);
+				if (stopped) return;
+				push(occurrenceOf(parts.name, {
+					...emitted,
+					data
+				}, () => crypto.randomUUID(), () => /* @__PURE__ */ new Date()));
+			}
+		} catch (cause) {
+			if (stopped) return;
+			parts.onDefect(cause);
+			end({ failure: new CallFailureError(callFailure("internal", INTERNAL_MESSAGE)) });
+		}
+	})();
+	const occurrences = {
+		next: () => new Promise((resolve, reject) => {
+			waiters.push({
+				resolve,
+				reject
+			});
+			settle();
+		}),
+		return: () => {
+			cancel();
+			return Promise.resolve(DONE);
+		},
+		[Symbol.asyncIterator]: () => occurrences,
+		[Symbol.asyncDispose]: () => {
+			cancel();
+			return Promise.resolve();
+		}
+	};
+	return {
+		occurrences,
+		cancel,
+		complete: () => end({})
+	};
+}
+/**
+* Check the members of a value that the provider gives, beside its data. The provider is code of the application, but
+* plain JavaScript can give any value. A value that is not valid is a defect.
+*/
+function checkEmitted(value) {
+	const object = value;
+	if (typeof object !== "object" || object === null) throw new TypeError("The provider gave a value that is not an object.");
+	const { eventId, timestamp, cursor, truncated } = value;
+	if (eventId !== void 0 && (typeof eventId !== "string" || eventId === "")) throw new TypeError("The eventId of an occurrence is not a string.");
+	if (timestamp !== void 0 && (typeof timestamp !== "string" || Number.isNaN(Date.parse(timestamp)))) throw new TypeError("The timestamp of an occurrence is not a date and time.");
+	if (cursor !== void 0 && typeof cursor !== "string") throw new TypeError("The cursor of an occurrence is not a string.");
+	if (truncated !== void 0 && truncated !== true) throw new TypeError("The truncated member of an occurrence is not true.");
+	return value;
+}
+export { DEFAULT_BUFFER_LIMIT, runSubscription };

package/dist/webhook.d.ts

@@ -0,0 +1,40 @@
+import type { Clock } from "./clock.js";
+import type { WebhookDelivery } from "./mcp-events.js";
+/** The settings of webhook delivery. Each limit has the default of spec/bindings/mcp.md#webhook. */
+export interface WebhookOptions {
+    /**
+     * The allowlist: a URL for which this function gives `true` gets deliveries with no verification. With no function,
+     * each pair of principal and URL needs a verification.
+     */
+    readonly allow?: ((url: URL) => boolean) | undefined;
+    /**
+     * Connect also to addresses that are not globally routable, for example `127.0.0.1` or `10.0.0.1`. Only for tests and
+     * private deployments. The default is `false`.
+     */
+    readonly allowPrivateNetworks?: boolean | undefined;
+    /** Certificates of authorities to trust beside the default ones, in PEM form. For example the authority of a test receiver. */
+    readonly ca?: string | Buffer | readonly (string | Buffer)[] | undefined;
+    /** The maximum lifetime of a subscription, in milliseconds. The default is 1 hour. */
+    readonly maxTtlMs?: number | undefined;
+    /** The minimum lifetime of a subscription, in milliseconds. The default is 1 minute. */
+    readonly minTtlMs?: number | undefined;
+    /** The maximum number of webhook subscriptions of one principal. The default is 100. */
+    readonly maxSubscriptions?: number | undefined;
+    /** The maximum number of attempts to send one delivery. The default is 5. */
+    readonly attempts?: number | undefined;
+    /** The time in which the server makes the attempts of one delivery, in milliseconds. The default is 15 minutes. */
+    readonly retryWindowMs?: number | undefined;
+    /** The time that the server waits for each answer, in milliseconds. The default is 5 seconds. */
+    readonly timeoutMs?: number | undefined;
+    /** The time after a change of the secret in which the server signs with the old secret and the new secret. The default is 5 minutes. */
+    readonly rotationGraceMs?: number | undefined;
+    /**
+     * The wait before the next attempt, after attempt number `attempt` (1 for the first attempt) failed, in milliseconds.
+     * The default is 10 seconds, multiplied by 3 for each attempt: 10 s, 30 s, 90 s and 270 s.
+     */
+    readonly retryDelayMs?: ((attempt: number) => number) | undefined;
+    /** The clock of lifetimes and retries. The default is the clock of the system. */
+    readonly clock?: Clock | undefined;
+}
+/** Make webhook delivery for `mcpHandler` (option `webhooks`). */
+export declare function webhookDelivery(options?: WebhookOptions): WebhookDelivery;