skybridge 0.0.0-dev.febf292 → 0.0.0-dev.fec0253

package/dist/server/content-helpers.js

@@ -0,0 +1,79 @@
+/**
+ * Returns a base64-encoded string.
+ * - `Uint8Array` input is encoded via `Buffer.toString("base64")`.
+ * - `string` input is assumed to be **already base64-encoded** and is returned
+ *   as-is. Passing raw/unencoded string bytes will produce invalid MCP content.
+ */
+function toBase64(data) {
+    if (typeof data === "string") {
+        return data;
+    }
+    return Buffer.from(data).toString("base64");
+}
+/**
+ * Build an MCP text content block.
+ *
+ * @example
+ * ```ts
+ * return { content: [text("Found 3 results.")] };
+ * ```
+ */
+export function text(value, annotations) {
+    return { type: "text", text: value, ...(annotations && { annotations }) };
+}
+/**
+ * Build an MCP image content block.
+ *
+ * `data` may be a `Uint8Array` (encoded to base64 for you) or a string that is
+ * **already base64-encoded**. Passing a raw byte-string will produce invalid
+ * content.
+ */
+export function image(data, mimeType, annotations) {
+    return {
+        type: "image",
+        data: toBase64(data),
+        mimeType,
+        ...(annotations && { annotations }),
+    };
+}
+/**
+ * Build an MCP audio content block.
+ *
+ * `data` may be a `Uint8Array` (encoded to base64 for you) or a string that is
+ * **already base64-encoded**.
+ */
+export function audio(data, mimeType, annotations) {
+    return {
+        type: "audio",
+        data: toBase64(data),
+        mimeType,
+        ...(annotations && { annotations }),
+    };
+}
+/**
+ * Build an MCP embedded resource — the full content travels inline. Use this
+ * when the client needs the bytes themselves rather than a link.
+ *
+ * Pass either `text` (UTF-8 string) or `blob` (base64-encoded bytes).
+ */
+export function embeddedResource(resource, annotations) {
+    return {
+        type: "resource",
+        resource,
+        ...(annotations && { annotations }),
+    };
+}
+/**
+ * Build an MCP resource link — a `type: "resource_link"` block carrying a URI
+ * the client can fetch (or subscribe to) on demand. Use a link when the
+ * client should retrieve the bytes itself; use {@link embeddedResource} when
+ * the content must travel inline with the response.
+ */
+export function resourceLink(link, annotations) {
+    return {
+        type: "resource_link",
+        ...link,
+        ...(annotations && { annotations }),
+    };
+}
+//# sourceMappingURL=content-helpers.js.map

package/dist/server/content-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-helpers.js","sourceRoot":"","sources":["../../src/server/content-helpers.ts"],"names":[],"mappings":"AAqBA;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,IAAyB;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAClB,KAAa,EACb,WAAgC;IAEhC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CACnB,IAAyB,EACzB,QAAgB,EAChB,WAAgC;IAEhC,OAAO;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;QACpB,QAAQ;QACR,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,CAAC;KACpC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CACnB,IAAyB,EACzB,QAAgB,EAChB,WAAgC;IAEhC,OAAO;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;QACpB,QAAQ;QACR,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,CAAC;KACpC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAEoD,EACpD,WAAgC;IAEhC,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,QAAQ;QACR,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,CAAC;KACpC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,IAOC,EACD,WAAgC;IAEhC,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,GAAG,IAAI;QACP,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,CAAC;KACpC,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  AudioContent,\n  EmbeddedResource,\n  ImageContent,\n  ResourceLink,\n  TextContent,\n} from \"@modelcontextprotocol/server\";\n\n/**\n * MCP content annotations applied to any returned block.\n *\n * - `audience` — who is meant to see the content (`\"user\"`, `\"assistant\"`, or both).\n * - `priority` — relative importance hint for the host.\n * - `lastModified` — ISO timestamp for when the content was produced.\n */\ntype ContentAnnotations = {\n  audience?: (\"user\" | \"assistant\")[];\n  priority?: number;\n  lastModified?: string;\n};\n\n/**\n * Returns a base64-encoded string.\n * - `Uint8Array` input is encoded via `Buffer.toString(\"base64\")`.\n * - `string` input is assumed to be **already base64-encoded** and is returned\n *   as-is. Passing raw/unencoded string bytes will produce invalid MCP content.\n */\nfunction toBase64(data: string | Uint8Array): string {\n  if (typeof data === \"string\") {\n    return data;\n  }\n  return Buffer.from(data).toString(\"base64\");\n}\n\n/**\n * Build an MCP text content block.\n *\n * @example\n * ```ts\n * return { content: [text(\"Found 3 results.\")] };\n * ```\n */\nexport function text(\n  value: string,\n  annotations?: ContentAnnotations,\n): TextContent {\n  return { type: \"text\", text: value, ...(annotations && { annotations }) };\n}\n\n/**\n * Build an MCP image content block.\n *\n * `data` may be a `Uint8Array` (encoded to base64 for you) or a string that is\n * **already base64-encoded**. Passing a raw byte-string will produce invalid\n * content.\n */\nexport function image(\n  data: string | Uint8Array,\n  mimeType: string,\n  annotations?: ContentAnnotations,\n): ImageContent {\n  return {\n    type: \"image\",\n    data: toBase64(data),\n    mimeType,\n    ...(annotations && { annotations }),\n  };\n}\n\n/**\n * Build an MCP audio content block.\n *\n * `data` may be a `Uint8Array` (encoded to base64 for you) or a string that is\n * **already base64-encoded**.\n */\nexport function audio(\n  data: string | Uint8Array,\n  mimeType: string,\n  annotations?: ContentAnnotations,\n): AudioContent {\n  return {\n    type: \"audio\",\n    data: toBase64(data),\n    mimeType,\n    ...(annotations && { annotations }),\n  };\n}\n\n/**\n * Build an MCP embedded resource — the full content travels inline. Use this\n * when the client needs the bytes themselves rather than a link.\n *\n * Pass either `text` (UTF-8 string) or `blob` (base64-encoded bytes).\n */\nexport function embeddedResource(\n  resource:\n    | { uri: string; mimeType?: string; text: string }\n    | { uri: string; mimeType?: string; blob: string },\n  annotations?: ContentAnnotations,\n): EmbeddedResource {\n  return {\n    type: \"resource\",\n    resource,\n    ...(annotations && { annotations }),\n  };\n}\n\n/**\n * Build an MCP resource link — a `type: \"resource_link\"` block carrying a URI\n * the client can fetch (or subscribe to) on demand. Use a link when the\n * client should retrieve the bytes itself; use {@link embeddedResource} when\n * the content must travel inline with the response.\n */\nexport function resourceLink(\n  link: {\n    uri: string;\n    name: string;\n    title?: string;\n    description?: string;\n    mimeType?: string;\n    size?: number;\n  },\n  annotations?: ContentAnnotations,\n): ResourceLink {\n  return {\n    type: \"resource_link\",\n    ...link,\n    ...(annotations && { annotations }),\n  };\n}\n"]}

package/dist/server/content-helpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/content-helpers.test.js

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { audio, embeddedResource, image, resourceLink, text, } from "./content-helpers.js";
+describe("text", () => {
+    it("returns a TextContent without annotations when none given", () => {
+        expect(text("hello")).toEqual({ type: "text", text: "hello" });
+    });
+    it("includes annotations when provided", () => {
+        expect(text("hi", { priority: 1 })).toEqual({
+            type: "text",
+            text: "hi",
+            annotations: { priority: 1 },
+        });
+    });
+});
+describe("image", () => {
+    it("base64-encodes Uint8Array data", () => {
+        const bytes = new Uint8Array([104, 105]);
+        expect(image(bytes, "image/png")).toEqual({
+            type: "image",
+            data: "aGk=",
+            mimeType: "image/png",
+        });
+    });
+    it("passes string data through unchanged (caller is responsible for base64)", () => {
+        expect(image("YWxyZWFkeS1iNjQ=", "image/png")).toEqual({
+            type: "image",
+            data: "YWxyZWFkeS1iNjQ=",
+            mimeType: "image/png",
+        });
+    });
+});
+describe("audio", () => {
+    it("base64-encodes Uint8Array data", () => {
+        const bytes = new Uint8Array([104, 105]);
+        expect(audio(bytes, "audio/mpeg")).toMatchObject({
+            type: "audio",
+            data: "aGk=",
+            mimeType: "audio/mpeg",
+        });
+    });
+});
+describe("embeddedResource", () => {
+    it("wraps a text resource with a type tag", () => {
+        expect(embeddedResource({
+            uri: "file:///a.txt",
+            mimeType: "text/plain",
+            text: "x",
+        })).toEqual({
+            type: "resource",
+            resource: { uri: "file:///a.txt", mimeType: "text/plain", text: "x" },
+        });
+    });
+    it("wraps a blob resource with a type tag", () => {
+        expect(embeddedResource({ uri: "file:///a.bin", blob: "YmFy" })).toEqual({
+            type: "resource",
+            resource: { uri: "file:///a.bin", blob: "YmFy" },
+        });
+    });
+});
+describe("resourceLink", () => {
+    it("spreads link fields alongside the type tag", () => {
+        expect(resourceLink({ uri: "file:///a", name: "a", title: "A" })).toEqual({
+            type: "resource_link",
+            uri: "file:///a",
+            name: "a",
+            title: "A",
+        });
+    });
+});
+//# sourceMappingURL=content-helpers.test.js.map

package/dist/server/content-helpers.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-helpers.test.js","sourceRoot":"","sources":["../../src/server/content-helpers.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport {\n  audio,\n  embeddedResource,\n  image,\n  resourceLink,\n  text,\n} from \"./content-helpers.js\";\n\ndescribe(\"text\", () => {\n  it(\"returns a TextContent without annotations when none given\", () => {\n    expect(text(\"hello\")).toEqual({ type: \"text\", text: \"hello\" });\n  });\n\n  it(\"includes annotations when provided\", () => {\n    expect(text(\"hi\", { priority: 1 })).toEqual({\n      type: \"text\",\n      text: \"hi\",\n      annotations: { priority: 1 },\n    });\n  });\n});\n\ndescribe(\"image\", () => {\n  it(\"base64-encodes Uint8Array data\", () => {\n    const bytes = new Uint8Array([104, 105]);\n    expect(image(bytes, \"image/png\")).toEqual({\n      type: \"image\",\n      data: \"aGk=\",\n      mimeType: \"image/png\",\n    });\n  });\n\n  it(\"passes string data through unchanged (caller is responsible for base64)\", () => {\n    expect(image(\"YWxyZWFkeS1iNjQ=\", \"image/png\")).toEqual({\n      type: \"image\",\n      data: \"YWxyZWFkeS1iNjQ=\",\n      mimeType: \"image/png\",\n    });\n  });\n});\n\ndescribe(\"audio\", () => {\n  it(\"base64-encodes Uint8Array data\", () => {\n    const bytes = new Uint8Array([104, 105]);\n    expect(audio(bytes, \"audio/mpeg\")).toMatchObject({\n      type: \"audio\",\n      data: \"aGk=\",\n      mimeType: \"audio/mpeg\",\n    });\n  });\n});\n\ndescribe(\"embeddedResource\", () => {\n  it(\"wraps a text resource with a type tag\", () => {\n    expect(\n      embeddedResource({\n        uri: \"file:///a.txt\",\n        mimeType: \"text/plain\",\n        text: \"x\",\n      }),\n    ).toEqual({\n      type: \"resource\",\n      resource: { uri: \"file:///a.txt\", mimeType: \"text/plain\", text: \"x\" },\n    });\n  });\n\n  it(\"wraps a blob resource with a type tag\", () => {\n    expect(embeddedResource({ uri: \"file:///a.bin\", blob: \"YmFy\" })).toEqual({\n      type: \"resource\",\n      resource: { uri: \"file:///a.bin\", blob: \"YmFy\" },\n    });\n  });\n});\n\ndescribe(\"resourceLink\", () => {\n  it(\"spreads link fields alongside the type tag\", () => {\n    expect(resourceLink({ uri: \"file:///a\", name: \"a\", title: \"A\" })).toEqual({\n      type: \"resource_link\",\n      uri: \"file:///a\",\n      name: \"a\",\n      title: \"A\",\n    });\n  });\n});\n"]}

package/dist/server/events.d.ts

@@ -0,0 +1,113 @@
+import { type McpServer as SdkMcpServer, type StandardSchemaV1, type StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+/**
+ * A webhook subscription, as passed to `onSubscribe`. Whatever delivers the
+ * events POSTs them to `url`, signed with `secret`, until `expiresAt`.
+ */
+export interface EventSubscription {
+    /** Stable across refreshes: the same user subscribing to the same event with the same arguments and callback gets the same `id`. */
+    id: string;
+    /** Callback URL deliveries are POSTed to. */
+    url: string;
+    /** Standard Webhooks signing secret (`whsec_…`). A refresh may carry a new one. */
+    secret: string;
+    /** When the subscription lapses unless the host refreshes it. */
+    expiresAt: Date;
+}
+/** An event occurrence, as passed to {@link deliverEvent}. */
+export interface EventOccurrence {
+    /** Event type name, as registered with `registerEvent`. */
+    name: string;
+    /** Stable identifier the host uses to drop duplicates, ideally the upstream's. Reuse it when retrying. */
+    id: string;
+    /** When the event happened. Defaults to now. */
+    timestamp?: Date;
+    /** Payload matching the event's `payloadSchema`. */
+    data: unknown;
+}
+/** Outcome of {@link deliverEvent}. Retry with the same event `id` when `retryable`. */
+export type DeliveryResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    retryable: boolean;
+    status?: number;
+};
+type EventSchema = Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON;
+export type InferEventSchema<T extends EventSchema> = T extends StandardSchemaWithJSON ? StandardSchemaV1.InferOutput<T> : T extends Record<string, StandardSchemaWithJSON> ? {
+    [K in keyof T as undefined extends StandardSchemaV1.InferOutput<T[K]> ? never : K]: StandardSchemaV1.InferOutput<T[K]>;
+} & {
+    [K in keyof T as undefined extends StandardSchemaV1.InferOutput<T[K]> ? K : never]?: StandardSchemaV1.InferOutput<T[K]>;
+} : never;
+/** The `registerEvent` config: how the event type is described in `events/list`. */
+export interface EventConfig<TInput extends EventSchema> {
+    /** Stable, specific name such as `comment.created`. */
+    name: string;
+    /** What the event is and when it fires. */
+    description?: string;
+    /** Subscription arguments (filters): a Zod shape or a Standard Schema object. */
+    inputSchema?: TInput;
+    /** Shape of the delivered `data`: a Zod shape or a Standard Schema object. */
+    payloadSchema: EventSchema;
+    _meta?: Record<string, unknown>;
+}
+/** What `registerEvent` does when the host subscribes and unsubscribes. */
+export interface EventHooks<TArguments, TExtra> {
+    /**
+     * Runs on every `events/subscribe`, including the host's refreshes, once
+     * the callback URL is verified. Hand the subscription to whatever delivers
+     * the events, keyed by `subscription.id`. Throw (e.g. a `ProtocolError`) to
+     * reject it, for instance when the user may not access what the arguments
+     * point to.
+     */
+    onSubscribe(args: TArguments, context: {
+        subscription: EventSubscription;
+        extra: TExtra;
+    }): void | Promise<void>;
+    /** Runs on `events/unsubscribe`. Stop delivering to `subscription.id`. */
+    onUnsubscribe(args: TArguments, context: {
+        subscription: Pick<EventSubscription, "id">;
+        extra: TExtra;
+    }): void | Promise<void>;
+}
+/**
+ * @experimental POST one event to a subscription handed out by `onSubscribe`,
+ * as MCP Events expects: the event envelope, Standard Webhooks signature
+ * headers, a 10 second deadline and, outside development, no requests to
+ * private addresses. Pass the old and new secrets during a rotation so both
+ * sign the delivery. A subscription past `expiresAt` is not posted to.
+ * Retrying is up to the caller. API may change.
+ *
+ * @example
+ * ```ts
+ * const result = await deliverEvent(subscription, {
+ *   name: "comment.created",
+ *   id: comment.id,
+ *   data: { documentId: comment.documentId, excerpt: comment.text.slice(0, 280) },
+ * });
+ * if (!result.ok && result.retryable) {
+ *   await queue.retryLater(subscription, comment);
+ * }
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/register-event
+ */
+export declare function deliverEvent(subscription: Pick<EventSubscription, "id" | "url"> & {
+    secret: string | string[];
+    expiresAt: Date | string;
+}, event: EventOccurrence): Promise<DeliveryResult>;
+/**
+ * The event types registered on one server, and the `events/*` handlers that
+ * serve them.
+ *
+ * @internal
+ */
+export declare class EventRegistry {
+    private readonly server;
+    private readonly events;
+    constructor(server: Pick<SdkMcpServer["server"], "setRequestHandler">);
+    add(config: EventConfig<EventSchema>, hooks: EventHooks<never, never>): void;
+    private install;
+    private resolve;
+}
+export {};

package/dist/server/events.js

@@ -0,0 +1,318 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import http from "node:http";
+import https from "node:https";
+import { INVALID_PARAMS, ProtocolError, } from "@modelcontextprotocol/server";
+import { globalHttpAgent, globalHttpsAgent } from "request-filtering-agent";
+import { Webhook } from "standardwebhooks";
+import { z } from "zod/v4";
+const EVENTS_ERROR = {
+    NotFound: -32011,
+    Forbidden: -32012,
+    Unsupported: -32014,
+    CallbackEndpointError: -32015,
+};
+const MAX_PAYLOAD_BYTES = 256 * 1024;
+const DELIVERY_TIMEOUT_MS = 10_000;
+const VERIFICATION_CACHE_MS = 60 * 60_000;
+const MIN_TTL_MS = 60_000;
+const DEFAULT_TTL_MS = 30 * 60_000;
+const MAX_TTL_MS = 24 * 60 * 60_000;
+function toStandardSchema(schema) {
+    return "~standard" in schema
+        ? schema
+        : z.object(schema);
+}
+async function validate(schema, value) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues) {
+        throw new ProtocolError(INVALID_PARAMS, `Invalid arguments: ${result.issues.map((issue) => issue.message).join(", ")}`);
+    }
+    return result.value;
+}
+function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function subscriberOf(ctx) {
+    const authInfo = ctx.http?.authInfo;
+    const subject = authInfo?.extra?.subject;
+    const subscriber = typeof subject === "string" ? subject : authInfo?.clientId;
+    if (!subscriber) {
+        throw new ProtocolError(EVENTS_ERROR.Forbidden, "Webhook subscriptions require an authenticated caller");
+    }
+    return subscriber;
+}
+function isValidSecret(secret) {
+    const encoded = secret.startsWith("whsec_") ? secret.slice(6) : "";
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) {
+        return false;
+    }
+    const length = Buffer.from(encoded, "base64").length;
+    return length >= 24 && length <= 64;
+}
+const insecureCallbacksAllowed = () => process.env.NODE_ENV !== "production";
+function checkCallbackUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new ProtocolError(INVALID_PARAMS, "delivery.url is not a valid URL");
+    }
+    const allowed = url.protocol === "https:" ||
+        (url.protocol === "http:" && insecureCallbacksAllowed());
+    if (!allowed) {
+        throw new ProtocolError(INVALID_PARAMS, "delivery.url must use https");
+    }
+    return url.href;
+}
+function post(url, headers, body) {
+    const signal = AbortSignal.timeout(DELIVERY_TIMEOUT_MS);
+    const failure = (error) => ({
+        ok: false,
+        reason: signal.aborted
+            ? "timeout"
+            : error?.code?.startsWith("ERR_TLS") || error?.code?.includes("CERT")
+                ? "tls_error"
+                : "connection_refused",
+    });
+    const [client, agent] = url.startsWith("https:")
+        ? [https, globalHttpsAgent]
+        : [http, globalHttpAgent];
+    return new Promise((resolve) => {
+        const request = client.request(url, {
+            method: "POST",
+            headers: { ...headers, "content-length": Buffer.byteLength(body) },
+            signal,
+            ...(!insecureCallbacksAllowed() && { agent }),
+        }, (response) => {
+            const status = response.statusCode ?? 0;
+            const chunks = [];
+            let size = 0;
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size <= 64 * 1024) {
+                    chunks.push(chunk);
+                }
+            });
+            response.on("end", () => {
+                if (status >= 200 && status < 300) {
+                    resolve({ ok: true, body: Buffer.concat(chunks).toString() });
+                }
+                else {
+                    resolve({
+                        ok: false,
+                        status,
+                        reason: status >= 500 ? "http_5xx" : "http_4xx",
+                    });
+                }
+            });
+            response.on("error", (error) => resolve(failure(error)));
+            response.on("close", () => resolve(failure()));
+        });
+        request.on("error", (error) => resolve(failure(error)));
+        request.end(body);
+    });
+}
+function signedPost(subscription, messageId, body) {
+    const signedAt = new Date();
+    const secrets = [subscription.secret].flat();
+    return post(subscription.url, {
+        "content-type": "application/json",
+        "webhook-id": messageId,
+        "webhook-timestamp": String(Math.floor(signedAt.getTime() / 1000)),
+        "webhook-signature": secrets
+            .map((secret) => new Webhook(secret).sign(messageId, signedAt, body))
+            .join(" "),
+        "x-mcp-subscription-id": subscription.id,
+    }, body);
+}
+/**
+ * @experimental POST one event to a subscription handed out by `onSubscribe`,
+ * as MCP Events expects: the event envelope, Standard Webhooks signature
+ * headers, a 10 second deadline and, outside development, no requests to
+ * private addresses. Pass the old and new secrets during a rotation so both
+ * sign the delivery. A subscription past `expiresAt` is not posted to.
+ * Retrying is up to the caller. API may change.
+ *
+ * @example
+ * ```ts
+ * const result = await deliverEvent(subscription, {
+ *   name: "comment.created",
+ *   id: comment.id,
+ *   data: { documentId: comment.documentId, excerpt: comment.text.slice(0, 280) },
+ * });
+ * if (!result.ok && result.retryable) {
+ *   await queue.retryLater(subscription, comment);
+ * }
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/register-event
+ */
+export async function deliverEvent(subscription, event) {
+    if (!(new Date(subscription.expiresAt).getTime() > Date.now())) {
+        return { ok: false, reason: "expired", retryable: false };
+    }
+    const body = JSON.stringify({
+        eventId: event.id,
+        name: event.name,
+        timestamp: (event.timestamp ?? new Date()).toISOString(),
+        data: event.data,
+        cursor: null,
+    });
+    if (Buffer.byteLength(body) > MAX_PAYLOAD_BYTES) {
+        throw new Error(`Event "${event.name}" payload exceeds ${MAX_PAYLOAD_BYTES} bytes; send a summary and expose a tool to fetch the rest.`);
+    }
+    const outcome = await signedPost(subscription, event.id, body);
+    if (outcome.ok) {
+        return { ok: true };
+    }
+    const status = outcome.status ?? 0;
+    return {
+        ...outcome,
+        retryable: status !== 410 && status !== 413 && (status < 300 || status >= 400),
+    };
+}
+const verifiedCallbacks = new Map();
+async function verifyCallback(subscriber, subscription) {
+    const key = `${subscriber}\n${subscription.url}`;
+    const now = Date.now();
+    if ((verifiedCallbacks.get(key) ?? 0) > now) {
+        return;
+    }
+    const challenge = randomBytes(24).toString("base64url");
+    const outcome = await signedPost(subscription, `msg_verification_${randomBytes(12).toString("hex")}`, JSON.stringify({ type: "verification", challenge }));
+    let echoed;
+    if (outcome.ok) {
+        try {
+            echoed = JSON.parse(outcome.body)?.challenge;
+        }
+        catch { }
+    }
+    const matched = typeof echoed === "string" &&
+        echoed.length === challenge.length &&
+        timingSafeEqual(Buffer.from(echoed), Buffer.from(challenge));
+    if (!matched) {
+        throw new ProtocolError(EVENTS_ERROR.CallbackEndpointError, "Callback endpoint verification failed", { reason: outcome.ok ? "challenge_failed" : outcome.reason });
+    }
+    for (const [cached, until] of verifiedCallbacks) {
+        if (until <= now) {
+            verifiedCallbacks.delete(cached);
+        }
+    }
+    verifiedCallbacks.set(key, now + VERIFICATION_CACHE_MS);
+}
+const SubscriptionKeySchema = z.object({
+    name: z.string(),
+    arguments: z.record(z.string(), z.unknown()).optional(),
+    delivery: z.object({ url: z.string() }),
+});
+const SubscribeParamsSchema = SubscriptionKeySchema.extend({
+    delivery: z.object({
+        mode: z.string().optional(),
+        url: z.string(),
+        secret: z.string(),
+    }),
+    cursor: z.string().nullable().optional(),
+    ttlMs: z.number().nullable().optional(),
+});
+/**
+ * The event types registered on one server, and the `events/*` handlers that
+ * serve them.
+ *
+ * @internal
+ */
+export class EventRegistry {
+    server;
+    events = new Map();
+    constructor(server) {
+        this.server = server;
+    }
+    add(config, hooks) {
+        if (this.events.has(config.name)) {
+            throw new Error(`Event "${config.name}" is already registered.`);
+        }
+        if (this.events.size === 0) {
+            this.install();
+        }
+        this.events.set(config.name, {
+            name: config.name,
+            description: config.description,
+            inputSchema: toStandardSchema(config.inputSchema ?? {}),
+            payloadSchema: toStandardSchema(config.payloadSchema),
+            _meta: config._meta,
+            hooks,
+        });
+    }
+    install() {
+        this.server.setRequestHandler("events/list", { params: z.object({ cursor: z.string().optional() }).optional() }, () => ({
+            events: [...this.events.values()].map((event) => ({
+                name: event.name,
+                ...(event.description && { description: event.description }),
+                delivery: ["webhook"],
+                inputSchema: event.inputSchema["~standard"].jsonSchema.input({
+                    target: "draft-2020-12",
+                }),
+                payloadSchema: event.payloadSchema["~standard"].jsonSchema.output({
+                    target: "draft-2020-12",
+                }),
+                ...(event._meta && { _meta: event._meta }),
+            })),
+        }));
+        this.server.setRequestHandler("events/subscribe", { params: SubscribeParamsSchema }, async (params, ctx) => {
+            if (params.delivery.mode && params.delivery.mode !== "webhook") {
+                throw new ProtocolError(EVENTS_ERROR.Unsupported, `Unsupported delivery mode: ${params.delivery.mode}`, { feature: "deliveryMode", value: params.delivery.mode });
+            }
+            if (!isValidSecret(params.delivery.secret)) {
+                throw new ProtocolError(INVALID_PARAMS, "delivery.secret must be whsec_ followed by base64 of 24 to 64 bytes");
+            }
+            const { event, subscriber, args, id, url } = await this.resolve(params, ctx);
+            const ttl = params.ttlMs === null ? MAX_TTL_MS : (params.ttlMs ?? DEFAULT_TTL_MS);
+            const subscription = {
+                id,
+                url,
+                secret: params.delivery.secret,
+                expiresAt: new Date(Date.now() + Math.min(Math.max(ttl, MIN_TTL_MS), MAX_TTL_MS)),
+            };
+            await verifyCallback(subscriber, subscription);
+            await event.hooks.onSubscribe(args, { subscription, extra: ctx });
+            return {
+                id,
+                refreshBefore: subscription.expiresAt.toISOString(),
+                cursor: null,
+                truncated: false,
+            };
+        });
+        this.server.setRequestHandler("events/unsubscribe", { params: SubscriptionKeySchema }, async (params, ctx) => {
+            const { event, args, id } = await this.resolve(params, ctx);
+            await event.hooks.onUnsubscribe(args, {
+                subscription: { id },
+                extra: ctx,
+            });
+            return {};
+        });
+    }
+    async resolve(params, ctx) {
+        const event = this.events.get(params.name);
+        if (!event) {
+            throw new ProtocolError(EVENTS_ERROR.NotFound, `Unknown event: ${params.name}`, { kind: "event" });
+        }
+        const url = checkCallbackUrl(params.delivery.url);
+        const subscriber = subscriberOf(ctx);
+        const rawArguments = params.arguments ?? {};
+        const args = await validate(event.inputSchema, rawArguments);
+        const hash = createHash("sha256")
+            .update(canonicalJson([subscriber, url, event.name, rawArguments]))
+            .digest("hex");
+        return { event, subscriber, args, url, id: `sub_${hash.slice(0, 32)}` };
+    }
+}
+//# sourceMappingURL=events.js.map