@wakeshift/sdk 0.2.0 → 0.4.0

package/dist/events.d.ts

@@ -1,9 +1,9 @@
-import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
 import { type AnySchema, type SchemaInput, type SchemaOutput, type ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import { WakeshiftError } from "./errors.js";
 import { type Dialect } from "./spec.js";
-import { type Published, type PublishUrl, type Recognised, type ToolExtra, type Wakeshift } from "./wakeshift.js";
+import { type Emitted, type PublishUrl, type Recipient, type ToolExtra, type Via, type Wakeshift } from "./wakeshift.js";
+import { type EventsOptions } from "./toolcall.js";
 /** Who is subscribing: what authorize decides on. */
 export interface Subscriber {
     /** The app's ID for the person (attach's identify), if it has one. */
@@ -45,15 +45,26 @@ export interface EventOptions<A extends AnySchema, P extends AnySchema> {
      * to keep. One that isn't delivered expires as any other does.
      */
     deleteOnDelivery?: boolean;
-    /** Advanced: the topic template and payload filter, if the defaults don't fit. */
+    /**
+     * Advanced: the topic template and payload filter, if the defaults don't
+     * fit. A filter without a topic adds to the optional arguments' filters,
+     * and may not name the same payload field as one of them.
+     */
     topic?: string;
     filter?: Record<string, string>;
 }
 export interface EmitOptions {
-    /** Makes retries emit once for a day (at most 200 characters). */
+    /** Makes retries emit once for a day (at most 200 characters). A retry must name the same recipients: Wakeshift uses the first's. */
     id?: string;
-    /** A personal event's one subscriber: the app's ID for them (attach's identify). Required for personal events, refused otherwise. */
-    to?: string;
+    /**
+     * A personal event's recipients (at most 1,000), one or a list, mixed: a
+     * user, the app's ID for them (attach's identify), reaching every
+     * subscription they have to the event with these arguments;
+     * `{ user, subscription }`, exactly that subscription of that user's;
+     * `{ native: user }`, only that user's native (webhook) subscriptions.
+     * Required for personal events, refused otherwise.
+     */
+    to?: string | Recipient | (string | Recipient)[];
 }
 /** The manifest form of an event type. */
 export interface EventTypeManifest {
@@ -79,10 +90,11 @@ export declare class WakeEvent<A extends AnySchema = AnySchema, P extends AnySch
     constructor(wake: Wakeshift, name: string, opts: EventOptions<A, P>);
     /**
      * Sends one occurrence: to everyone subscribed with these arguments, or,
-     * for a personal event, to the one subscriber `to` names. The payload is
+     * for a personal event, to the recipients `to` names. The payload is
      * checked against the event's schema first.
      */
-    emit(args: SchemaInput<A>, payload: SchemaInput<P>, opts?: EmitOptions): Promise<Published>;
+    emit(args: SchemaInput<A>, payload: SchemaInput<P>, opts?: EmitOptions): Promise<Emitted>;
+    private wireTo;
     /**
      * A capability URL that emits this event with these arguments (a personal
      * event: to the one subscriber `to` names), for services that can only
@@ -95,65 +107,97 @@ export declare class WakeEvent<A extends AnySchema = AnySchema, P extends AnySch
         to?: string;
     }): Promise<PublishUrl>;
     /**
-     * Subscribes the conversation calling your tool, the way subscribe_events
-     * would, so a tool like "join" can set up its own wakes in one step. For
-     * clients that subscribe through Wakeshift's wake paths; native MCP Events
-     * clients subscribe themselves. Your tool decides who may: authorize isn't
-     * consulted here. user is the app's ID for the person (required for a
-     * personal event); wakeArgs are your tool's wake.args (session_key,
-     * harness, conversation_id).
+     * How many conversations are subscribed to this event with these
+     * arguments (a personal event: those of the one user `to` names), how
+     * many are connected now, and how. Only reads.
+     */
+    status(args: SchemaInput<A>, opts?: {
+        to?: string;
+    }): Promise<EventStatus>;
+    /**
+     * Reads subscriptions to this event by ID, each with the user
+     * `call.subscribe` made it for, up to 1,000 at once: whether each is live
+     * and its conversation connected now, and how. Only reads.
      */
-    subscribe(extra: ToolExtra, args: SchemaInput<A>, opts: {
-        server?: McpServer;
-        client?: string;
-        user?: string;
-        wakeArgs?: Record<string, unknown>;
-    }): Promise<CallerSubscription>;
+    statusOf(subs: {
+        user: string;
+        subscription: string;
+    }[]): Promise<EventSubscriptionStatus[]>;
     /**
-     * Ends the calling conversation's subscription with these arguments, the
-     * way unsubscribe_events would: for a tool like "unwatch". False if it
-     * wasn't subscribed.
+     * Ends one of user's subscriptions to this app's events, by its ID (a
+     * Subscription's id from call.subscribe, or list_subscriptions'), outside
+     * a tool: a player who timed out, a member removed. False if there was none.
      */
-    unsubscribe(extra: ToolExtra, args: SchemaInput<A>, opts: {
-        server?: McpServer;
-        client?: string;
-        user?: string;
-        wakeArgs?: Record<string, unknown>;
-    }): Promise<boolean>;
-    /** Ends one of user's subscriptions to this app's events, by its ID (from subscribe or list_subscriptions). False if there was none. */
     end(user: string, id: string): Promise<boolean>;
 }
-/** A subscription made from inside an app's own tool (WakeEvent.subscribe). */
-export interface CallerSubscription {
+/** The most subscriptions one `statusOf` reads. */
+export declare const MAX_STATUS_SUBSCRIPTIONS = 1000;
+/** Who is subscribed to an event with some arguments right now (`event.status`). */
+export interface EventStatus {
+    /** Conversations subscribed (ended or expired subscriptions don't count). */
+    subscriptions: number;
+    /** Of those, connected now. */
+    connected: number;
+    /** How many are connected each way. */
+    via: Record<Via, number>;
+}
+/** One subscription right now (`event.statusOf`). */
+export interface EventSubscriptionStatus {
     id: string;
-    /** False when the conversation was already subscribed with these arguments (renewed). */
-    created: boolean;
-    /** The conversation's session handle: pass it back as session_key. */
-    session: string;
-    /** Which harness Wakeshift recognised, and how. */
-    agent: Recognised;
-    /** Your tool's text, with what the agent needs to be woken added. */
-    result(text: string | CallToolResult): CallToolResult;
+    user: string;
+    /** The subscription is the user's, to this event, and hasn't ended. One that names nothing is false too. */
+    live: boolean;
+    /** Its conversation is reachable now, and `via` says how. */
+    connected: boolean;
+    via?: Via;
 }
-/** A subscriber's arguments don't match the event's schema. */
-export declare class ArgsError extends Error {
+/**
+ * An event's arguments or payload don't match its schema: a WakeshiftError
+ * with code bad_arguments (status 400), as Wakeshift answers the same
+ * mistake, thrown before asking it.
+ */
+export declare class ArgsError extends WakeshiftError {
+    constructor(message: string);
 }
 /** Who is behind a request to the app's MCP server, as the app knows them (AttachOptions.identify). */
 export interface Identity {
     /** The app's ID for the person: what personal events and list_subscriptions need, and native subscriptions belong to. */
     user?: string;
+    /**
+     * The MCP client's name, for a request that doesn't carry one: a
+     * stateless server never sees initialize, so the app passes the name it
+     * knows from its own sign-in (an OAuth registration's client_name, say).
+     * Wakeshift reads it to tell which program the agent runs in, and
+     * whether the client subscribes to events itself. A name the request
+     * carries (initialize's, or its _meta's) wins. Leave it out for a caller
+     * that must have no name.
+     */
+    client?: string;
 }
 export interface AttachOptions {
     /**
-     * Who is behind a request, from the server's authentication. Default:
-     * the guest GuestAuth signed in ({ user: guestOf(extra)?.user }).
+     * Who is behind a request. The app passes identify, returning { user }:
+     * its own ID for the person, from its own sign-in (and, on a stateless
+     * server, the client's name as `client`). Without it, requests have no
+     * user, so personal events and list_subscriptions refuse.
      */
     identify?: (extra: ToolExtra & {
         authInfo?: AuthInfo;
     }) => Identity | undefined;
+    /**
+     * Which of attach's own tools it adds (BUILTIN_TOOLS): subscribe_events,
+     * unsubscribe_events and list_subscriptions. Default: all three; `[]`
+     * adds none. Leave out unsubscribe_events or list_subscriptions only if
+     * your own tools let a person see and stop their subscriptions.
+     */
+    tools?: readonly BuiltinTool[];
+    /** The event features' options: events.native overrides native detection for wrapped tools (attached.events). */
+    events?: EventsOptions;
 }
-/** A client that speaks MCP Events: it declared the extension, or it's one known to (ChatGPT). */
-export declare function speaksEvents(capabilities: Record<string, unknown> | undefined, clientName: string): boolean;
+/** The tools attach adds, unless AttachOptions.tools names fewer. */
+export declare const BUILTIN_TOOLS: readonly ["subscribe_events", "unsubscribe_events", "list_subscriptions"];
+/** One of attach's own tools. */
+export type BuiltinTool = (typeof BUILTIN_TOOLS)[number];
 export declare const EVENT_TOOL_TEXT: {
     readonly a_webhook: "a webhook";
     readonly arguments_argument: "The event's arguments, as an object: see the event's list above";