@waniwani/sdk 0.11.13 → 0.11.15

package/dist/legacy/index.d.ts

@@ -3,6 +3,10 @@ export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { ZodRawShapeCompat, ShapeOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 export { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ContentBlock, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import React$1, { ReactNode, SetStateAction } from 'react';
+import { UIMessage } from 'ai';
 
 type WidgetCSP = {
     /** Domains permitted for fetch/XHR network requests */
@@ -210,6 +214,58 @@ interface LegacyTrackEvent extends TrackingContext {
  * Public track input accepted by `client.track()`.
  */
 type TrackInput = TrackEvent | LegacyTrackEvent;
+interface TrackingConfig {
+    /** Events API V2 endpoint path. */
+    endpointPath?: string;
+    /** Periodic flush interval for buffered events. */
+    flushIntervalMs?: number;
+    /** Max events per HTTP batch send. */
+    maxBatchSize?: number;
+    /** Max in-memory buffer size before oldest items are dropped. */
+    maxBufferSize?: number;
+    /** Number of retries for retryable failures. */
+    maxRetries?: number;
+    /** Retry backoff base delay. */
+    retryBaseDelayMs?: number;
+    /** Retry backoff max delay. */
+    retryMaxDelayMs?: number;
+    /** Default shutdown timeout when none is provided. */
+    shutdownTimeoutMs?: number;
+}
+interface TrackingShutdownOptions {
+    timeoutMs?: number;
+}
+interface TrackingShutdownResult {
+    timedOut: boolean;
+    pendingEvents: number;
+}
+/**
+ * Tracking module methods for WaniWaniClient.
+ */
+interface TrackingClient {
+    /**
+     * Send a one-shot identify event for a user.
+     * userId can be any string: an email, an internal ID, etc.
+     */
+    identify: (userId: string, properties?: Record<string, unknown>, meta?: Record<string, unknown>) => Promise<{
+        eventId: string;
+    }>;
+    /**
+     * Track an event using modern or legacy input shape.
+     * Returns a deterministic event id immediately after enqueue.
+     */
+    track: (event: TrackInput) => Promise<{
+        eventId: string;
+    }>;
+    /**
+     * Flush all currently buffered events.
+     */
+    flush: () => Promise<void>;
+    /**
+     * Flush and stop the transport.
+     */
+    shutdown: (options?: TrackingShutdownOptions) => Promise<TrackingShutdownResult>;
+}
 
 /**
  * A request-scoped WaniWani client with meta pre-attached.
@@ -332,4 +388,737 @@ declare function createTool<TInput extends z.ZodRawShape>(config: ToolConfig<TIn
  */
 declare function registerTools(server: McpServer, tools: RegisteredTool[]): Promise<void>;
 
-export { type RegisteredResource, type RegisteredTool, type ResourceConfig, type ToolConfig, type ToolHandler, type ToolHandlerContext, type ToolToolCallback, type WidgetCSP, createResource, createTool, registerTools };
+/**
+ * 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;
+
+/**
+ * WaniWani SDK Client
+ *
+ * Extends with each module:
+ * - TrackingClient: track(), flush(), shutdown()
+ *
+ * Pass this client to framework adapters:
+ * - `toNextJsHandler(wani, { ... })` for Next.js route handlers
+ */
+interface WaniWaniClient extends TrackingClient {
+    /** @internal Resolved config — used by framework adapters */
+    readonly _config: InternalConfig;
+    /** Knowledge base client for ingestion, search, and source listing */
+    readonly kb: KbClient;
+}
+interface InternalConfig {
+    apiUrl: string;
+    apiKey: string | undefined;
+    tracking: Required<TrackingConfig>;
+}
+
+/**
+ * Server-side geolocation extracted from platform headers (Vercel, Cloudflare).
+ * All fields are optional — in local dev, no headers are present.
+ */
+interface GeoLocation {
+    city?: string;
+    country?: string;
+    countryRegion?: string;
+    latitude?: string;
+    longitude?: string;
+    timezone?: string;
+    ip?: string;
+}
+
+/** Client-side visitor context sent in the request body */
+interface ClientVisitorContext {
+    timezone: string;
+    language: string;
+    languages: string[];
+    deviceType: "mobile" | "tablet" | "desktop";
+    referrer: string;
+    visitorId: string;
+}
+/** Combined visitor context: server geo + client context */
+interface VisitorMeta {
+    geo: GeoLocation;
+    client: ClientVisitorContext | null;
+}
+interface BeforeRequestContext {
+    /** The conversation messages from the client */
+    messages: UIMessage[];
+    /** Session identifier for conversation continuity */
+    sessionId?: string;
+    /** Hidden widget-provided model context for the next assistant turn */
+    modelContext?: ModelContextUpdate;
+    /** The original HTTP Request object */
+    request: Request;
+    /** Server-extracted geo location + client-provided visitor context */
+    visitor: VisitorMeta;
+}
+type BeforeRequestResult = {
+    /** Override messages (e.g., filtered, augmented) */
+    messages?: UIMessage[];
+    /** Override the system prompt for this request */
+    systemPrompt?: string;
+    /** Override sessionId */
+    sessionId?: string;
+    /** Override hidden widget-provided model context */
+    modelContext?: ModelContextUpdate;
+};
+interface WebSearchConfig {
+    /** Restrict web search results to these domains */
+    includeDomains?: string[];
+    /** Exclude these domains from web search results */
+    excludeDomains?: string[];
+}
+interface ChatOptions {
+    /**
+     * System prompt for the assistant.
+     * Can be overridden per-request via `beforeRequest`.
+     */
+    systemPrompt?: string;
+    /**
+     * Maximum number of tool call steps. Defaults to 5.
+     */
+    maxSteps?: number;
+    /**
+     * Hook called before each request is forwarded to the WaniWani API.
+     * - Return void to use defaults.
+     * - Return an object to override messages, systemPrompt, or sessionId.
+     * - Throw to reject the request (the error message is returned as JSON).
+     */
+    beforeRequest?: (context: BeforeRequestContext) => Promise<BeforeRequestResult | undefined> | BeforeRequestResult | undefined;
+    /**
+     * Override the MCP server URL directly, bypassing config resolution.
+     * Useful for development/testing when pointing to a local MCP server.
+     */
+    mcpServerUrl?: string;
+    /**
+     * Enable web search as an additional tool alongside MCP tools.
+     * Pass `true` to enable with defaults, or a config object to restrict domains.
+     */
+    webSearch?: boolean | WebSearchConfig;
+}
+
+interface NextJsHandlerOptions {
+    /** Chat handler configuration */
+    chat?: ChatOptions;
+    /**
+     * Identifies this chatbar instance in analytics.
+     * Use a descriptive name like "hamilton-support" or "pricing-page".
+     * Shows up as `source` on tracked events.
+     */
+    source: string;
+    /**
+     * Enable verbose debug logging for all handler steps.
+     * Logs request details, response codes, resolved URLs, and caught errors.
+     */
+    debug?: boolean;
+}
+interface NextJsHandlerResult {
+    /** GET handler: routes sub-paths (e.g. /resource for MCP widget content) */
+    GET: (request: Request) => Promise<Response>;
+    /** POST handler: proxies chat messages to the WaniWani API */
+    POST: (request: Request) => Promise<Response>;
+    /** PATCH handler: routes updates (e.g. /scenarios/:id) */
+    PATCH: (request: Request) => Promise<Response>;
+    /** OPTIONS handler: CORS preflight */
+    OPTIONS: (request: Request) => Response;
+}
+
+/**
+ * Create Next.js route handlers from a WaniWani client.
+ *
+ * Returns `{ GET, POST }` for use with catch-all routes.
+ * Mount at `app/api/waniwani/[[...path]]/route.ts`:
+ *
+ * - `POST /api/waniwani`              → chat (proxied to WaniWani API)
+ * - `GET  /api/waniwani/resource?uri=…` → MCP resource content
+ *
+ * @deprecated The chat-server catch-all adapters are being phased out. The chat widget
+ *   will talk directly to `app.waniwani.ai` in a future release, removing the need for a
+ *   self-hosted BFF. This export is preserved for back-compat with existing customer MCPs
+ *   but is no longer documented; it will move to `@waniwani/sdk/legacy/next-js` in a future
+ *   minor release.
+ *
+ * @example
+ * ```typescript
+ * // app/api/waniwani/[[...path]]/route.ts
+ * import { waniwani } from "@waniwani/sdk";
+ * import { toNextJsHandler } from "@waniwani/sdk/next-js";
+ *
+ * const wani = waniwani();
+ *
+ * export const { GET, POST } = toNextJsHandler(wani, {
+ *   chat: {
+ *     systemPrompt: "You are a helpful assistant.",
+ *     mcpServerUrl: process.env.MCP_SERVER_URL!,
+ *   },
+ * });
+ * ```
+ */
+declare function toNextJsHandler(client: WaniWaniClient, options: NextJsHandlerOptions): NextJsHandlerResult;
+
+export { DevModeProvider, type DeviceType, type DisplayMode, type FlowActionResult, type HostContext, InitializeNextJsInIframe, LoadingWidget, type ModelContextContentBlock, type ModelContextUpdate, type NextJsHandlerOptions, type NextJsHandlerResult, type RegisteredResource, type RegisteredTool, type ResourceConfig, type SafeArea, type SafeAreaInsets, type SendFollowUpOptions, type Theme, type ToolCallResult, type ToolConfig, type ToolHandler, type ToolHandlerContext, type ToolResult, type ToolToolCallback, type UnifiedWidgetClient, type UnknownObject, type UserAgent, type WidgetCSP, type WidgetPlatform, WidgetProvider, createResource, createTool, detectPlatform, getMockState, initializeMockOpenAI, isMCPApps, isOpenAI, registerTools, toNextJsHandler, updateMockDisplayMode, updateMockGlobal, updateMockTheme, updateMockToolOutput, useCallTool, useDisplayMode, useFlowAction, useIsChatGptApp, useLocale, useMaxHeight, useOpenExternal, useRequestDisplayMode, useSafeArea, useSendFollowUp, useTheme, useToolOutput, useToolResponseMetadata, useUpdateModelContext, useWidgetClient, useWidgetState };