mcp-app-studio 0.3.2

package/dist/index.d.ts

@@ -0,0 +1,508 @@
+import { Platform, ExtendedBridge, HostContext, HostCapabilities, ToolResult, DisplayMode, ContentBlock, FeatureKey } from './core/index.js';
+export { AudioContentBlock, CHATGPT_CAPABILITIES, ChatMessage, ContainerDimensions, ContentBlockAnnotations, ContentBlockIcon, HostBridge, HostContextChangedCallback, HostStyles, ImageContentBlock, MCP_CAPABILITIES, ResourceContentBlock, ResourceLinkContentBlock, TeardownCallback, TextContentBlock, Theme, ToolCancelledCallback, ToolInputCallback, ToolInputPartialCallback, ToolResultCallback, hasFeature, imageBlock, textBlock } from './core/index.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { A as AppCapabilities } from './bridge-BOSEqpaS.js';
+import '@modelcontextprotocol/ext-apps';
+
+/**
+ * Detection result with detailed information about what was checked.
+ */
+interface DetectionResult {
+    /** The detected platform */
+    platform: Platform;
+    /** What marker was found (if any) */
+    detectedBy: string | null;
+    /** All markers that were checked */
+    checks: {
+        windowOpenai: boolean;
+        mcpUrlParam: boolean;
+        mcpWindowProp: boolean;
+        mcpDataAttr: boolean;
+    };
+}
+/**
+ * Detects the current platform with detailed results.
+ * Useful for debugging platform detection issues.
+ *
+ * @returns Detection result with platform and diagnostic info
+ *
+ * @example
+ * ```ts
+ * const result = detectPlatformDetailed();
+ * console.log('Platform:', result.platform);
+ * console.log('Detected by:', result.detectedBy);
+ * console.log('Checks:', result.checks);
+ * ```
+ */
+declare function detectPlatformDetailed(): DetectionResult;
+/**
+ * Detects the current platform the widget is running on.
+ *
+ * Detection priority:
+ * 1. `window.openai` exists → ChatGPT
+ * 2. URL has `?mcp-host` param → MCP
+ * 3. `window.__MCP_HOST__` exists → MCP
+ * 4. iframe has `data-mcp-host` attribute → MCP
+ * 5. None of the above → unknown
+ *
+ * **Debugging tip:** Set `window.__CHATGPT_APP_DEBUG__ = true` before
+ * loading your widget to see detailed detection logs in the console.
+ *
+ * @returns The detected platform: "chatgpt", "mcp", or "unknown"
+ *
+ * @example
+ * ```ts
+ * const platform = detectPlatform();
+ * if (platform === 'unknown') {
+ *   console.log('Running in development mode or unsupported host');
+ * }
+ * ```
+ */
+declare function detectPlatform(): Platform;
+/**
+ * Returns true if running inside ChatGPT.
+ *
+ * @example
+ * ```ts
+ * if (isChatGPT()) {
+ *   // Use ChatGPT-specific features
+ * }
+ * ```
+ */
+declare function isChatGPT(): boolean;
+/**
+ * Returns true if running inside an MCP host (e.g., Claude Desktop).
+ *
+ * @example
+ * ```ts
+ * if (isMCP()) {
+ *   // Use MCP-specific features
+ * }
+ * ```
+ */
+declare function isMCP(): boolean;
+/**
+ * Enable debug mode for platform detection.
+ * Logs detailed information about what markers are being checked.
+ *
+ * @example
+ * ```ts
+ * import { enableDebugMode } from 'mcp-app-studio';
+ *
+ * // Enable before your app initializes
+ * enableDebugMode();
+ *
+ * // Now detection will log to console
+ * const platform = detectPlatform();
+ * ```
+ */
+declare function enableDebugMode(): void;
+/**
+ * Disable debug mode for platform detection.
+ */
+declare function disableDebugMode(): void;
+
+interface UniversalProviderProps {
+    children: ReactNode;
+    appInfo?: {
+        name: string;
+        version: string;
+    };
+    appCapabilities?: AppCapabilities;
+}
+declare function UniversalProvider({ children, appInfo, appCapabilities, }: UniversalProviderProps): react_jsx_runtime.JSX.Element | null;
+declare function useUniversalBridge(): ExtendedBridge | null;
+declare function usePlatform(): Platform;
+
+/**
+ * Returns the current host context with environment information.
+ * Updates automatically when the host context changes.
+ *
+ * @returns The host context object, or null if not connected
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const context = useHostContext();
+ *
+ *   if (!context) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Theme: {context.theme}</p>
+ *       <p>Locale: {context.locale}</p>
+ *       <p>Display mode: {context.displayMode}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useHostContext(): HostContext | null;
+/**
+ * Returns the current color theme ("light" or "dark").
+ * Defaults to "light" if theme is not available.
+ *
+ * @returns Current theme
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const theme = useTheme();
+ *
+ *   return (
+ *     <div className={theme === 'dark' ? 'bg-gray-900 text-white' : 'bg-white text-black'}>
+ *       Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useTheme(): "light" | "dark";
+/**
+ * Returns the capabilities supported by the current host platform.
+ * Use this to conditionally enable features based on platform support.
+ *
+ * @returns Host capabilities object, or null if not connected
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const capabilities = useCapabilities();
+ *
+ *   return (
+ *     <div>
+ *       {capabilities?.widgetState && (
+ *         <button>Save State (ChatGPT only)</button>
+ *       )}
+ *       {capabilities?.modelContext && (
+ *         <button>Update Context (MCP only)</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useCapabilities(): HostCapabilities | null;
+/**
+ * Returns the input arguments passed to the tool that invoked this widget.
+ * Generic type parameter allows you to specify the expected input shape.
+ *
+ * @typeParam T - The expected shape of the tool input
+ * @returns Tool input object, or null if not yet received
+ *
+ * @example
+ * ```tsx
+ * interface SearchInput {
+ *   query: string;
+ *   limit?: number;
+ * }
+ *
+ * function SearchWidget() {
+ *   const input = useToolInput<SearchInput>();
+ *
+ *   if (!input) return <div>Waiting for search query...</div>;
+ *
+ *   return <SearchResults query={input.query} limit={input.limit ?? 10} />;
+ * }
+ * ```
+ */
+declare function useToolInput<T = Record<string, unknown>>(): T | null;
+/**
+ * Returns partial tool input as it's being streamed (MCP only).
+ * Useful for showing real-time feedback as the user types.
+ *
+ * **Platform support:** MCP only. Returns null on ChatGPT.
+ *
+ * @typeParam T - The expected shape of the tool input
+ * @returns Partial tool input, or null
+ *
+ * @example
+ * ```tsx
+ * function StreamingInput() {
+ *   const partial = useToolInputPartial<{ query: string }>();
+ *   const final = useToolInput<{ query: string }>();
+ *
+ *   // Show partial input with typing indicator
+ *   if (partial && !final) {
+ *     return <div className="opacity-50">{partial.query}...</div>;
+ *   }
+ *
+ *   return <div>{final?.query}</div>;
+ * }
+ * ```
+ */
+declare function useToolInputPartial<T = Record<string, unknown>>(): T | null;
+/**
+ * Returns the result from a tool call made by the widget.
+ * Updates when tool calls complete.
+ *
+ * @returns Tool result object, or null if no result yet
+ *
+ * @example
+ * ```tsx
+ * function ToolResultDisplay() {
+ *   const result = useToolResult();
+ *
+ *   if (!result) return null;
+ *
+ *   if (result.isError) {
+ *     return <div className="text-red-500">Error: {result.content?.[0]?.text}</div>;
+ *   }
+ *
+ *   return <div>{JSON.stringify(result.structuredContent)}</div>;
+ * }
+ * ```
+ */
+declare function useToolResult(): ToolResult | null;
+/**
+ * Returns the current display mode and a function to request a mode change.
+ * Display mode controls how the widget is presented (inline, fullscreen, or pip).
+ *
+ * @returns Tuple of [currentMode, setMode]
+ *
+ * @example
+ * ```tsx
+ * function ExpandableWidget() {
+ *   const [mode, setMode] = useDisplayMode();
+ *
+ *   return (
+ *     <div>
+ *       <p>Current mode: {mode}</p>
+ *       {mode === 'inline' && (
+ *         <button onClick={() => setMode('fullscreen')}>
+ *           Expand to Fullscreen
+ *         </button>
+ *       )}
+ *       {mode === 'fullscreen' && (
+ *         <button onClick={() => setMode('inline')}>
+ *           Collapse
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useDisplayMode(): [
+    DisplayMode,
+    (mode: DisplayMode) => Promise<void>
+];
+/**
+ * Returns a function to call tools registered with the host.
+ * Tools allow your widget to perform actions and get data from the AI.
+ *
+ * @returns Async function to call tools
+ * @throws Error if bridge is not connected
+ *
+ * @example
+ * ```tsx
+ * function SearchWidget() {
+ *   const callTool = useCallTool();
+ *   const [results, setResults] = useState(null);
+ *   const [loading, setLoading] = useState(false);
+ *
+ *   const handleSearch = async (query: string) => {
+ *     setLoading(true);
+ *     try {
+ *       const result = await callTool('search', { query, limit: 10 });
+ *       if (result.isError) {
+ *         console.error('Search failed');
+ *       } else {
+ *         setResults(result.structuredContent);
+ *       }
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   };
+ *
+ *   return <SearchUI onSearch={handleSearch} results={results} loading={loading} />;
+ * }
+ * ```
+ */
+declare function useCallTool(): (name: string, args: Record<string, unknown>) => Promise<ToolResult>;
+/**
+ * Returns a function to open links in the user's browser.
+ * This is the recommended way to open external URLs from your widget.
+ *
+ * @returns Async function to open links
+ * @throws Error if bridge is not connected
+ *
+ * @example
+ * ```tsx
+ * function LinkButton({ url, label }: { url: string; label: string }) {
+ *   const openLink = useOpenLink();
+ *
+ *   return (
+ *     <button onClick={() => openLink(url)}>
+ *       {label} ↗
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useOpenLink(): (url: string) => Promise<void>;
+/**
+ * Returns a function to send a message to the conversation.
+ * Useful for suggesting follow-up prompts or triggering new interactions.
+ *
+ * @returns Async function to send messages
+ * @throws Error if bridge is not connected or sendMessage not supported
+ *
+ * @example
+ * ```tsx
+ * function SuggestionChips() {
+ *   const sendMessage = useSendMessage();
+ *
+ *   const suggestions = ['Tell me more', 'Show examples', 'Explain in detail'];
+ *
+ *   return (
+ *     <div className="flex gap-2">
+ *       {suggestions.map(text => (
+ *         <button key={text} onClick={() => sendMessage(text)}>
+ *           {text}
+ *         </button>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSendMessage(): (text: string) => Promise<void>;
+/**
+ * Returns a function to update the model's context (MCP only).
+ * Use this to provide additional context to the AI model.
+ *
+ * **Platform support:** MCP only. Logs a warning on ChatGPT.
+ *
+ * @returns Async function to update model context
+ *
+ * @example
+ * ```tsx
+ * function DataViewer({ data }: { data: object }) {
+ *   const updateContext = useUpdateModelContext();
+ *   const platform = usePlatform();
+ *
+ *   useEffect(() => {
+ *     if (platform === 'mcp') {
+ *       updateContext({
+ *         structuredContent: { currentData: data }
+ *       });
+ *     }
+ *   }, [data, platform, updateContext]);
+ *
+ *   return <pre>{JSON.stringify(data, null, 2)}</pre>;
+ * }
+ * ```
+ */
+declare function useUpdateModelContext(): (ctx: {
+    content?: ContentBlock[];
+    structuredContent?: Record<string, unknown>;
+}) => Promise<void>;
+/**
+ * Returns persisted widget state and a setter (ChatGPT only).
+ * State is preserved across page refreshes and conversation turns.
+ *
+ * **Platform support:** ChatGPT only. Logs a warning on MCP.
+ *
+ * @typeParam T - The shape of your widget state
+ * @returns Tuple of [state, setState]
+ *
+ * @example
+ * ```tsx
+ * interface MapState {
+ *   center: { lat: number; lng: number };
+ *   zoom: number;
+ *   selectedMarker: string | null;
+ * }
+ *
+ * function MapWidget() {
+ *   const [state, setState] = useWidgetState<MapState>();
+ *
+ *   const handleZoom = (zoom: number) => {
+ *     setState(prev => prev ? { ...prev, zoom } : { center: { lat: 0, lng: 0 }, zoom, selectedMarker: null });
+ *   };
+ *
+ *   return (
+ *     <Map
+ *       center={state?.center ?? { lat: 0, lng: 0 }}
+ *       zoom={state?.zoom ?? 10}
+ *       onZoomChange={handleZoom}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function useWidgetState<T = Record<string, unknown>>(): [
+    T | null,
+    (state: T | null) => void
+];
+/**
+ * Returns a function for structured logging (MCP only).
+ * Logs are sent to the MCP host for debugging and monitoring.
+ *
+ * **Platform support:** MCP only. Falls back to console.log on other platforms.
+ *
+ * @returns Log function that accepts level and message
+ *
+ * @example
+ * ```tsx
+ * function DataProcessor() {
+ *   const log = useLog();
+ *
+ *   const processData = async (data: unknown) => {
+ *     log('info', 'Starting data processing');
+ *     try {
+ *       // Process data...
+ *       log('debug', `Processed ${data.length} items`);
+ *     } catch (error) {
+ *       log('error', `Processing failed: ${error.message}`);
+ *     }
+ *   };
+ *
+ *   return <button onClick={() => processData(someData)}>Process</button>;
+ * }
+ * ```
+ */
+declare function useLog(): (level: "debug" | "info" | "warning" | "error", data: string) => void;
+/**
+ * Check if a specific feature is available on the current platform.
+ * This is a convenient wrapper around `useCapabilities()` for single feature checks.
+ *
+ * @param feature - The feature key to check
+ * @returns Whether the feature is available
+ *
+ * @example
+ * ```tsx
+ * function ConditionalFeatures() {
+ *   const hasWidgetState = useFeature('widgetState');
+ *   const hasModelContext = useFeature('modelContext');
+ *
+ *   return (
+ *     <div>
+ *       {hasWidgetState && <StatePersistence />}
+ *       {hasModelContext && <ContextUpdater />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Combine with usePlatform for platform-specific UI
+ * function PlatformAwareWidget() {
+ *   const platform = usePlatform();
+ *   const hasFileUpload = useFeature('fileUpload');
+ *
+ *   return (
+ *     <div>
+ *       <p>Running on: {platform}</p>
+ *       {hasFileUpload ? <FileUploader /> : <p>File upload not available</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useFeature(feature: FeatureKey): boolean;
+
+export { ContentBlock, type DetectionResult, DisplayMode, ExtendedBridge, FeatureKey, HostCapabilities, HostContext, Platform, ToolResult, UniversalProvider, type UniversalProviderProps, detectPlatform, detectPlatformDetailed, disableDebugMode, enableDebugMode, isChatGPT, isMCP, useCallTool, useCapabilities, useDisplayMode, useFeature, useHostContext, useLog, useOpenLink, usePlatform, useSendMessage, useTheme, useToolInput, useToolInputPartial, useToolResult, useUniversalBridge, useUpdateModelContext, useWidgetState };