@acid-cat/spec-ts 0.9.0 → 0.10.1

package/README.md

@@ -17,5 +17,8 @@ pnpm add @acid-cat/spec-ts
 | `CALL_FAILURE_KINDS`, `CallFailureError` | The kinds of call failure, and the JavaScript error for one |
 | `AVAILABLE`, `unavailable` | Make [availability](../../spec/invocation.md#availability) values |
 | `viewOf`, `bundle` | The [view](../../spec/catalog.md#views) of a target, and a schema with its shared types |
+| `resolveType` | The type that the `$ref` of a schema refers to, whatever other keys the schema has |
+| `ownMember` | The member of an object with a key, or `undefined`. Inherited names, such as `constructor`, are not members |
+| `byCodePoint` | Order strings by Unicode code point, as the [canonical form](../../spec/catalog.md#canonical-form) sorts keys |
 
 The other exports give the names, flags, exit codes and tool shapes of each [binding](../../spec/bindings/README.md).

package/dist/index.d.ts

@@ -3,6 +3,7 @@
  * implementation. This package has no dependencies.
  *
  * - Outcomes and call failures: spec/invocation.md
+ * - Subscriptions and occurrences: spec/events.md
  * - Names, views and bundling: spec/catalog.md
  * - Exit codes, status codes and MCP results: spec/bindings/
  */
@@ -36,6 +37,39 @@ export declare class CallFailureError extends Error {
     readonly kind: CallFailureKind;
     constructor(failure: CallFailure);
 }
+/** The kinds of call failure that a subscription can fail with before its first occurrence, in order of precedence. */
+export declare const SUBSCRIBE_FAILURE_KINDS: readonly ["cancelled", "unknown-capability", "invalid-input", "internal"];
+/** One thing that happened, in its JSON form (spec/events.md#occurrences). */
+export interface Occurrence<Payload = unknown> {
+    readonly eventId: string;
+    readonly name: string;
+    readonly timestamp: string;
+    readonly data: Payload;
+    readonly cursor?: string;
+    readonly truncated?: true;
+}
+/** What a provider gives for one occurrence. The binding adds `name`, and makes `eventId` and `timestamp` if they are absent. */
+export interface Emitted<Payload = unknown> {
+    readonly data: Payload;
+    readonly eventId?: string;
+    readonly timestamp?: string;
+    readonly cursor?: string;
+    readonly truncated?: true;
+}
+/** Where a subscription starts (spec/events.md#resuming). */
+export interface Resume {
+    readonly cursor?: string;
+    readonly maxAgeMs?: number;
+}
+/**
+ * The occurrence for an emitted value. `makeId` gives an `eventId` that is unique in the subscription, and `now` gives
+ * the time, when the provider gives none.
+ */
+export declare function occurrenceOf<Payload>(name: string, emitted: Emitted<Payload>, makeId: () => string, now: () => Date): Occurrence<Payload>;
+/** Tell if a value is an occurrence in its JSON form. `data` can be any JSON object. */
+export declare function isOccurrence(value: unknown): value is Occurrence;
+/** The time with no message on a stream after which a binding sends a keepalive or a heartbeat, in milliseconds. */
+export declare const KEEPALIVE_MS = 15000;
 export type Availability = {
     readonly available: true;
 } | {
@@ -82,6 +116,19 @@ export declare function cliJsonArray(values: readonly string[]): readonly unknow
  * `undefined` when the capability has no input.
  */
 export declare function cliUsage(program: string, id: string, input: JsonObject | undefined): string;
+/**
+ * The `usage` of an event in `list` (spec/bindings/cli.md#events). `input` is the bundled input schema, or `undefined`
+ * when the event has no input.
+ */
+export declare function cliEventUsage(program: string, id: string, input: JsonObject | undefined): string;
+/** The flags of `watch` that give the cursor and `maxAgeMs`. No input property of an event can have these names. */
+export declare const CLI_RESUME_FLAGS: readonly ["cursor", "max-age-ms"];
+/** The exit code for each end of a subscription through the CLI (spec/bindings/cli.md#events). */
+export declare const CLI_WATCH_EXIT_CODES: {
+    readonly complete: 0;
+    readonly cancelled: 130;
+    readonly internal: 5;
+};
 export declare const HTTP_STATUS: {
     readonly "unknown-capability": 404;
     readonly "invalid-input": 422;
@@ -90,6 +137,21 @@ export declare const HTTP_STATUS: {
     readonly internal: 500;
 };
 export declare const httpStatus: (outcome: Outcome<unknown, unknown>) => number;
+/** One message of a stream of server-sent events, as text, with the blank line that ends it. */
+export declare function sseMessage(fields: {
+    readonly event?: string | undefined;
+    readonly id?: string | undefined;
+    readonly data: string;
+}): string;
+/** The messages of a subscription through the HTTP binding (spec/bindings/http.md#events). */
+export declare const httpEventMessage: {
+    readonly next: (occurrence: Occurrence) => string;
+    readonly complete: () => string;
+    readonly error: (failure: CallFailure) => string;
+    readonly keepalive: () => string;
+};
+/** The media type of a stream of server-sent events. */
+export declare const SSE_MEDIA_TYPE = "text/event-stream";
 export type Rejection = "method" | "origin" | "media-type" | "too-large" | "not-utf8";
 /**
  * The first rule that a request breaks, before its body is read: method, origin, media type, declared length.
@@ -116,6 +178,85 @@ export declare const MCP_REJECTIONS: {
         readonly code?: number;
     };
 };
+/** The identifier of the MCP events extension (spec/bindings/mcp.md#events). */
+export declare const MCP_EVENTS_EXTENSION = "io.modelcontextprotocol/events";
+/** The key in `params._meta` that holds the id of the `events/stream` request. */
+export declare const MCP_SUBSCRIPTION_ID = "io.modelcontextprotocol/subscriptionId";
+/** The JSON-RPC errors of the MCP events extension. Their numbers are not final in SEP-3415. */
+export declare const MCP_EVENT_ERRORS: {
+    readonly notFound: -32023;
+    readonly forbidden: -32024;
+    readonly resourceExhausted: -32025;
+    readonly unsupported: -32026;
+    readonly callbackEndpoint: -32027;
+    readonly invalidParams: -32602;
+    readonly internal: -32603;
+};
+/** The JSON-RPC error for a call failure of a subscription before its first occurrence. */
+export declare function mcpSubscribeError(failure: CallFailure): {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: JsonObject;
+};
+/** An entry of `events/list`. `input` and `payload` are the bundled schemas. */
+export declare function mcpEventEntry(id: string, description: string, input: JsonObject | undefined, payload: JsonObject | undefined, webhook?: boolean): JsonObject;
+/** The params of `notifications/events/event` for an occurrence: the occurrence without `truncated`. */
+export declare function mcpEventParams(occurrence: Occurrence, subscriptionId: string | number): JsonObject;
+/**
+ * Order strings by Unicode code point. The `<` operator compares UTF-16 code units, which put a character after U+FFFF
+ * before a character from U+E000 to U+FFFF.
+ */
+export declare function byCodePoint(left: string, right: string): number;
+/** The canonical JSON of a value (spec/bindings/mcp.md#canonical-json): no spaces, and the keys of each object in code point order. */
+export declare function canonicalJson(value: unknown): string;
+/** The defaults of poll delivery (spec/bindings/mcp.md#poll). */
+export declare const MCP_POLL_DEFAULTS: {
+    readonly leaseMs: 300000;
+    readonly bufferLimit: 1000;
+    readonly maxEvents: 100;
+    readonly nextPollMs: 2000;
+};
+/** Where a poll cursor points: a lease, a position in its buffer, and the last cursor of the provider. */
+export interface PollPosition {
+    readonly lease: string;
+    readonly position: number;
+    readonly provider?: string;
+}
+/** The cursor of a poll position. Only the server reads it. */
+export declare function encodePollCursor(position: PollPosition): string;
+/** The position of a poll cursor, or `undefined` when the text is not a poll cursor. */
+export declare function decodePollCursor(cursor: string): PollPosition | undefined;
+/** The defaults of webhook delivery (spec/bindings/mcp.md#webhook). */
+export declare const MCP_WEBHOOK_DEFAULTS: {
+    readonly maxTtlMs: 3600000;
+    readonly minTtlMs: 60000;
+    readonly maxSubscriptions: 100;
+    readonly attempts: 5;
+    readonly retryWindowMs: 900000;
+    readonly timeoutMs: 5000;
+    readonly rotationGraceMs: 300000;
+};
+/** The reasons of a `CallbackEndpointError`, and the values of `lastError` (spec/bindings/mcp.md#webhook). */
+export declare const WEBHOOK_ERRORS: readonly ["challenge_failed", "connection_refused", "timeout", "tls_error", "http_4xx", "http_5xx"];
+export type WebhookError = (typeof WEBHOOK_ERRORS)[number];
+/** The bytes of a Standard Webhooks secret: `whsec_` and the base64 of 24 to 64 bytes. `undefined` when it is not valid. */
+export declare function webhookSecretBytes(secret: string): Uint8Array<ArrayBuffer> | undefined;
+/** The lifetime that the server grants for a suggested `ttlMs` (spec/bindings/mcp.md#webhook). */
+export declare function webhookGrantMs(ttlMs: number | null | undefined, limits: {
+    readonly maxTtlMs: number;
+    readonly minTtlMs: number;
+}): number;
+/** The text that a Standard Webhooks signature covers. */
+export declare const webhookSignedText: (webhookId: string, timestamp: number, body: string) => string;
+/** The `webhook-signature` header: one `v1,` signature for each secret, with a space between them. */
+export declare function webhookSignature(secrets: readonly string[], webhookId: string, timestamp: number, body: string): Promise<string>;
+/** The subscription id of a webhook subscription: `sub_` and 16 hexadecimal digits of the SHA-256 of its key. */
+export declare function webhookSubscriptionId(principal: string, url: string, id: string, input: unknown): Promise<string>;
+/**
+ * Tell if an IP address is globally routable: not in a special-purpose range of the IANA IPv4 and IPv6 registries that
+ * is not global, for example loopback, private, link-local, shared, documentation or multicast addresses.
+ */
+export declare function isGloballyRoutable(address: string): boolean;
 export interface McpToolResult {
     readonly content: readonly [{
         readonly type: "text";
@@ -140,6 +281,12 @@ export interface CatalogCapability extends JsonObject {
     readonly readOnly?: boolean;
     readonly state?: JsonObject;
 }
+export interface CatalogEvent extends JsonObject {
+    readonly description: string;
+    readonly audience?: readonly string[];
+    readonly input?: JsonObject;
+    readonly payload?: JsonObject;
+}
 export interface CatalogDocument extends JsonObject {
     readonly acidcat: string;
     readonly title?: string;
@@ -155,12 +302,24 @@ export interface CatalogDocument extends JsonObject {
     readonly capabilities: {
         readonly [id: string]: CatalogCapability;
     };
+    readonly events?: {
+        readonly [id: string]: CatalogEvent;
+    };
 }
 export declare const REFERENCE: RegExp;
 /** Tell if a value is a JSON object: an object that is not `null` and not an array. */
 export declare const isJsonObject: (value: unknown) => value is JsonObject;
+/**
+ * The member of an object with this key, or `undefined` when the object does not have it. Inherited names, such as
+ * `constructor` or `toString`, are not members.
+ */
+export declare function ownMember<Value>(object: {
+    readonly [key: string]: Value;
+}, key: string): Value | undefined;
 /** The schemas of a capability, each with the member that holds it. */
 export declare function schemasOf(capability: CatalogCapability): readonly (readonly [string, JsonObject])[];
+/** The schemas of an event, each with the member that holds it. */
+export declare function eventSchemasOf(event: CatalogEvent): readonly (readonly [string, JsonObject])[];
 /** Every object in a JSON value, at all levels. */
 export declare function visitObjects(value: unknown, onObject: (node: JsonObject) => void): void;
 /** The types that a schema uses, directly or through other types. */
@@ -175,6 +334,14 @@ export declare function typesUsedBy(schema: unknown, types: {
 export declare function objectInput(schema: JsonObject, types: {
     readonly [name: string]: JsonObject;
 }): JsonObject;
+/**
+ * The type that a schema's `$ref` refers to, whatever other keys the schema has, or the schema itself when it has no
+ * `$ref` to a type in `types`. A catalog uses it to tell if an input or a payload is an object
+ * (spec/catalog.md#capabilities).
+ */
+export declare function resolveType(schema: JsonObject, types: {
+    readonly [name: string]: JsonObject;
+}): JsonObject;
 /** Bundle a schema (spec/catalog.md#bundling). */
 export declare function bundle(schema: JsonObject, types: {
     readonly [name: string]: JsonObject;

package/dist/index.js

@@ -1,9 +1,10 @@
-//#region src/index.ts
+// src/index.ts
 /**
 * The fixed details of the AcidCat specification, as TypeScript data and pure functions, for the TypeScript reference
 * implementation. This package has no dependencies.
 *
 * - Outcomes and call failures: spec/invocation.md
+* - Subscriptions and occurrences: spec/events.md
 * - Names, views and bundling: spec/catalog.md
 * - Exit codes, status codes and MCP results: spec/bindings/
 */
@@ -38,6 +39,41 @@ var CallFailureError = class extends Error {
 		this.name = failure.kind === "cancelled" ? "AbortError" : failure.kind === "invalid-input" ? "TypeError" : "Error";
 	}
 };
+/** The kinds of call failure that a subscription can fail with before its first occurrence, in order of precedence. */
+const SUBSCRIBE_FAILURE_KINDS = [
+	"cancelled",
+	"unknown-capability",
+	"invalid-input",
+	"internal"
+];
+/**
+* The occurrence for an emitted value. `makeId` gives an `eventId` that is unique in the subscription, and `now` gives
+* the time, when the provider gives none.
+*/
+function occurrenceOf(name, emitted, makeId, now) {
+	return {
+		eventId: emitted.eventId ?? makeId(),
+		name,
+		timestamp: emitted.timestamp ?? now().toISOString(),
+		data: emitted.data,
+		...emitted.cursor === void 0 ? {} : { cursor: emitted.cursor },
+		...emitted.truncated === true ? { truncated: true } : {}
+	};
+}
+/** Tell if a value is an occurrence in its JSON form. `data` can be any JSON object. */
+function isOccurrence(value) {
+	return isJsonObject(value) && typeof value.eventId === "string" && value.eventId.length > 0 && typeof value.name === "string" && isId(value.name) && typeof value.timestamp === "string" && !Number.isNaN(Date.parse(value.timestamp)) && isJsonObject(value.data) && (value.cursor === void 0 || typeof value.cursor === "string") && (value.truncated === void 0 || value.truncated === true) && Object.keys(value).every((key) => OCCURRENCE_MEMBERS.has(key));
+}
+const OCCURRENCE_MEMBERS = /* @__PURE__ */ new Set([
+	"eventId",
+	"name",
+	"timestamp",
+	"data",
+	"cursor",
+	"truncated"
+]);
+/** The time with no message on a stream after which a binding sends a keepalive or a heartbeat, in milliseconds. */
+const KEEPALIVE_MS = 15e3;
 const AVAILABLE = { available: true };
 const unavailable = (reason) => ({
 	available: false,
@@ -65,8 +101,7 @@ function cliFlags(input) {
 	const properties = objectOrEmpty(input.properties);
 	const definitions = objectOrEmpty(input.$defs);
 	const required = new Set(stringsOf(input.required));
-	const byName = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-	const names = Object.keys(properties).sort(byName);
+	const names = Object.keys(properties).sort(byCodePoint);
 	return [...names.filter((name) => required.has(name)), ...names.filter((name) => !required.has(name))].map((name) => {
 		const property = cliResolve(objectOrEmpty(properties[name]), definitions);
 		const items = cliRepeatedItems(property, definitions);
@@ -76,8 +111,8 @@ function cliFlags(input) {
 }
 /** A property schema, or the type in `definitions` that its `$ref` refers to. */
 function cliResolve(property, definitions) {
-	const target = typeof property.$ref === "string" ? REFERENCE.exec(property.$ref)?.[1] : void 0;
-	return target === void 0 ? property : objectOrEmpty(definitions[target] ?? property);
+	const target = referenceName(property);
+	return target === void 0 ? property : objectOrEmpty(ownMember(definitions, target) ?? property);
 }
 /**
 * The schema of the items of a repeated flag (spec/bindings/cli.md#commands), or `undefined` when the property does
@@ -122,6 +157,29 @@ function cliUsage(program, id, input) {
 		...input === void 0 ? [] : cliFlags(input)
 	].join(" ");
 }
+/**
+* The `usage` of an event in `list` (spec/bindings/cli.md#events). `input` is the bundled input schema, or `undefined`
+* when the event has no input.
+*/
+function cliEventUsage(program, id, input) {
+	const resume = "[--cursor <string>] [--max-age-ms <integer>]";
+	if (input !== void 0 && input.properties === void 0) return `${program} watch ${id} '<json>' ${resume}`;
+	return [
+		program,
+		"watch",
+		id,
+		...input === void 0 ? [] : cliFlags(input),
+		resume
+	].join(" ");
+}
+/** The flags of `watch` that give the cursor and `maxAgeMs`. No input property of an event can have these names. */
+const CLI_RESUME_FLAGS = ["cursor", "max-age-ms"];
+/** The exit code for each end of a subscription through the CLI (spec/bindings/cli.md#events). */
+const CLI_WATCH_EXIT_CODES = {
+	complete: 0,
+	cancelled: 130,
+	internal: 5
+};
 const HTTP_STATUS = {
 	"unknown-capability": 404,
 	"invalid-input": 422,
@@ -130,6 +188,36 @@ const HTTP_STATUS = {
 	internal: 500
 };
 const httpStatus = (outcome) => isCallFailure(outcome) ? HTTP_STATUS[outcome.kind] : 200;
+/** One message of a stream of server-sent events, as text, with the blank line that ends it. */
+function sseMessage(fields) {
+	return `${[
+		...fields.event === void 0 ? [] : [`event: ${fields.event}`],
+		...fields.id === void 0 ? [] : [`id: ${fields.id}`],
+		...fields.data.split("\n").map((line) => line === "" ? "data:" : `data: ${line}`)
+	].join("\n")}\n\n`;
+}
+/** The messages of a subscription through the HTTP binding (spec/bindings/http.md#events). */
+const httpEventMessage = {
+	next: (occurrence) => sseMessage({
+		event: "next",
+		id: occurrence.cursor,
+		data: JSON.stringify(occurrence)
+	}),
+	complete: () => sseMessage({
+		event: "complete",
+		data: ""
+	}),
+	error: (failure) => sseMessage({
+		event: "error",
+		data: JSON.stringify({
+			kind: failure.kind,
+			message: failure.message
+		})
+	}),
+	keepalive: () => ":\n\n"
+};
+/** The media type of a stream of server-sent events. */
+const SSE_MEDIA_TYPE = "text/event-stream";
 /**
 * The first rule that a request breaks, before its body is read: method, origin, media type, declared length.
 * The body itself is checked as it arrives, with `readBounded`.
@@ -187,6 +275,269 @@ const MCP_REJECTIONS = {
 		code: -32700
 	}
 };
+/** The identifier of the MCP events extension (spec/bindings/mcp.md#events). */
+const MCP_EVENTS_EXTENSION = "io.modelcontextprotocol/events";
+/** The key in `params._meta` that holds the id of the `events/stream` request. */
+const MCP_SUBSCRIPTION_ID = "io.modelcontextprotocol/subscriptionId";
+/** The JSON-RPC errors of the MCP events extension. Their numbers are not final in SEP-3415. */
+const MCP_EVENT_ERRORS = {
+	notFound: -32023,
+	forbidden: -32024,
+	resourceExhausted: -32025,
+	unsupported: -32026,
+	callbackEndpoint: -32027,
+	invalidParams: -32602,
+	internal: -32603
+};
+/** The JSON-RPC error for a call failure of a subscription before its first occurrence. */
+function mcpSubscribeError(failure) {
+	if (failure.kind === "unknown-capability") return {
+		code: MCP_EVENT_ERRORS.notFound,
+		message: failure.message,
+		data: { kind: "event" }
+	};
+	if (failure.kind === "invalid-input") return {
+		code: MCP_EVENT_ERRORS.invalidParams,
+		message: failure.message
+	};
+	return {
+		code: MCP_EVENT_ERRORS.internal,
+		message: failure.message
+	};
+}
+/** An entry of `events/list`. `input` and `payload` are the bundled schemas. */
+function mcpEventEntry(id, description, input, payload, webhook = false) {
+	return {
+		name: id,
+		description,
+		delivery: webhook ? [
+			"push",
+			"poll",
+			"webhook"
+		] : ["push", "poll"],
+		inputSchema: input ?? { type: "object" },
+		payloadSchema: payload ?? { type: "object" }
+	};
+}
+/** The params of `notifications/events/event` for an occurrence: the occurrence without `truncated`. */
+function mcpEventParams(occurrence, subscriptionId) {
+	const { truncated: _, ...rest } = occurrence;
+	return {
+		...rest,
+		_meta: { [MCP_SUBSCRIPTION_ID]: subscriptionId }
+	};
+}
+/**
+* Order strings by Unicode code point. The `<` operator compares UTF-16 code units, which put a character after U+FFFF
+* before a character from U+E000 to U+FFFF.
+*/
+function byCodePoint(left, right) {
+	const a = Array.from(left, (character) => character.codePointAt(0) ?? 0);
+	const b = Array.from(right, (character) => character.codePointAt(0) ?? 0);
+	for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+		const difference = (a[i] ?? 0) - (b[i] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return a.length - b.length;
+}
+/** The canonical JSON of a value (spec/bindings/mcp.md#canonical-json): no spaces, and the keys of each object in code point order. */
+function canonicalJson(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (isJsonObject(value)) return `{${Object.keys(value).sort(byCodePoint).map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+}
+/** The defaults of poll delivery (spec/bindings/mcp.md#poll). */
+const MCP_POLL_DEFAULTS = {
+	leaseMs: 3e5,
+	bufferLimit: 1e3,
+	maxEvents: 100,
+	nextPollMs: 2e3
+};
+/** The cursor of a poll position. Only the server reads it. */
+function encodePollCursor(position) {
+	const parts = position.provider === void 0 ? [position.lease, position.position] : [
+		position.lease,
+		position.position,
+		position.provider
+	];
+	return `p1.${base64UrlOfText(JSON.stringify(parts))}`;
+}
+/** The position of a poll cursor, or `undefined` when the text is not a poll cursor. */
+function decodePollCursor(cursor) {
+	if (!cursor.startsWith("p1.")) return void 0;
+	let parts;
+	try {
+		parts = JSON.parse(textOfBase64Url(cursor.slice(3)));
+	} catch {
+		return;
+	}
+	if (!Array.isArray(parts) || parts.length < 2 || parts.length > 3) return void 0;
+	const [lease, position, provider] = parts;
+	if (typeof lease !== "string" || typeof position !== "number" || !Number.isSafeInteger(position) || position < 0) return void 0;
+	if (provider !== void 0 && typeof provider !== "string") return void 0;
+	return provider === void 0 ? {
+		lease,
+		position
+	} : {
+		lease,
+		position,
+		provider
+	};
+}
+function base64UrlOfText(text) {
+	let binary = "";
+	for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function textOfBase64Url(text) {
+	const binary = atob(text.replaceAll("-", "+").replaceAll("_", "/"));
+	return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(binary, (character) => character.charCodeAt(0)));
+}
+/** The defaults of webhook delivery (spec/bindings/mcp.md#webhook). */
+const MCP_WEBHOOK_DEFAULTS = {
+	maxTtlMs: 36e5,
+	minTtlMs: 6e4,
+	maxSubscriptions: 100,
+	attempts: 5,
+	retryWindowMs: 9e5,
+	timeoutMs: 5e3,
+	rotationGraceMs: 3e5
+};
+/** The reasons of a `CallbackEndpointError`, and the values of `lastError` (spec/bindings/mcp.md#webhook). */
+const WEBHOOK_ERRORS = [
+	"challenge_failed",
+	"connection_refused",
+	"timeout",
+	"tls_error",
+	"http_4xx",
+	"http_5xx"
+];
+/** The bytes of a Standard Webhooks secret: `whsec_` and the base64 of 24 to 64 bytes. `undefined` when it is not valid. */
+function webhookSecretBytes(secret) {
+	if (!secret.startsWith("whsec_")) return void 0;
+	const text = secret.slice(6);
+	if (!/^[A-Za-z0-9+/]*={0,2}$/.test(text) || text.length % 4 !== 0) return void 0;
+	let binary;
+	try {
+		binary = atob(text);
+	} catch {
+		return;
+	}
+	return binary.length >= 24 && binary.length <= 64 ? Uint8Array.from(binary, (character) => character.charCodeAt(0)) : void 0;
+}
+/** The lifetime that the server grants for a suggested `ttlMs` (spec/bindings/mcp.md#webhook). */
+function webhookGrantMs(ttlMs, limits) {
+	if (ttlMs === null || ttlMs === void 0) return limits.maxTtlMs;
+	return Math.min(limits.maxTtlMs, Math.max(limits.minTtlMs, ttlMs));
+}
+/** The text that a Standard Webhooks signature covers. */
+const webhookSignedText = (webhookId, timestamp, body) => `${webhookId}.${timestamp}.${body}`;
+/** The `webhook-signature` header: one `v1,` signature for each secret, with a space between them. */
+async function webhookSignature(secrets, webhookId, timestamp, body) {
+	const content = new TextEncoder().encode(webhookSignedText(webhookId, timestamp, body));
+	const signatures = [];
+	for (const secret of secrets) {
+		const bytes = webhookSecretBytes(secret);
+		if (bytes === void 0) throw new TypeError("A webhook secret is not valid.");
+		const key = await crypto.subtle.importKey("raw", bytes, {
+			name: "HMAC",
+			hash: "SHA-256"
+		}, false, ["sign"]);
+		const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, content));
+		let binary = "";
+		for (const byte of mac) binary += String.fromCharCode(byte);
+		signatures.push(`v1,${btoa(binary)}`);
+	}
+	return signatures.join(" ");
+}
+/** The subscription id of a webhook subscription: `sub_` and 16 hexadecimal digits of the SHA-256 of its key. */
+async function webhookSubscriptionId(principal, url, id, input) {
+	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson([
+		principal,
+		url,
+		id,
+		input
+	]))));
+	return `sub_${Array.from(digest.slice(0, 8), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+/**
+* Tell if an IP address is globally routable: not in a special-purpose range of the IANA IPv4 and IPv6 registries that
+* is not global, for example loopback, private, link-local, shared, documentation or multicast addresses.
+*/
+function isGloballyRoutable(address) {
+	const ipv4 = ipv4Bytes(address);
+	if (ipv4 !== void 0) return isGlobalIpv4(ipv4);
+	const ipv6 = ipv6Words(address);
+	if (ipv6 === void 0) return false;
+	const [a = 0, b = 0, c = 0, d = 0, e = 0, f = 0, g = 0, h = 0] = ipv6;
+	if (a === 0 && b === 0 && c === 0 && d === 0 && e === 0 && f === 65535) return isGlobalIpv4([
+		g >> 8,
+		g & 255,
+		h >> 8,
+		h & 255
+	]);
+	if (ipv6.every((word) => word === 0)) return false;
+	if (a === 0 && b === 0 && c === 0 && d === 0 && e === 0 && f === 0 && g === 0 && h === 1) return false;
+	if (a === 100 && b === 65435) return false;
+	if (a === 256 && b === 0 && c === 0 && d === 0) return false;
+	if (a === 8193 && b < 512) return false;
+	if (a === 8193 && b === 3512) return false;
+	if (a === 8194) return false;
+	if (a === 16383 && b < 4096) return false;
+	if (a === 24320) return false;
+	if ((a & 65024) === 64512) return false;
+	if ((a & 65472) === 65152) return false;
+	if ((a & 65280) === 65280) return false;
+	return (a & 57344) === 8192;
+}
+function isGlobalIpv4([a = 0, b = 0, c = 0]) {
+	if (a === 0 || a === 10 || a === 127) return false;
+	if (a === 100 && b >= 64 && b <= 127) return false;
+	if (a === 169 && b === 254) return false;
+	if (a === 172 && b >= 16 && b <= 31) return false;
+	if (a === 192 && b === 0 && (c === 0 || c === 2)) return false;
+	if (a === 192 && b === 88 && c === 99) return false;
+	if (a === 192 && b === 168) return false;
+	if (a === 198 && (b === 18 || b === 19)) return false;
+	if (a === 198 && b === 51 && c === 100) return false;
+	if (a === 203 && b === 0 && c === 113) return false;
+	return a < 224;
+}
+function ipv4Bytes(address) {
+	const parts = address.split(".");
+	if (parts.length !== 4 || !parts.every((part) => /^(0|[1-9][0-9]{0,2})$/.test(part))) return void 0;
+	const bytes = parts.map(Number);
+	return bytes.every((byte) => byte <= 255) ? bytes : void 0;
+}
+function ipv6Words(input) {
+	let address = input.startsWith("[") && input.endsWith("]") ? input.slice(1, -1) : input;
+	const zone = address.indexOf("%");
+	if (zone !== -1) address = address.slice(0, zone);
+	const tail = [];
+	const lastColon = address.lastIndexOf(":");
+	const ipv4 = lastColon === -1 ? void 0 : ipv4Bytes(address.slice(lastColon + 1));
+	if (ipv4 !== void 0) {
+		const [w = 0, x = 0, y = 0, z = 0] = ipv4;
+		tail.push(w << 8 | x, y << 8 | z);
+		address = address.slice(0, lastColon + 1);
+		if (!address.endsWith("::")) address = address.slice(0, -1);
+	}
+	const halves = address.split("::");
+	if (halves.length > 2) return void 0;
+	const words = (text) => text === "" ? [] : text.split(":");
+	const head = words(halves[0] ?? "");
+	const rest = halves.length === 2 ? words(halves[1] ?? "") : [];
+	if (![...head, ...rest].every((word) => /^[0-9a-fA-F]{1,4}$/.test(word))) return void 0;
+	const count = head.length + rest.length + tail.length;
+	if (halves.length === 1 ? count !== 8 : count > 7) return void 0;
+	const zeros = halves.length === 2 ? Array.from({ length: 8 - count }, () => 0) : [];
+	return [
+		...head.map((word) => parseInt(word, 16)),
+		...zeros,
+		...rest.map((word) => parseInt(word, 16)),
+		...tail
+	];
+}
 /** The MCP tool result for an outcome that is not `unknown-capability`. */
 function mcpToolResult(outcome, hasOutputSchema) {
 	const text = (value) => [{
@@ -213,8 +564,17 @@ function mcpToolResult(outcome, hasOutputSchema) {
 	} : { content: text(outcome.value) };
 }
 const REFERENCE = /^#\/\$defs\/([A-Za-z][A-Za-z0-9_]*)$/;
+/** The name of the type that a schema's `$ref` refers to, or `undefined` when it has no `$ref` of that form. */
+const referenceName = (schema) => typeof schema.$ref === "string" ? REFERENCE.exec(schema.$ref)?.[1] : void 0;
 /** Tell if a value is a JSON object: an object that is not `null` and not an array. */
 const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The member of an object with this key, or `undefined` when the object does not have it. Inherited names, such as
+* `constructor` or `toString`, are not members.
+*/
+function ownMember(object, key) {
+	return Object.hasOwn(object, key) ? object[key] : void 0;
+}
 /** A value as a JSON object, or an empty object when it is not one. */
 const objectOrEmpty = (value) => isJsonObject(value) ? value : {};
 /** The strings in a value that is an array, or no strings when it is not an array. */
@@ -228,6 +588,10 @@ function schemasOf(capability) {
 		...Object.entries(capability.failures ?? {}).map(([tag, schema]) => [`failure ${tag}`, schema])
 	].filter((entry) => entry[1] !== void 0);
 }
+/** The schemas of an event, each with the member that holds it. */
+function eventSchemasOf(event) {
+	return [["input", event.input], ["payload", event.payload]].filter((entry) => entry[1] !== void 0);
+}
 /** Every object in a JSON value, at all levels. */
 function visitObjects(value, onObject) {
 	if (Array.isArray(value)) value.forEach((item) => visitObjects(item, onObject));
@@ -240,8 +604,8 @@ function visitObjects(value, onObject) {
 function typesUsedBy(schema, types) {
 	const used = /* @__PURE__ */ new Map();
 	const collect = (node) => visitObjects(node, (inner) => {
-		const name = typeof inner.$ref === "string" ? REFERENCE.exec(inner.$ref)?.[1] : void 0;
-		const type = name === void 0 ? void 0 : types[name];
+		const name = referenceName(inner);
+		const type = name === void 0 ? void 0 : ownMember(types, name);
 		if (name !== void 0 && type !== void 0 && !used.has(name)) {
 			used.set(name, type);
 			collect(type);
@@ -258,9 +622,8 @@ function typesUsedBy(schema, types) {
 function objectInput(schema, types) {
 	const resolve = (node) => {
 		if (!isJsonObject(node)) return void 0;
-		const object = node;
-		const name = typeof object.$ref === "string" ? REFERENCE.exec(object.$ref)?.[1] : void 0;
-		return name === void 0 ? object : types[name];
+		const name = referenceName(node);
+		return name === void 0 ? node : ownMember(types, name);
 	};
 	const target = resolve(schema);
 	if (schema.type !== void 0 || target === void 0 || target.type !== void 0) return schema;
@@ -271,10 +634,18 @@ function objectInput(schema, types) {
 		...schema
 	} : schema;
 }
+/**
+* The type that a schema's `$ref` refers to, whatever other keys the schema has, or the schema itself when it has no
+* `$ref` to a type in `types`. A catalog uses it to tell if an input or a payload is an object
+* (spec/catalog.md#capabilities).
+*/
+function resolveType(schema, types) {
+	const name = referenceName(schema);
+	return (name === void 0 ? void 0 : ownMember(types, name)) ?? schema;
+}
 /** Bundle a schema (spec/catalog.md#bundling). */
 function bundle(schema, types) {
-	const only = Object.keys(schema).length === 1 ? REFERENCE.exec(String(schema.$ref))?.[1] : void 0;
-	const base = only === void 0 ? schema : types[only] ?? schema;
+	const base = Object.keys(schema).length === 1 ? resolveType(schema, types) : schema;
 	const used = typesUsedBy(base, types);
 	return used.size === 0 ? base : {
 		...base,
@@ -288,16 +659,21 @@ function viewOf(catalog, target) {
 		...capability,
 		audience: [target]
 	}]));
+	const events = Object.fromEntries(Object.entries(catalog.events ?? {}).filter(([, event]) => (event.audience ?? []).includes(target)).map(([id, event]) => [id, {
+		...event,
+		audience: [target]
+	}]));
 	const used = /* @__PURE__ */ new Map();
-	for (const capability of Object.values(capabilities)) for (const [, schema] of schemasOf(capability)) for (const [name, type] of typesUsedBy(schema, types)) used.set(name, type);
-	const { $defs: _, ...rest } = catalog;
-	const declared = catalog.targets[target];
+	const schemas = [...Object.values(capabilities).flatMap(schemasOf), ...Object.values(events).flatMap(eventSchemasOf)];
+	for (const [, schema] of schemas) for (const [name, type] of typesUsedBy(schema, types)) used.set(name, type);
+	const { $defs: _, events: __, ...rest } = catalog;
+	const declared = ownMember(catalog.targets, target);
 	return {
 		...rest,
 		targets: declared === void 0 ? {} : { [target]: declared },
 		...used.size > 0 ? { $defs: Object.fromEntries(used) } : {},
-		capabilities
+		capabilities,
+		...Object.keys(events).length > 0 ? { events } : {}
 	};
 }
-//#endregion
-export { AVAILABLE, CALL_FAILURE_KINDS, CLI_EXIT_CODES, CallFailureError, HTTP_STATUS, ID_PATTERN, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, REFERENCE, bundle, callFailure, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, fail, httpStatus, isCallFailure, isId, isJsonObject, mcpToolResult, objectInput, ok, readBounded, schemasOf, screenRequest, typesUsedBy, unavailable, viewOf, visitObjects };
+export { AVAILABLE, CALL_FAILURE_KINDS, CLI_EXIT_CODES, CLI_RESUME_FLAGS, CLI_WATCH_EXIT_CODES, CallFailureError, HTTP_STATUS, ID_PATTERN, KEEPALIVE_MS, MCP_EVENTS_EXTENSION, MCP_EVENT_ERRORS, MCP_POLL_DEFAULTS, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_SUBSCRIPTION_ID, MCP_UNKNOWN_TOOL, MCP_WEBHOOK_DEFAULTS, REFERENCE, SSE_MEDIA_TYPE, SUBSCRIBE_FAILURE_KINDS, WEBHOOK_ERRORS, bundle, byCodePoint, callFailure, canonicalJson, cliEventUsage, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, decodePollCursor, encodePollCursor, eventSchemasOf, fail, httpEventMessage, httpStatus, isCallFailure, isGloballyRoutable, isId, isJsonObject, isOccurrence, mcpEventEntry, mcpEventParams, mcpSubscribeError, mcpToolResult, objectInput, occurrenceOf, ok, ownMember, readBounded, resolveType, schemasOf, screenRequest, sseMessage, typesUsedBy, unavailable, viewOf, visitObjects, webhookGrantMs, webhookSecretBytes, webhookSignature, webhookSignedText, webhookSubscriptionId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/spec-ts",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "The fixed details of the AcidCat specification as TypeScript data and pure functions, with no dependencies. Part of the TypeScript reference implementation.",
   "keywords": [
     "acidcat",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "26.6.5",
+    "@types/node": "26.6.6",
     "typescript": "7.0.2"
   }
 }