@pingroom/sdk 0.2.0 → 0.4.0

package/dist/liveStatus.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Live-status streams — the wire contract for driving a Live Activity.
+ *
+ * A stream is keyed by `correlation_id`: the first ping starts a live card on
+ * every room member's lock screen (one alert), further `running` pings move it
+ * silently, and the first `done`/`failed` sends one completion alert and ends
+ * it. See https://pingroom.io/liveactivities.md.
+ *
+ * Three producers speak this contract. This SDK reaches the two machine ones:
+ *   - a room's **incoming webhook** (Pro) — `sendIncomingWebhook()`
+ *   - an **agent credential** — `pr.live.*` (needs `pingroom:live:write`)
+ *
+ * The third is a signed-in person driving a stream from the app composer over
+ * `POST /api/rooms/{inviteCode}/live` with their own Human JWT. It sends this
+ * same body minus `live_status.agent_id` (stripped server-side), so these
+ * builders describe it too — but it is not an agent route and has no client
+ * here.
+ *
+ * Not to be confused with `liveActivity.*` in ./liveActivity.ts, which builds
+ * the frozen *native* `{ attributes, content_state }` push shape for tests and
+ * tooling. These builders produce the `live_status` object you actually send.
+ */
+import type { LiveActivityTemplate } from './liveActivity.js';
+export type LiveStatusState = 'running' | 'done' | 'failed';
+/** Legacy rendering category. Prefer `template`; `alert` selects urgent styling. */
+export type LiveStatusCategory = 'status' | 'steps' | 'alert';
+export interface LiveStatusMetric {
+    label: string;
+    value: string;
+}
+export interface LiveStatusOption {
+    value: string;
+    label: string;
+}
+export interface LiveStatusSide {
+    label: string;
+    value: string;
+    iconSvg?: string;
+}
+/**
+ * The `live_status` object. Only `state` is required; every other field is read
+ * by the template you selected.
+ *
+ * `template` and `steps` are fixed at stream creation — a later ping cannot
+ * re-template a running card. Content set at creation is sticky, so a sparse
+ * update carrying just `progress` keeps rendering the full template. The
+ * terminal leg is sticky too: `{ state: 'done' }` alone keeps the scoreboard,
+ * metrics grid, deadline and accent on the final frame.
+ */
+export interface LiveStatus {
+    state: LiveStatusState;
+    template?: LiveActivityTemplate;
+    category?: LiveStatusCategory;
+    message?: string;
+    /** 0..1 — the progress bar / Dynamic Island gauge. */
+    progress?: number;
+    /** 2–8 labels. Required on the first ping of a `steps` stream; immutable after. */
+    steps?: string[];
+    /** Index into `steps`; the only mutable steps field. */
+    current_step?: number;
+    /** Up to 3 counters, for the `metrics` template. */
+    metrics?: LiveStatusMetric[];
+    /** Epoch seconds the `countdown` template counts down to. */
+    deadline_at?: number;
+    /** Epoch seconds; renders a live ETA on `status`/`progress`. */
+    eta_at?: number;
+    /** The ask, for the `question` template. */
+    prompt?: string;
+    /** Up to 4 choices, for the `question` template. */
+    options?: LiveStatusOption[];
+    left?: LiveStatusSide;
+    right?: LiveStatusSide;
+    center?: string;
+    /** Hex `#rrggbb` — a semantic accent for one frame (e.g. deadline red). */
+    accent_override?: string;
+    agent_id?: string;
+}
+/** The full body of a live-status ping. */
+export interface LiveStatusPing {
+    correlation_id: string;
+    live_status: LiveStatus;
+    title?: string;
+    /** Quick-action slot 1–4 supplying the icon and sound. */
+    action?: number;
+    data?: Record<string, unknown>;
+    requires_ack?: boolean;
+    ack_timeout_seconds?: number;
+}
+export interface LiveStatusResult {
+    notification_id: string;
+    correlation_id: string;
+    /** `started` on creation, then `running` / `done` / `failed`. */
+    state: string;
+    idempotent: boolean;
+    action_state?: unknown;
+}
+/**
+ * The read-back shape from `GET .../live/{correlationId}`.
+ *
+ * EVERY stored `live_status` field is returned, not a step/progress subset — a
+ * `matchup` / `metrics` / `countdown` / `question` stream would otherwise be
+ * unresumable after a producer restart. Fields you never set come back as
+ * `null` rather than being omitted, so read them defensively.
+ *
+ * The server-side ownership stamps (`_webhook` / `_agent` / `_user`) are
+ * deliberately NOT returned — they are the authorization record, not client
+ * state.
+ */
+export interface LiveStatusSnapshot {
+    notification_id: string;
+    correlation_id: string;
+    state: string | null;
+    progress: number | null;
+    message: string | null;
+    category: LiveStatusCategory | null;
+    template: LiveActivityTemplate | null;
+    agent_id: string | null;
+    accent_override: string | null;
+    eta_at: number | null;
+    deadline_at: number | null;
+    metrics: LiveStatusMetric[] | null;
+    prompt: string | null;
+    options: LiveStatusOption[] | null;
+    left: LiveStatusSide | null;
+    right: LiveStatusSide | null;
+    center: string | null;
+    steps: string[] | null;
+    current_step: number | null;
+    action_state?: unknown;
+    updated_at: string | null;
+}
+type Rest = Omit<LiveStatusPing, 'correlation_id' | 'live_status'>;
+/**
+ * Builders for the common stream shapes. Each returns a body you can hand to
+ * `pr.live.push()` or `sendIncomingWebhook()`.
+ */
+export declare const liveStatus: {
+    /** Default template: a title line plus a status dot, with optional progress. */
+    status(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** A segmented step tracker. `steps` is required on the first ping. */
+    steps(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** A determinate progress bar with an optional live ETA. */
+    progress(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** Up to 3 labelled counters. */
+    metrics(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** A large live timer counting down to `deadline_at`. */
+    countdown(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** A prompt with up to 4 options shown on the lock screen. */
+    question(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** Two sides plus a center score/clock. */
+    matchup(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /**
+     * An urgent stream, delivered time-sensitive from the start so it breaks
+     * through Focus.
+     *
+     * This is a `category`, not a `template`: `alert` has no template equivalent,
+     * and it is the only way to start time-sensitive WITHOUT also setting
+     * `requires_ack` (which demands somebody tap). Fixed at creation, like
+     * `template`.
+     */
+    alert(correlationId: string, live: Omit<LiveStatus, "template" | "category">, rest?: Rest): LiveStatusPing;
+    /** Finish a stream. The one alert your stream earns. */
+    done(correlationId: string, message?: string, rest?: Rest): LiveStatusPing;
+    /** Finish a stream unsuccessfully. */
+    failed(correlationId: string, message?: string, rest?: Rest): LiveStatusPing;
+};
+export {};
+//# sourceMappingURL=liveStatus.d.ts.map

package/dist/liveStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveStatus.d.ts","sourceRoot":"","sources":["../src/liveStatus.ts"],"names":[],"mappings":"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"}

package/dist/liveStatus.js

@@ -0,0 +1,82 @@
+/**
+ * Live-status streams — the wire contract for driving a Live Activity.
+ *
+ * A stream is keyed by `correlation_id`: the first ping starts a live card on
+ * every room member's lock screen (one alert), further `running` pings move it
+ * silently, and the first `done`/`failed` sends one completion alert and ends
+ * it. See https://pingroom.io/liveactivities.md.
+ *
+ * Three producers speak this contract. This SDK reaches the two machine ones:
+ *   - a room's **incoming webhook** (Pro) — `sendIncomingWebhook()`
+ *   - an **agent credential** — `pr.live.*` (needs `pingroom:live:write`)
+ *
+ * The third is a signed-in person driving a stream from the app composer over
+ * `POST /api/rooms/{inviteCode}/live` with their own Human JWT. It sends this
+ * same body minus `live_status.agent_id` (stripped server-side), so these
+ * builders describe it too — but it is not an agent route and has no client
+ * here.
+ *
+ * Not to be confused with `liveActivity.*` in ./liveActivity.ts, which builds
+ * the frozen *native* `{ attributes, content_state }` push shape for tests and
+ * tooling. These builders produce the `live_status` object you actually send.
+ */
+const ping = (correlationId, live, rest = {}) => ({
+    correlation_id: correlationId,
+    live_status: live,
+    ...rest,
+});
+/**
+ * Builders for the common stream shapes. Each returns a body you can hand to
+ * `pr.live.push()` or `sendIncomingWebhook()`.
+ */
+export const liveStatus = {
+    /** Default template: a title line plus a status dot, with optional progress. */
+    status(correlationId, live, rest) {
+        return ping(correlationId, { template: 'status', ...live }, rest);
+    },
+    /** A segmented step tracker. `steps` is required on the first ping. */
+    steps(correlationId, live, rest) {
+        return ping(correlationId, { template: 'steps', ...live }, rest);
+    },
+    /** A determinate progress bar with an optional live ETA. */
+    progress(correlationId, live, rest) {
+        return ping(correlationId, { template: 'progress', ...live }, rest);
+    },
+    /** Up to 3 labelled counters. */
+    metrics(correlationId, live, rest) {
+        return ping(correlationId, { template: 'metrics', ...live }, rest);
+    },
+    /** A large live timer counting down to `deadline_at`. */
+    countdown(correlationId, live, rest) {
+        return ping(correlationId, { template: 'countdown', ...live }, rest);
+    },
+    /** A prompt with up to 4 options shown on the lock screen. */
+    question(correlationId, live, rest) {
+        return ping(correlationId, { template: 'question', ...live }, rest);
+    },
+    /** Two sides plus a center score/clock. */
+    matchup(correlationId, live, rest) {
+        return ping(correlationId, { template: 'matchup', ...live }, rest);
+    },
+    /**
+     * An urgent stream, delivered time-sensitive from the start so it breaks
+     * through Focus.
+     *
+     * This is a `category`, not a `template`: `alert` has no template equivalent,
+     * and it is the only way to start time-sensitive WITHOUT also setting
+     * `requires_ack` (which demands somebody tap). Fixed at creation, like
+     * `template`.
+     */
+    alert(correlationId, live, rest) {
+        return ping(correlationId, { category: 'alert', ...live }, rest);
+    },
+    /** Finish a stream. The one alert your stream earns. */
+    done(correlationId, message, rest) {
+        return ping(correlationId, { state: 'done', ...(message ? { message } : {}) }, rest);
+    },
+    /** Finish a stream unsuccessfully. */
+    failed(correlationId, message, rest) {
+        return ping(correlationId, { state: 'failed', ...(message ? { message } : {}) }, rest);
+    },
+};
+//# sourceMappingURL=liveStatus.js.map

package/dist/liveStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveStatus.js","sourceRoot":"","sources":["../src/liveStatus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA2HH,MAAM,IAAI,GAAG,CAAC,aAAqB,EAAE,IAAgB,EAAE,OAAa,EAAE,EAAkB,EAAE,CAAC,CAAC;IAC1F,cAAc,EAAE,aAAa;IAC7B,WAAW,EAAE,IAAI;IACjB,GAAG,IAAI;CACR,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,gFAAgF;IAChF,MAAM,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC3E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACpE,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC1E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACnE,CAAC;IAED,4DAA4D;IAC5D,QAAQ,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC7E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,iCAAiC;IACjC,OAAO,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC5E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC;IAED,yDAAyD;IACzD,SAAS,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC9E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC;IAED,8DAA8D;IAC9D,QAAQ,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC7E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,2CAA2C;IAC3C,OAAO,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC5E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,aAAqB,EAAE,IAA+C,EAAE,IAAW;QACvF,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACnE,CAAC;IAED,wDAAwD;IACxD,IAAI,CAAC,aAAqB,EAAE,OAAgB,EAAE,IAAW;QACvD,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACvF,CAAC;IAED,sCAAsC;IACtC,MAAM,CAAC,aAAqB,EAAE,OAAgB,EAAE,IAAW;QACzD,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACzF,CAAC;CACF,CAAC"}

package/dist/mcp.d.ts

@@ -19,6 +19,16 @@ export interface McpToolResult {
     isError?: boolean;
     [key: string]: unknown;
 }
+export interface McpInitializeResult {
+    protocolVersion: string;
+    capabilities: Record<string, unknown>;
+    serverInfo: {
+        name: string;
+        version: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
 /**
  * Thin client for the PingRoom MCP endpoint (`POST /api/agent/mcp`,
  * JSON-RPC 2.0). Tools are scope-filtered server-side, so `listTools()` returns
@@ -28,13 +38,25 @@ export declare class McpClient {
     private readonly http;
     private readonly path;
     private nextId;
+    private initialization;
+    private initializeResult;
+    private protocolVersion;
     constructor(http: HttpClient, path?: string);
     /** Raw JSON-RPC call. Resolves the `result`; throws PingRoomError on a JSON-RPC `error`. */
     call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
-    initialize(params?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Perform the MCP initialize handshake once, including the required
+     * `notifications/initialized` notification. Safe to call more than once.
+     */
+    initialize(params?: Record<string, unknown>): Promise<McpInitializeResult>;
+    /** Alias for initialize(), useful when treating this helper as a connection. */
+    connect(params?: Record<string, unknown>): Promise<McpInitializeResult>;
     listTools(): Promise<{
         tools: McpTool[];
     }>;
     callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+    private performInitialize;
+    private notify;
+    private headers;
 }
 //# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,SAAS;IAIlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,MAAM,CAAK;gBAGA,IAAI,EAAE,UAAU,EAChB,IAAI,SAAmB;IAG1C,4FAA4F;IACtF,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAgBrF,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAW9D,SAAS,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAI1C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAGnF"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACtE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,SAAS;IAOlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPvB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,gBAAgB,CAAoC;IAC5D,OAAO,CAAC,eAAe,CAAuB;gBAG3B,IAAI,EAAE,UAAU,EAChB,IAAI,SAAmB;IAG1C,4FAA4F;IACtF,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAgBrF;;;OAGG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAc1E,gFAAgF;IAChF,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIjE,SAAS,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAK1C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC;YAK1E,iBAAiB;YAsBjB,MAAM;IAQpB,OAAO,CAAC,OAAO;CAMhB"}

package/dist/mcp.js

@@ -9,6 +9,9 @@ export class McpClient {
     http;
     path;
     nextId = 1;
+    initialization = null;
+    initializeResult = null;
+    protocolVersion = null;
     constructor(http, path = '/api/agent/mcp') {
         this.http = http;
         this.path = path;
@@ -19,7 +22,7 @@ export class McpClient {
         const envelope = { jsonrpc: '2.0', id, method, ...(params ? { params } : {}) };
         const res = await this.http.request('POST', this.path, {
             body: envelope,
-            headers: { Accept: 'application/json, text/event-stream' },
+            headers: this.headers(),
         });
         if (res && res.error) {
             throw new PingRoomError(`MCP error ${res.error.code}: ${res.error.message}`, {
@@ -29,18 +32,63 @@ export class McpClient {
         }
         return res?.result;
     }
+    /**
+     * Perform the MCP initialize handshake once, including the required
+     * `notifications/initialized` notification. Safe to call more than once.
+     */
     initialize(params) {
-        return this.call('initialize', params ?? {
+        if (this.initializeResult) {
+            return Promise.resolve(this.initializeResult);
+        }
+        if (this.initialization) {
+            return this.initialization;
+        }
+        this.initialization = this.performInitialize(params).finally(() => {
+            this.initialization = null;
+        });
+        return this.initialization;
+    }
+    /** Alias for initialize(), useful when treating this helper as a connection. */
+    connect(params) {
+        return this.initialize(params);
+    }
+    async listTools() {
+        await this.initialize();
+        return this.call('tools/list');
+    }
+    async callTool(name, args = {}) {
+        await this.initialize();
+        return this.call('tools/call', { name, arguments: args });
+    }
+    async performInitialize(params) {
+        const result = await this.call('initialize', params ?? {
             protocolVersion: '2025-06-18',
             capabilities: {},
             clientInfo: { name: 'pingroom-sdk', version: VERSION },
         });
+        if (!result || typeof result.protocolVersion !== 'string') {
+            throw new PingRoomError('MCP initialize response did not include a protocol version.', {
+                code: 'mcp_invalid_initialize',
+                body: result,
+            });
+        }
+        this.protocolVersion = result.protocolVersion;
+        await this.notify('notifications/initialized');
+        this.initializeResult = result;
+        return result;
     }
-    listTools() {
-        return this.call('tools/list');
+    async notify(method, params) {
+        const envelope = { jsonrpc: '2.0', method, ...(params ? { params } : {}) };
+        await this.http.request('POST', this.path, {
+            body: envelope,
+            headers: this.headers(),
+        });
     }
-    callTool(name, args = {}) {
-        return this.call('tools/call', { name, arguments: args });
+    headers() {
+        return {
+            Accept: 'application/json, text/event-stream',
+            ...(this.protocolVersion ? { 'MCP-Protocol-Version': this.protocolVersion } : {}),
+        };
     }
 }
 //# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAqBvC;;;;GAIG;AACH,MAAM,OAAO,SAAS;IAID;IACA;IAJX,MAAM,GAAG,CAAC,CAAC;IAEnB,YACmB,IAAgB,EAChB,OAAO,gBAAgB;QADvB,SAAI,GAAJ,IAAI,CAAY;QAChB,SAAI,GAAJ,IAAI,CAAmB;IACvC,CAAC;IAEJ,4FAA4F;IAC5F,KAAK,CAAC,IAAI,CAAc,MAAc,EAAE,MAAgC;QACtE,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAC/E,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAuC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE;YAC3F,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,EAAE,MAAM,EAAE,qCAAqC,EAAE;SAC3D,CAAC,CAAC;QACH,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,IAAI,aAAa,CAAC,aAAa,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE;gBAC3E,IAAI,EAAE,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE;gBAC7B,IAAI,EAAE,GAAG,CAAC,KAAK;aAChB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,GAAG,EAAE,MAAW,CAAC;IAC1B,CAAC;IAED,UAAU,CAAC,MAAgC;QACzC,OAAO,IAAI,CAAC,IAAI,CACd,YAAY,EACZ,MAAM,IAAI;YACR,eAAe,EAAE,YAAY;YAC7B,YAAY,EAAE,EAAE;YAChB,UAAU,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE;SACvD,CACF,CAAC;IACJ,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,IAAI,CAAuB,YAAY,CAAC,CAAC;IACvD,CAAC;IAED,QAAQ,CAAC,IAAY,EAAE,OAAgC,EAAE;QACvD,OAAO,IAAI,CAAC,IAAI,CAAgB,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3E,CAAC;CACF"}
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}