@waniwani/sdk 0.19.9 → 0.20.0

package/dist/mcp/index.d.ts

@@ -1,9 +1,9 @@
-import { ZodRawShapeCompat, ShapeOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 export { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import { ToolAnnotations, ServerRequest, ServerNotification, CallToolResult, ContentBlock } from '@modelcontextprotocol/sdk/types.js';
+import { ToolAnnotations, ServerRequest, ServerNotification, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 interface SearchResult {
@@ -409,106 +409,6 @@ interface ScopedWaniWaniClient {
  */
 declare function extractScopedClient(extra: unknown): ScopedWaniWaniClient | undefined;
 
-type WidgetCSP = {
-    /** Domains permitted for fetch/XHR network requests */
-    connect_domains?: string[];
-    /** Domains for static assets (images, fonts, scripts, styles) */
-    resource_domains?: string[];
-    /** Origins allowed for iframe embeds (triggers stricter app review) */
-    frame_domains?: string[];
-    /** Origins that can receive openExternal redirects without safe-link modal */
-    redirect_domains?: string[];
-};
-type ResourceConfig = {
-    /** Unique identifier for the resource */
-    id: string;
-    /** Display title */
-    title: string;
-    /** UI description (describes WHAT the resource displays) */
-    description?: string;
-    /** Base URL for fetching the HTML */
-    baseUrl: string;
-    /** Path to the HTML file (relative to baseUrl) */
-    htmlPath: string;
-    /** Domain for OpenAI security context */
-    widgetDomain: string;
-    /** Whether widget prefers border (defaults to true) */
-    prefersBorder?: boolean;
-    /** When true, the iframe height auto-adapts to its content */
-    autoHeight?: boolean;
-    /** Content Security Policy configuration */
-    widgetCSP?: WidgetCSP;
-};
-type RegisteredResource = {
-    readonly id: string;
-    readonly title: string;
-    readonly description: string | undefined;
-    /** OpenAI URI: ui://widgets/apps-sdk/{id}.html */
-    readonly openaiUri: string;
-    /** MCP URI: ui://widgets/ext-apps/{id}.html */
-    readonly mcpUri: string;
-    readonly autoHeight: boolean | undefined;
-    /** Register this resource on an McpServer */
-    register: (server: McpServer) => Promise<void>;
-};
-
-type ToolHandlerContext = {
-    /** Raw MCP request extra data (includes _meta for session extraction) */
-    extra?: {
-        _meta?: Record<string, unknown>;
-    };
-    /** Session-scoped Waniwani client — available when the server is wrapped with withWaniwani() */
-    waniwani?: ScopedWaniWaniClient;
-};
-type ToolConfig<TInput extends ZodRawShapeCompat> = {
-    /** The resource (HTML template) this tool renders. When present, tool returns structuredContent + widget _meta. */
-    resource?: RegisteredResource;
-    /** Tool identifier. Defaults to resource.id when resource is present, required otherwise. */
-    id?: string;
-    /** Display title. Defaults to resource.title when resource is present, required otherwise. */
-    title?: string;
-    /** Action-oriented description for the tool (tells the model WHEN to use it) */
-    description: string;
-    /** UI component description (describes WHAT the widget displays). Falls back to description. Only relevant when resource is present. */
-    widgetDescription?: string;
-    /** Input schema using zod */
-    inputSchema: TInput;
-    /** Optional loading message (defaults to "Loading..."). Only relevant when resource is present. */
-    invoking?: string;
-    /** Optional loaded message (defaults to "Loaded"). Only relevant when resource is present. */
-    invoked?: string;
-    /**
-     * When a widget calls this tool via `tools/call`, should the host auto-inject
-     * the tool's text result into the next follow-up message if the widget does
-     * not send one itself. Defaults to true. Set false for helper tools whose
-     * result is consumed programmatically by the widget.
-     */
-    autoInjectResultText?: boolean;
-    /**
-     * Annotations describe the tool's potential impact. Passed through to
-     * `registerTool` as-is.
-     *
-     * Includes MCP's `title` — a human-readable name for the tool. Claude's
-     * Connectors Directory requires it on every tool and flags the server at
-     * submission without it; the top-level `title` does not satisfy that.
-     */
-    annotations?: ToolAnnotations;
-};
-type ToolHandler<TInput extends ZodRawShapeCompat> = (input: ShapeOutput<TInput>, context: ToolHandlerContext) => Promise<{
-    /** Text content to return */
-    text: string;
-    /** Structured data returned as MCP `structuredContent`. */
-    data?: Record<string, unknown>;
-}>;
-type ToolToolCallback<TInput extends ZodRawShapeCompat> = ToolCallback<TInput>;
-type RegisteredTool = {
-    id: string;
-    title: string;
-    description: string;
-    /** Register the tool on the server */
-    register: (server: McpServer) => Promise<void>;
-};
-
 /**
  * Compact, JSON-serializable schema fragment for a single state field.
  * Emitted inside interrupt/widget responses so the LLM gets focused, just-in-time
@@ -642,6 +542,20 @@ declare const flowOutputSchema: {
 };
 type FlowOutputSchema = typeof flowOutputSchema;
 
+/**
+ * A tool object `showWidget` can render, as opposed to a bare tool name.
+ *
+ * Structural on purpose: anything carrying these four members satisfies it,
+ * so a server that registers its tools by hand keeps working without
+ * importing a factory from this package.
+ */
+type RegisteredTool = {
+    id: string;
+    title: string;
+    description: string;
+    /** Register the tool on the server */
+    register: (server: McpServer) => Promise<void>;
+};
 declare const START: "__start__";
 declare const END: "__end__";
 declare const INTERRUPT: unique symbol;
@@ -1326,343 +1240,4 @@ type WithWaniwaniOptions = {
  */
 declare function withWaniwani(server: McpServer, options?: WithWaniwaniOptions): Promise<McpServer>;
 
-/**
- * Widget platform types
- */
-type WidgetPlatform = "openai" | "mcp-apps";
-/**
- * Detects which platform the widget is running on.
- *
- * OpenAI injects a global `window.openai` object.
- * MCP Apps runs in a sandboxed iframe and uses postMessage.
- *
- * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
- *   `@waniwani/sdk/legacy/react` in a future minor release.
- */
-declare function detectPlatform(): WidgetPlatform;
-/**
- * Check if running on OpenAI platform.
- *
- * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
- *   `@waniwani/sdk/legacy/react` in a future minor release.
- */
-declare function isOpenAI(): boolean;
-/**
- * Check if running on MCP Apps platform.
- *
- * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
- *   `@waniwani/sdk/legacy/react` in a future minor release.
- */
-declare function isMCPApps(): boolean;
-
-type ModelContextContentBlock = ContentBlock;
-type ModelContextUpdate = {
-    content?: ModelContextContentBlock[];
-    structuredContent?: Record<string, unknown>;
-};
-
-/**
- * Source: https://github.com/openai/openai-apps-sdk-examples/tree/main/src
- */
-type OpenAIGlobals<ToolInput = UnknownObject, ToolOutput = UnknownObject, ToolResponseMetadata = UnknownObject, WidgetState = UnknownObject> = {
-    theme: Theme;
-    userAgent: UserAgent;
-    locale: string;
-    maxHeight: number;
-    displayMode: DisplayMode;
-    safeArea: SafeArea;
-    toolInput: ToolInput;
-    toolOutput: ToolOutput | null;
-    toolResponseMetadata: ToolResponseMetadata | null;
-    widgetState: WidgetState | null;
-    setWidgetState: (state: WidgetState) => Promise<void>;
-};
-type API = {
-    callTool: CallTool;
-    sendFollowUpMessage: (args: {
-        prompt: string;
-    }) => Promise<void>;
-    openExternal(payload: {
-        href: string;
-    }): void;
-    requestDisplayMode: RequestDisplayMode;
-};
-type UnknownObject = Record<string, unknown>;
-type Theme = "light" | "dark";
-type SafeAreaInsets = {
-    top: number;
-    bottom: number;
-    left: number;
-    right: number;
-};
-type SafeArea = {
-    insets: SafeAreaInsets;
-};
-type DeviceType = "mobile" | "tablet" | "desktop" | "unknown";
-type UserAgent = {
-    device: {
-        type: DeviceType;
-    };
-    capabilities: {
-        hover: boolean;
-        touch: boolean;
-    };
-};
-/** Display mode */
-type DisplayMode = "pip" | "inline" | "fullscreen";
-type RequestDisplayMode = (args: {
-    mode: DisplayMode;
-}) => Promise<{
-    /**
-     * The granted display mode. The host may reject the request.
-     * For mobile, PiP is always coerced to fullscreen.
-     */
-    mode: DisplayMode;
-}>;
-type CallToolResponse = {
-    result: string;
-};
-/** Calling APIs */
-type CallTool = (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
-/** Extra events */
-declare const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
-declare class SetGlobalsEvent extends CustomEvent<{
-    globals: Partial<OpenAIGlobals>;
-}> {
-    constructor(detail: {
-        globals: Partial<OpenAIGlobals>;
-    });
-}
-/**
- * Global oai object injected by the web sandbox for communicating with chatgpt host page.
- */
-declare global {
-    interface Window {
-        openai: API & OpenAIGlobals;
-        innerBaseUrl: string;
-    }
-    interface WindowEventMap {
-        [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;
-    }
-}
-
-/**
- * Result from calling a tool
- */
-type ToolCallResult = CallToolResult;
-/**
- * Tool result notification (what the host pushes to the widget)
- */
-type ToolResult = CallToolResult;
-/**
- * Host context - all values available from the host.
- */
-type HostContext = {
-    theme: Theme;
-    locale: string;
-    displayMode: DisplayMode;
-    maxHeight: number | null;
-    safeArea: SafeArea | null;
-    toolOutput: UnknownObject | null;
-    toolResponseMetadata: UnknownObject | null;
-    widgetState: UnknownObject | null;
-};
-/**
- * Unified widget client interface that works on both OpenAI and MCP Apps.
- *
- * Platform-specific behavior:
- * - Display mode: OpenAI-only. MCP Apps returns "inline" and requestDisplayMode is a no-op.
- * - Follow-up messages: Unified API, different underlying implementations.
- */
-interface UnifiedWidgetClient {
-    /**
-     * Connect to the host. Must be called before using other methods.
-     * On OpenAI, this is a no-op (already connected via window.openai).
-     * On MCP Apps, this establishes the postMessage connection.
-     */
-    connect(): Promise<void>;
-    /**
-     * Close the connection to the host and clean up resources.
-     * On OpenAI, this is a no-op.
-     * On MCP Apps, this closes the transport and removes event listeners.
-     */
-    close(): Promise<void>;
-    /**
-     * Get the tool output (structured content returned by the tool handler).
-     * This is the main data source for widget rendering.
-     */
-    getToolOutput<T = Record<string, unknown>>(): T | null;
-    /**
-     * Register a callback for when tool results are received.
-     * On OpenAI, this subscribes to toolOutput changes.
-     * On MCP Apps, this sets app.ontoolresult.
-     */
-    onToolResult(callback: (result: ToolResult) => void): () => void;
-    /**
-     * Call another tool on the server.
-     */
-    callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
-    /**
-     * Open an external URL.
-     * On OpenAI: openai.openExternal({ href })
-     * On MCP Apps: app.sendOpenLink(url)
-     */
-    openExternal(url: string): void;
-    /**
-     * Send a follow-up message to the AI.
-     * On OpenAI: openai.sendFollowUpMessage({ prompt })
-     * On MCP Apps: app.sendMessages([{ role: 'user', content: { type: 'text', text: prompt } }])
-     */
-    sendFollowUp(prompt: string): void | Promise<void>;
-    /**
-     * Update hidden model context for the next assistant turn.
-     * On MCP Apps this uses the standard `ui/update-model-context` request.
-     * On other hosts this may fall back to best-effort behavior.
-     */
-    updateModelContext(context: ModelContextUpdate): Promise<void> | void;
-    /**
-     * Get the current theme.
-     */
-    getTheme(): Theme;
-    /**
-     * Subscribe to theme changes.
-     */
-    onThemeChange(callback: (theme: Theme) => void): () => void;
-    /**
-     * Get the current locale.
-     */
-    getLocale(): string;
-    /**
-     * Get the current display mode.
-     * OpenAI-only: returns "pip" | "inline" | "fullscreen"
-     * MCP Apps: always returns "inline"
-     */
-    getDisplayMode(): DisplayMode;
-    /**
-     * Request a display mode change.
-     * OpenAI-only: requests the mode from the host.
-     * MCP Apps: no-op (returns current mode).
-     */
-    requestDisplayMode(mode: DisplayMode): Promise<DisplayMode>;
-    /**
-     * Subscribe to display mode changes.
-     * OpenAI-only: subscribes to displayMode changes.
-     * MCP Apps: callback is never called.
-     */
-    onDisplayModeChange(callback: (mode: DisplayMode) => void): () => void;
-    /**
-     * Get the safe area insets.
-     * OpenAI-only: returns insets from window.openai.safeArea.
-     * MCP Apps: returns null.
-     */
-    getSafeArea(): SafeArea | null;
-    /**
-     * Subscribe to safe area changes.
-     * OpenAI-only: subscribes to safeArea changes.
-     * MCP Apps: callback is never called.
-     */
-    onSafeAreaChange(callback: (safeArea: SafeArea | null) => void): () => void;
-    /**
-     * Get the max height constraint.
-     * OpenAI-only: returns maxHeight from window.openai.maxHeight.
-     * MCP Apps: returns null.
-     */
-    getMaxHeight(): number | null;
-    /**
-     * Subscribe to max height changes.
-     * OpenAI-only: subscribes to maxHeight changes.
-     * MCP Apps: callback is never called.
-     */
-    onMaxHeightChange(callback: (maxHeight: number | null) => void): () => void;
-    /**
-     * Get the tool response metadata.
-     * OpenAI: returns metadata from window.openai.toolResponseMetadata.
-     * MCP Apps: returns `_meta` from the latest `ui/notifications/tool-result`, if provided by host.
-     */
-    getToolResponseMetadata(): UnknownObject | null;
-    /**
-     * Subscribe to tool response metadata changes.
-     * OpenAI: subscribes to toolResponseMetadata changes.
-     * MCP Apps: fires when tool result `_meta` changes.
-     */
-    onToolResponseMetadataChange(callback: (metadata: UnknownObject | null) => void): () => void;
-    /**
-     * Get the widget state.
-     * OpenAI-only: returns state from window.openai.widgetState.
-     * MCP Apps: returns null.
-     */
-    getWidgetState(): UnknownObject | null;
-    /**
-     * Subscribe to widget state changes.
-     * OpenAI-only: subscribes to widgetState changes.
-     * MCP Apps: callback is never called.
-     */
-    onWidgetStateChange(callback: (state: UnknownObject | null) => void): () => void;
-}
-
-/**
- * Creates a reusable UI resource (HTML template) that can be attached
- * to tools or flow nodes.
- *
- * @deprecated Prefer `createFlow` with `showWidget` from `@waniwani/sdk/mcp` for new code.
- *   `createResource` is preserved for back-compat with existing customer MCPs but is no longer
- *   documented; it will move to `@waniwani/sdk/legacy` in a future minor release.
- *
- * @example
- * ```ts
- * const pricingUI = createResource({
- *   id: "pricing_table",
- *   title: "Pricing Table",
- *   baseUrl: "https://my-app.com",
- *   htmlPath: "/widgets/pricing",
- *   widgetDomain: "my-app.com",
- * });
- *
- * await pricingUI.register(server);
- * ```
- */
-declare function createResource(config: ResourceConfig): RegisteredResource;
-
-/**
- * Creates an MCP tool with minimal boilerplate.
- *
- * When `handler()` returns `data`, the tool includes it as MCP `structuredContent`.
- * When `config.resource` is provided, the tool also returns widget metadata.
- *
- * @deprecated Prefer `createFlow` from `@waniwani/sdk/mcp` for new code. `createTool`
- *   is preserved for back-compat with existing customer MCPs but is no longer documented;
- *   it will move to `@waniwani/sdk/legacy` in a future minor release.
- *
- * @example
- * ```ts
- * // Widget tool (with resource)
- * const pricingTool = createTool({
- *   resource: pricingUI,
- *   description: "Show pricing comparison",
- *   inputSchema: { postalCode: z.string() },
- * }, async ({ postalCode }) => ({
- *   text: "Pricing loaded",
- *   data: { postalCode, prices: [] },
- * }));
- *
- * // Plain tool (no resource)
- * const searchTool = createTool({
- *   id: "search",
- *   title: "Search",
- *   description: "Search the knowledge base",
- *   inputSchema: { query: z.string() },
- * }, async ({ query }) => ({
- *   text: `Results for "${query}"`,
- * }));
- * ```
- */
-declare function createTool<TInput extends z.ZodRawShape>(config: ToolConfig<TInput>, handler: ToolHandler<TInput>): RegisteredTool;
-/**
- * Registers multiple tools on the server.
- *
- * @deprecated Prefer `createFlow` + `.register()` for new code. Preserved for back-compat
- *   with existing customer MCPs; will move to `@waniwani/sdk/legacy` in a future minor release.
- */
-declare function registerTools(server: McpServer, tools: RegisteredTool[]): Promise<void>;
-
-export { type AddNodeConfig, type ConditionFn, END, type FlowConfig, type FlowTestResult, type HostContext, type InferFlowState, type InterruptSignal, type KvStore, type KvStoreSetOptions, MemoryKvStore, type NodeContext, type NodeHandler, type RegisteredFlow, type RegisteredResource, type RegisteredTool, type ResourceConfig, SCOPED_CLIENT_KEY, START, type ScopedWaniWaniClient, StateGraph, type ToolCallResult, type ToolConfig, type ToolHandler, type ToolHandlerContext, type ToolResult, type ToolToolCallback, type TrackingRouteOptions, type TypedInterrupt, type TypedShowWidget, type UnifiedWidgetClient, WaniwaniKvStore, type WidgetCSP, type WidgetPlatform, type WidgetSignal, type WithWaniwaniOptions, createFlow, createFlowTestHarness, createResource, createTool, createTrackingRoute, detectPlatform, extractScopedClient, isMCPApps, isOpenAI, redacted, registerTools, withWaniwani };
+export { type AddNodeConfig, type ConditionFn, END, type FlowConfig, type FlowTestResult, type InferFlowState, type InterruptSignal, type KvStore, type KvStoreSetOptions, MemoryKvStore, type NodeContext, type NodeHandler, type RegisteredFlow, type RegisteredTool, SCOPED_CLIENT_KEY, START, type ScopedWaniWaniClient, StateGraph, type TrackingRouteOptions, type TypedInterrupt, type TypedShowWidget, WaniwaniKvStore, type WidgetSignal, type WithWaniwaniOptions, createFlow, createFlowTestHarness, createTrackingRoute, extractScopedClient, redacted, withWaniwani };