@waniwani/sdk 0.11.11 → 0.11.13

package/dist/legacy/mcp/react.d.ts

@@ -0,0 +1,573 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ContentBlock, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import React$1, { ReactNode, SetStateAction } from 'react';
+
+/**
+ * Initializes & patches Next.js functionality so an app can run as a
+ * widget inside a cross-origin iframe. Used by every MCP widget host —
+ * ChatGPT's sandbox, the embed's `/api/mcp/chat/resource` proxy, and any
+ * future host that renders the widget on a domain other than its own
+ * `baseUrl`.
+ *
+ * See `applyIframePatches` for the patch behavior.
+ *
+ * More background on the ChatGPT case:
+ * https://vercel.com/blog/running-next-js-inside-chatgpt-a-deep-dive-into-native-app-integration
+ *
+ * @deprecated Legacy MCP-widget-in-host stack (used with `createResource`/`createTool`).
+ *   Preserved for back-compat; will move to `@waniwani/sdk/legacy/react` in a future minor
+ *   release.
+ */
+declare function InitializeNextJsInIframe({ baseUrl, passthroughOrigins, }: {
+    baseUrl: string;
+    /**
+     * Origins whose fetches should skip the relative same-origin → baseUrl
+     * rewrite. Only needed for relative-URL calls that resolve to an
+     * origin you do not want forwarded to `baseUrl` — absolute URLs are
+     * never rewritten regardless of this list.
+     */
+    passthroughOrigins?: string[];
+}): react_jsx_runtime.JSX.Element;
+
+interface DevControlsProps {
+    defaultProps?: Record<string, unknown>;
+    widgetPaths?: string[];
+}
+/**
+ * @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 DevModeProvider({ defaultProps, widgetPaths, children, }: DevControlsProps & {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * 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;
+    }
+}
+
+declare let mockState: Omit<OpenAIGlobals, "setWidgetState">;
+declare function initializeMockOpenAI(initialToolOutput?: Record<string, unknown>): void;
+declare function updateMockGlobal<K extends keyof OpenAIGlobals>(key: K, value: OpenAIGlobals[K]): void;
+declare function getMockState(): typeof mockState;
+declare function updateMockToolOutput(props: Record<string, unknown>): void;
+declare function updateMockDisplayMode(mode: DisplayMode): void;
+declare function updateMockTheme(theme: Theme): void;
+
+type ModelContextContentBlock = ContentBlock;
+type ModelContextUpdate = {
+    content?: ModelContextContentBlock[];
+    structuredContent?: Record<string, unknown>;
+};
+
+/**
+ * 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;
+}
+
+/**
+ * Get a function to call other tools.
+ * Works on both OpenAI widgets and MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns A function to call tools with their name and arguments
+ */
+declare function useCallTool(): (name: string, args: Record<string, unknown>) => Promise<ToolCallResult>;
+
+/**
+ * Get the current display mode.
+ * Works on both OpenAI widgets and MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns The current display mode ("pip" | "inline" | "fullscreen")
+ */
+declare function useDisplayMode(): DisplayMode;
+
+/** Return type of the useFlowAction hook */
+type FlowActionResult<T> = {
+    /** Current widget data from structuredContent. */
+    data: T | null;
+};
+/**
+ * Hook for reading flow widget data from structuredContent.
+ * Lightweight wrapper over `useToolOutput` — will be extended
+ * with flow-specific features in the future.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ *
+ * @example
+ * ```tsx
+ * const { data } = useFlowAction<{ plans: string[] }>();
+ * if (!data) return null;
+ * return <PricingTable plans={data.plans} />;
+ * ```
+ */
+declare function useFlowAction<T extends Record<string, unknown>>(): FlowActionResult<T>;
+
+/**
+ * Check if running in ChatGPT app (OpenAI-only).
+ * Returns false on MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns Whether the widget is running in ChatGPT app
+ */
+declare function useIsChatGptApp(): boolean;
+
+/**
+ * Get the current locale.
+ * Works on both OpenAI widgets and MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns The current locale string (e.g., "en-US")
+ */
+declare function useLocale(): string;
+
+/**
+ * Get the maximum height available for the widget (OpenAI-only).
+ * Useful for responsive layouts that need to adapt to container constraints.
+ * Returns null on MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns The maximum height in pixels, or null if not available
+ */
+declare function useMaxHeight(): number | null;
+
+/**
+ * Get a function to open external URLs.
+ * Works on both OpenAI widgets and MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns A function that opens external URLs
+ */
+declare function useOpenExternal(): (url: string) => void;
+
+/**
+ * Get a function to request display mode changes.
+ * On MCP Apps, this may be a no-op depending on host support.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns A function to request a specific display mode
+ */
+declare function useRequestDisplayMode(): (mode: DisplayMode) => Promise<DisplayMode>;
+
+/**
+ * Get safe area insets (OpenAI-only).
+ * Useful for ensuring UI elements don't get hidden behind the chat input.
+ * Returns null on MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns The safe area insets, or null if not available
+ */
+declare function useSafeArea(): SafeArea | null;
+
+interface SendFollowUpOptions {
+    modelContext?: ModelContextUpdate | null;
+}
+/**
+ * Get a function to send follow-up messages to the AI.
+ * Works on both OpenAI widgets and MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns A function that sends a follow-up message
+ */
+declare function useSendFollowUp(): (prompt: string, options?: SendFollowUpOptions) => void;
+
+/**
+ * Get the current theme.
+ * Works on both OpenAI widgets and MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns The current theme ("light" | "dark")
+ */
+declare function useTheme(): Theme;
+
+/**
+ * Get the tool output (structured content returned by the tool handler).
+ * Works on both OpenAI widgets and MCP Apps.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns The tool output or null
+ */
+declare function useToolOutput<T extends Record<string, unknown>>(): T | null;
+
+/**
+ * Get tool response metadata.
+ * Contains host/tool metadata (for example identifiers like
+ * `openai/widgetSessionId` and custom tool `_meta` fields).
+ * Returns null when the host does not provide metadata.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @returns The tool response metadata object or null if not available
+ */
+declare function useToolResponseMetadata(): UnknownObject | null;
+
+/**
+ * Get a function to update hidden model context for the next assistant turn.
+ * Uses the MCP Apps `ui/update-model-context` request when available.
+ *
+ * @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 useUpdateModelContext(): (context: ModelContextUpdate) => Promise<void>;
+
+/**
+ * Provider props
+ */
+interface WidgetProviderProps {
+    children: ReactNode;
+    /** Optional loading component while connecting */
+    loading?: ReactNode;
+    /** Optional error component */
+    onError?: (error: Error) => ReactNode;
+}
+/**
+ * Provider component that initializes the correct widget client based on platform.
+ * Wrap your widget component with this provider.
+ *
+ * @deprecated Part of the legacy MCP-widget-in-host stack (used with `createResource` /
+ *   `createTool`). Preserved for back-compat; will move to `@waniwani/sdk/legacy/react` in
+ *   a future minor release. For new code, use `createFlow` from `@waniwani/sdk/mcp` and
+ *   `useWaniwani` from `@waniwani/sdk/mcp/react`.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <WidgetProvider loading={<Spinner />}>
+ *       <MyWidget />
+ *     </WidgetProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function WidgetProvider({ children, loading, onError, }: WidgetProviderProps): React$1.FunctionComponentElement<React$1.FragmentProps> | React$1.FunctionComponentElement<React$1.ProviderProps<UnifiedWidgetClient | null>>;
+/**
+ * Keys that can be selected from the widget client.
+ */
+type WidgetKey = "toolOutput" | "theme" | "displayMode" | "locale" | "safeArea" | "maxHeight" | "toolResponseMetadata" | "widgetState";
+/**
+ * Value types for each widget key.
+ */
+type WidgetKeyValues = {
+    toolOutput: Record<string, unknown> | null;
+    theme: Theme;
+    displayMode: DisplayMode;
+    locale: string;
+    safeArea: SafeArea | null;
+    maxHeight: number | null;
+    toolResponseMetadata: UnknownObject | null;
+    widgetState: UnknownObject | null;
+};
+/**
+ * Get the unified widget client instance.
+ * Must be used within a WidgetProvider.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ *
+ * @example
+ * ```tsx
+ * // Full client for actions
+ * const client = useWidgetClient();
+ * client.callTool("foo", {});
+ *
+ * // Key selector for reactive values
+ * const toolOutput = useWidgetClient("toolOutput");
+ * const theme = useWidgetClient("theme");
+ * ```
+ */
+declare function useWidgetClient(): UnifiedWidgetClient;
+declare function useWidgetClient<K extends WidgetKey>(key: K): WidgetKeyValues[K];
+
+/**
+ * Widget state that persists across widget lifecycles (OpenAI-only).
+ * State is synchronized with the ChatGPT parent window and survives widget minimize/restore.
+ * On MCP Apps, returns [null, no-op].
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ * @param defaultState - Initial state value or function to compute it
+ * @returns A tuple of [state, setState] similar to useState
+ */
+declare function useWidgetState<T extends UnknownObject>(defaultState?: T | (() => T | null) | null): readonly [T | null, (state: SetStateAction<T | null>) => void];
+
+/**
+ * Default loading fallback for legacy MCP widgets.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
+ */
+declare const LoadingWidget: () => react_jsx_runtime.JSX.Element;
+
+/**
+ * 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;
+
+export { DevModeProvider, type DeviceType, type DisplayMode, type FlowActionResult, type HostContext, InitializeNextJsInIframe, LoadingWidget, type ModelContextContentBlock, type ModelContextUpdate, type SafeArea, type SafeAreaInsets, type SendFollowUpOptions, type Theme, type ToolCallResult, type ToolResult, type UnifiedWidgetClient, type UnknownObject, type UserAgent, type WidgetPlatform, WidgetProvider, detectPlatform, getMockState, initializeMockOpenAI, isMCPApps, isOpenAI, updateMockDisplayMode, updateMockGlobal, updateMockTheme, updateMockToolOutput, useCallTool, useDisplayMode, useFlowAction, useIsChatGptApp, useLocale, useMaxHeight, useOpenExternal, useRequestDisplayMode, useSafeArea, useSendFollowUp, useTheme, useToolOutput, useToolResponseMetadata, useUpdateModelContext, useWidgetClient, useWidgetState };