qyl-mcp-server 7.1.0 → 7.2.0

package/dist/events.d.ts

@@ -0,0 +1,235 @@
+/**
+ * MCP Events for ChatGPT: `events/list`, `events/subscribe` and
+ * `events/unsubscribe` on the authenticated MCP endpoint, with signed webhook
+ * delivery of one event type, `trace.error`.
+ *
+ * Contract: developers.openai.com/plugins/build/mcp-events (ChatGPT supports
+ * webhook delivery with callback verification only) and the draft MCP Events
+ * design sketch in modelcontextprotocol/experimental-ext-triggers-events.
+ * `@modelcontextprotocol/server` 2.3.1 ships no `events/*` methods, so the
+ * three are custom request handlers and the capability is added by hand.
+ *
+ * Delivery source: the collector's recent-trace list, polled only while a
+ * subscription is live. The first poll sets a baseline, so a subscription
+ * never receives a backlog. Events carry `cursor: null` — there is no replay;
+ * traces that arrive while the server is down are not delivered.
+ *
+ * Access: subscribing, refreshing and unsubscribing each pass the same OAuth
+ * gate as every tool call. The required authorization callback rechecks the
+ * owner's current access while polling and before delivery, including retries.
+ * Authorization outages suspend delivery; revoked access removes the record.
+ */
+import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+import { AtomicJsonStore } from "./atomic-json-store.js";
+import type { QylTrace } from "./wire.js";
+import { type WebhookPost } from "./webhook.js";
+export declare const TRACE_ERROR_EVENT_NAME = "trace.error";
+/** JSON-RPC error for a callback that failed validation or verification. */
+export declare const CALLBACK_ENDPOINT_ERROR = -32015;
+export declare const DEFAULT_TTL_MS: number;
+export declare const MIN_TTL_MS: number;
+export declare const MAX_TTL_MS: number;
+/**
+ * Live subscriptions one caller may hold. Every subscription is a stored
+ * entry, a delivery fan-out target and, for a new callback, an outbound
+ * verification POST; without a cap one account grows all three at will.
+ */
+export declare const MAX_SUBSCRIPTIONS_PER_PRINCIPAL = 20;
+/** The one event definition `events/list` returns. */
+export declare const TRACE_ERROR_EVENT: {
+    readonly name: "trace.error";
+    readonly description: string;
+    readonly delivery: readonly ["webhook"];
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly service_name: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+                readonly description: "Only traces that involve this service.";
+            };
+        };
+        readonly additionalProperties: false;
+    };
+    readonly payloadSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly trace_id: {
+                readonly type: "string";
+                readonly description: "Trace identifier; pass it to get_trace or display_traces.";
+            };
+            readonly root_span: {
+                readonly type: "string";
+                readonly description: "Name of the trace's root span.";
+            };
+            readonly services: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Services involved in the trace.";
+            };
+            readonly span_count: {
+                readonly type: "integer";
+                readonly description: "Total span count.";
+            };
+            readonly duration_ms: {
+                readonly type: "number";
+                readonly description: "Trace duration in milliseconds.";
+            };
+            readonly start_time: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "Trace start time.";
+            };
+        };
+        readonly required: readonly ["trace_id", "root_span", "services", "span_count", "duration_ms", "start_time"];
+        readonly additionalProperties: false;
+    };
+};
+declare const SubscribeParamsSchema: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    delivery: z.ZodObject<{
+        mode: z.ZodString;
+        url: z.ZodString;
+        secret: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    cursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ttlMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+export type SubscribeParams = z.infer<typeof SubscribeParamsSchema>;
+declare const UnsubscribeParamsSchema: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    delivery: z.ZodObject<{
+        mode: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type UnsubscribeParams = z.infer<typeof UnsubscribeParamsSchema>;
+/** The authenticated caller a subscription belongs to. */
+export interface Principal {
+    subject: string;
+    clientId: string;
+}
+declare const StoredSubscriptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    subject: z.ZodString;
+    clientId: z.ZodString;
+    name: z.ZodLiteral<"trace.error">;
+    arguments: z.ZodObject<{
+        service_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    url: z.ZodString;
+    secret: z.ZodString;
+    previousSecret: z.ZodOptional<z.ZodString>;
+    previousSecretUntil: z.ZodOptional<z.ZodString>;
+    refreshBefore: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type StoredSubscription = z.infer<typeof StoredSubscriptionSchema>;
+declare const EventStoreStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    subscriptions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        subject: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodLiteral<"trace.error">;
+        arguments: z.ZodObject<{
+            service_name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        url: z.ZodString;
+        secret: z.ZodString;
+        previousSecret: z.ZodOptional<z.ZodString>;
+        previousSecretUntil: z.ZodOptional<z.ZodString>;
+        refreshBefore: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EventStoreState = z.infer<typeof EventStoreStateSchema>;
+/** Subscription storage that survives restarts: an atomic JSON file (0600). */
+export declare function createEventStore(filePath: string): AtomicJsonStore<EventStoreState>;
+/** Key-order-independent JSON, so `{a,b}` and `{b,a}` name one subscription. */
+export declare function canonicalJson(value: unknown): string;
+/** Deterministic ID over principal, callback URL, event name and arguments. */
+export declare function subscriptionId(principal: Principal, url: string, name: string, args: unknown): string;
+/** The lifetime granted for a requested `ttlMs`: bounded, and never unbounded. */
+export declare function grantedTtlMs(ttlMs: number | null | undefined): number;
+/** The principal of a verified request, or a JSON-RPC error without one. */
+export declare function principalOf(ctx: Pick<ServerContext, "http">): Principal;
+/** The `data` of a `trace.error` delivery; matches `payloadSchema`. */
+export declare function traceErrorPayload(trace: QylTrace): Record<string, unknown>;
+export interface EventsRuntimeOptions {
+    store: AtomicJsonStore<EventStoreState>;
+    /** Live access check. False revokes; errors suspend delivery without deleting state. */
+    isAuthorized: (principal: Principal) => Promise<boolean>;
+    /** Network seam; defaults to the public-HTTPS-only `postWebhook`. */
+    post?: WebhookPost;
+    /** Trace source scoped to the authenticated subscriber's project. */
+    recentTraces?: (principal: Principal) => Promise<readonly QylTrace[]>;
+    pollIntervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    log?: (message: string) => void;
+}
+/**
+ * One per process: owns the subscription store, the verification cache and the
+ * poller. `register` wires the three methods into each per-request McpServer.
+ */
+export declare class EventsRuntime {
+    private readonly store;
+    private readonly isAuthorized;
+    private readonly post;
+    private readonly recentTraces;
+    private readonly pollIntervalMs;
+    private readonly now;
+    private readonly sleep;
+    private readonly log;
+    private readonly verified;
+    private readonly seen;
+    private ready;
+    private timer;
+    private polling;
+    private stopped;
+    private readonly deliveries;
+    constructor(options: EventsRuntimeOptions);
+    /** Advertise `events` and answer the three methods on this server instance. */
+    register(server: McpServer): void;
+    list(): {
+        events: (typeof TRACE_ERROR_EVENT)[];
+    };
+    subscribe(params: SubscribeParams, principal: Principal): Promise<{
+        id: string;
+        refreshBefore: string;
+        cursor: null;
+        truncated: false;
+    }>;
+    unsubscribe(params: UnsubscribeParams, principal: Principal): Promise<Record<string, never>>;
+    /** A refresh always passes; a new subscription needs a free slot for its caller. */
+    private assertCapacity;
+    /**
+     * A signed, single-use challenge before any application data; a success is
+     * cached per principal and callback URL for a bounded period.
+     */
+    private verifyCallback;
+    /** Loads the store once; every store access waits for it. */
+    private initialized;
+    /** Start the poller if a live subscription exists; `stop` ends it. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private ensurePolling;
+    private isLive;
+    private pruneState;
+    private authorized;
+    /** One poll: drop lapsed subscriptions, then deliver each new error trace. */
+    poll(): Promise<void>;
+    private pollOnce;
+    private sourceKey;
+    private deliver;
+    /** POST one signed event, retrying transient failures with backoff. */
+    private deliverWhileActive;
+}
+export {};