@pancake-apps/web 0.0.0-snapshot-20260125200133

package/dist/index-BBfZZJWn.d.ts

@@ -0,0 +1,671 @@
+/**
+ * ChatGPT Apps SDK Type Definitions
+ *
+ * These types match the window.openai runtime interface as specified
+ * in the ChatGPT Apps SDK documentation.
+ */
+type Theme = 'light' | 'dark';
+type DisplayMode = 'inline' | 'pip' | 'fullscreen';
+interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface ContentBlock {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+interface CallToolResult<TOutput = unknown> {
+    content: ContentBlock[];
+    structuredContent?: TOutput;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Read-only properties available on window.openai
+ */
+interface OpenAiGlobals {
+    theme: Theme;
+    locale: string;
+    displayMode: DisplayMode;
+    maxHeight: number;
+    safeArea: SafeAreaInsets;
+    view: string;
+    userAgent: string;
+    toolInput: Record<string, unknown> | undefined;
+    toolOutput: unknown | undefined;
+    toolResponseMetadata: Record<string, unknown> | undefined;
+    widgetState: unknown | undefined;
+}
+/**
+ * Methods available on window.openai
+ */
+interface OpenAiMethods {
+    callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
+    sendFollowUpMessage(options: {
+        prompt: string;
+    }): void;
+    uploadFile(file: File): Promise<{
+        fileId: string;
+    }>;
+    getFileDownloadUrl(options: {
+        fileId: string;
+    }): Promise<{
+        url: string;
+    }>;
+    requestDisplayMode(mode: DisplayMode): void;
+    requestModal(options: ModalOptions): Promise<void>;
+    notifyIntrinsicHeight(options: {
+        height: number;
+    }): void;
+    requestClose(): void;
+    openExternal(options: {
+        href: string;
+    }): void;
+    setOpenInAppUrl(options: {
+        href: string;
+    }): void;
+    setWidgetState(state: unknown): void;
+}
+/**
+ * Complete window.openai interface
+ */
+interface OpenAiRuntime extends OpenAiGlobals, OpenAiMethods {
+}
+declare const SET_GLOBALS_EVENT_TYPE: "openai:set_globals";
+interface SetGlobalsEventDetail {
+    globals: OpenAiGlobals;
+    changes: Partial<OpenAiGlobals>;
+}
+interface SetGlobalsEvent extends CustomEvent<SetGlobalsEventDetail> {
+    type: typeof SET_GLOBALS_EVENT_TYPE;
+}
+interface ModalOptions {
+    [key: string]: unknown;
+}
+declare global {
+    interface Window {
+        openai?: OpenAiRuntime;
+    }
+    interface WindowEventMap {
+        [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;
+    }
+}
+
+/**
+ * AppsSdkBridge
+ *
+ * Singleton bridge that wraps window.openai, providing:
+ * - Runtime availability checking
+ * - Method wrappers with proper typing
+ * - Error handling for missing runtime
+ */
+
+declare class AppsSdkBridge {
+    private static instance;
+    /**
+     * Get the singleton bridge instance
+     * @throws Error if window.openai is not available
+     */
+    static getInstance(): AppsSdkBridge;
+    /**
+     * Check if the Apps SDK runtime is available
+     */
+    static isAvailable(): boolean;
+    /**
+     * Reset the singleton (for testing)
+     */
+    static reset(): void;
+    private constructor();
+    /**
+     * Get the raw window.openai runtime
+     */
+    private get runtime();
+    /**
+     * Call an MCP tool
+     */
+    callTool<TInput = Record<string, unknown>, TOutput = unknown>(name: string, args?: TInput): Promise<CallToolResult<TOutput>>;
+    /**
+     * Send a follow-up message to the conversation
+     */
+    sendFollowUpMessage(prompt: string): void;
+    /**
+     * Upload a file and get its ID
+     */
+    uploadFile(file: File): Promise<{
+        fileId: string;
+    }>;
+    /**
+     * Get a temporary download URL for a file
+     */
+    getFileDownloadUrl(fileId: string): Promise<{
+        url: string;
+    }>;
+    /**
+     * Request a change in display mode
+     */
+    requestDisplayMode(mode: DisplayMode): void;
+    /**
+     * Request to show a modal dialog
+     */
+    requestModal(options: ModalOptions): Promise<void>;
+    /**
+     * Notify the host of the widget's intrinsic height
+     */
+    notifyIntrinsicHeight(height: number): void;
+    /**
+     * Request to close/hide the widget
+     */
+    requestClose(): void;
+    /**
+     * Open an external URL in the user's browser
+     */
+    openExternal(href: string): void;
+    /**
+     * Set the "Open in App" URL for fullscreen mode
+     */
+    setOpenInAppUrl(href: string): void;
+    /**
+     * Set the widget state (persisted by host)
+     */
+    setWidgetState<T>(state: T): void;
+}
+/**
+ * Get the bridge instance (convenience function)
+ */
+declare function getBridge(): AppsSdkBridge;
+/**
+ * Check if Apps SDK is available (convenience function)
+ */
+declare function isAppsSdkAvailable(): boolean;
+
+/**
+ * AppsSdkStore
+ *
+ * External store implementation for React 18's useSyncExternalStore.
+ * Listens to openai:set_globals events for reactive updates.
+ */
+
+type Subscriber = () => void;
+type Unsubscribe = () => void;
+declare class AppsSdkStore {
+    private static instance;
+    private subscribers;
+    private globalSubscribers;
+    static getInstance(): AppsSdkStore;
+    static reset(): void;
+    private constructor();
+    private setupEventListener;
+    private cleanup;
+    private handleSetGlobals;
+    /**
+     * Subscribe to changes for specific keys
+     */
+    subscribe(keys: keyof OpenAiGlobals | (keyof OpenAiGlobals)[], callback: Subscriber): Unsubscribe;
+    /**
+     * Subscribe to any change
+     */
+    subscribeAll(callback: Subscriber): Unsubscribe;
+    /**
+     * Get current value of a global property
+     */
+    getSnapshot<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K] | undefined;
+    /**
+     * Get server snapshot (for SSR, returns undefined)
+     */
+    getServerSnapshot<K extends keyof OpenAiGlobals>(_key: K): undefined;
+}
+
+/**
+ * Get the store instance (convenience function)
+ */
+declare function getStore(): AppsSdkStore;
+
+/**
+ * Base hook factory for creating reactive hooks for window.openai properties
+ */
+
+/**
+ * Create a hook that subscribes to a specific window.openai property
+ */
+declare function createOpenAiGlobalHook<K extends keyof OpenAiGlobals>(key: K): () => OpenAiGlobals[K] | undefined;
+/**
+ * Generic hook to access any window.openai property
+ */
+declare function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K] | undefined;
+
+/**
+ * Get the current theme (light or dark)
+ *
+ * @returns Current theme, defaults to 'light' if not available
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const theme = useTheme();
+ *   return <div className={theme === 'dark' ? 'dark' : 'light'}>...</div>;
+ * }
+ * ```
+ */
+declare function useTheme(): Theme;
+
+/**
+ * Get the user's locale setting
+ *
+ * @returns BCP 47 language tag (e.g., 'en-US', 'ja-JP')
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const locale = useLocale();
+ *   const formatter = new Intl.DateTimeFormat(locale);
+ *   return <span>{formatter.format(new Date())}</span>;
+ * }
+ * ```
+ */
+declare function useLocale(): string;
+
+/**
+ * Get the current widget display mode
+ *
+ * @returns Current display mode: 'inline', 'pip', or 'fullscreen'
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const mode = useDisplayMode();
+ *   if (mode === 'fullscreen') {
+ *     return <FullscreenLayout />;
+ *   }
+ *   return <CompactLayout />;
+ * }
+ * ```
+ */
+declare function useDisplayMode(): DisplayMode;
+
+/**
+ * Get the maximum allowed height for the widget
+ *
+ * @returns Maximum height in pixels
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const maxHeight = useMaxHeight();
+ *   return <div style={{ maxHeight }}>...</div>;
+ * }
+ * ```
+ */
+declare function useMaxHeight(): number;
+
+/**
+ * Get safe area insets for devices with notches/rounded corners
+ *
+ * @returns Safe area insets object
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const safeArea = useSafeArea();
+ *   return (
+ *     <div style={{ paddingTop: safeArea.top, paddingBottom: safeArea.bottom }}>
+ *       ...
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSafeArea(): SafeAreaInsets;
+
+/**
+ * Get the view context identifier
+ *
+ * @returns View identifier string or undefined
+ */
+declare function useView(): string | undefined;
+
+/**
+ * Get the user agent string
+ *
+ * Note: Do not rely on this for security decisions.
+ *
+ * @returns User agent string or undefined
+ */
+declare function useUserAgent(): string | undefined;
+
+/**
+ * Get the tool input arguments
+ *
+ * @returns Tool input arguments or undefined if not yet available
+ *
+ * @example
+ * ```tsx
+ * interface SearchInput {
+ *   query: string;
+ *   limit?: number;
+ * }
+ *
+ * function SearchWidget() {
+ *   const input = useToolInput<SearchInput>();
+ *
+ *   if (!input) {
+ *     return <Loading />;
+ *   }
+ *
+ *   return <div>Searching for: {input.query}</div>;
+ * }
+ * ```
+ */
+declare function useToolInput<T = Record<string, unknown>>(): T | undefined;
+
+/**
+ * Get the tool output (structuredContent from tool response)
+ *
+ * This is the concise JSON that both widget and model can access.
+ *
+ * @returns Tool output or undefined if not yet available
+ *
+ * @example
+ * ```tsx
+ * interface SearchOutput {
+ *   results: Array<{ id: string; title: string }>;
+ *   total: number;
+ * }
+ *
+ * function SearchWidget() {
+ *   const output = useToolOutput<SearchOutput>();
+ *
+ *   if (!output) {
+ *     return <Loading />;
+ *   }
+ *
+ *   return (
+ *     <ul>
+ *       {output.results.map(r => <li key={r.id}>{r.title}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useToolOutput<T = unknown>(): T | undefined;
+
+/**
+ * Get the tool response metadata (_meta from tool response)
+ *
+ * This data is only visible to the widget, never sent to the model.
+ * Use for large datasets, sensitive info, or data not needed for model reasoning.
+ *
+ * @returns Tool response metadata or undefined
+ *
+ * @example
+ * ```tsx
+ * interface SearchMetadata {
+ *   fullResultData: Array<FullResult>;
+ *   timing: number;
+ * }
+ *
+ * function SearchWidget() {
+ *   const meta = useToolResponseMetadata<SearchMetadata>();
+ *   // meta.fullResultData has the complete data
+ *   // meta.timing shows how long the search took
+ * }
+ * ```
+ */
+declare function useToolResponseMetadata<T = Record<string, unknown>>(): T | undefined;
+
+/**
+ * Bidirectional sync with host-persisted widget state
+ *
+ * State is scoped to the specific widget instance on a single message.
+ * It persists across page refreshes and conversation reopening.
+ *
+ * @param defaultState - Optional default state if no persisted state exists
+ * @returns Tuple of [state, setState]
+ *
+ * @example
+ * ```tsx
+ * interface EditorState {
+ *   activeTab: string;
+ *   scrollPosition: number;
+ * }
+ *
+ * function Editor() {
+ *   const [state, setState] = useWidgetState<EditorState>({
+ *     activeTab: 'general',
+ *     scrollPosition: 0,
+ *   });
+ *
+ *   const handleTabChange = (tab: string) => {
+ *     setState({ ...state!, activeTab: tab });
+ *   };
+ *
+ *   return <Tabs active={state?.activeTab} onChange={handleTabChange} />;
+ * }
+ * ```
+ */
+declare function useWidgetState<T>(defaultState?: T): readonly [T | undefined, (newState: T) => void];
+
+/**
+ * Call an MCP tool from the widget
+ *
+ * The target tool must have `_meta["openai/widgetAccessible"]: true` set on the server.
+ *
+ * @param name - Tool name to call
+ * @param args - Optional arguments for the tool
+ * @returns Promise resolving to tool result
+ *
+ * @example
+ * ```tsx
+ * const result = await callTool('get_product_details', { productId: '123' });
+ * if (result.isError) {
+ *   console.error('Tool failed:', result.content[0]?.text);
+ * } else {
+ *   console.log('Product:', result.structuredContent);
+ * }
+ * ```
+ */
+declare function callTool<TInput = Record<string, unknown>, TOutput = unknown>(name: string, args?: TInput): Promise<CallToolResult<TOutput>>;
+
+/**
+ * Send a follow-up message to the conversation
+ *
+ * This will post a message authored by the widget into the chat.
+ *
+ * @param prompt - The message text to send
+ *
+ * @example
+ * ```tsx
+ * function ActionButton() {
+ *   const handleClick = () => {
+ *     sendFollowUpMessage('Show me more options like this one');
+ *   };
+ *   return <button onClick={handleClick}>Show more</button>;
+ * }
+ * ```
+ */
+declare function sendFollowUpMessage(prompt: string): void;
+
+/**
+ * Upload a file and get its ID
+ *
+ * Supported formats: PNG, JPEG, WebP
+ *
+ * @param file - File object to upload
+ * @returns Promise resolving to object with fileId
+ *
+ * @example
+ * ```tsx
+ * const input = document.querySelector('input[type="file"]');
+ * const file = input.files[0];
+ * const { fileId } = await uploadFile(file);
+ * ```
+ */
+declare function uploadFile(file: File): Promise<{
+    fileId: string;
+}>;
+
+/**
+ * Get a temporary download URL for a previously uploaded file
+ *
+ * The URL is temporary and will expire.
+ *
+ * @param fileId - ID of the uploaded file
+ * @returns Promise resolving to object with temporary URL
+ *
+ * @example
+ * ```tsx
+ * const { url } = await getFileDownloadUrl('file-abc123');
+ * // Use url before it expires
+ * ```
+ */
+declare function getFileDownloadUrl(fileId: string): Promise<{
+    url: string;
+}>;
+
+/**
+ * Request a change in widget display mode
+ *
+ * Note: The host may deny the request based on user preferences or device constraints.
+ *
+ * @param mode - Desired display mode: 'inline', 'pip', or 'fullscreen'
+ *
+ * @example
+ * ```tsx
+ * function ExpandButton() {
+ *   return (
+ *     <button onClick={() => requestDisplayMode('fullscreen')}>
+ *       Expand
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function requestDisplayMode(mode: DisplayMode): void;
+
+/**
+ * Spawn a modal dialog owned by ChatGPT
+ *
+ * @param options - Modal configuration options
+ * @returns Promise that resolves when modal is closed
+ */
+declare function requestModal(options: ModalOptions): Promise<void>;
+
+/**
+ * Report the widget's intrinsic content height to the host
+ *
+ * Use this to avoid scroll clipping when content size changes dynamically.
+ *
+ * @param height - Content height in pixels
+ *
+ * @example
+ * ```tsx
+ * function DynamicContent({ content }) {
+ *   const ref = useRef<HTMLDivElement>(null);
+ *
+ *   useEffect(() => {
+ *     if (ref.current) {
+ *       notifyIntrinsicHeight(ref.current.scrollHeight);
+ *     }
+ *   }, [content]);
+ *
+ *   return <div ref={ref}>{content}</div>;
+ * }
+ * ```
+ */
+declare function notifyIntrinsicHeight(height: number): void;
+
+/**
+ * Programmatically hide/close the widget
+ *
+ * @example
+ * ```tsx
+ * function CloseButton() {
+ *   return <button onClick={requestClose}>Close</button>;
+ * }
+ * ```
+ */
+declare function requestClose(): void;
+
+/**
+ * Open an external URL in the user's browser
+ *
+ * The URL must be allowed by the widget's CSP `redirect_domains` configuration.
+ *
+ * @param href - URL to open
+ *
+ * @example
+ * ```tsx
+ * function ProductLink({ url, children }) {
+ *   const handleClick = (e) => {
+ *     e.preventDefault();
+ *     openExternal(url);
+ *   };
+ *   return <a href={url} onClick={handleClick}>{children}</a>;
+ * }
+ * ```
+ */
+declare function openExternal(href: string): void;
+
+/**
+ * Set the destination URL for the fullscreen mode's "Open in App" button
+ *
+ * @param href - URL to set for the "Open in App" button
+ */
+declare function setOpenInAppUrl(href: string): void;
+
+/**
+ * @pancake-apps/web/apps-sdk
+ *
+ * Complete SDK for building widgets that run inside ChatGPT.
+ * Wraps the window.openai runtime with React hooks and typed actions.
+ */
+
+type appsSdk_AppsSdkBridge = AppsSdkBridge;
+declare const appsSdk_AppsSdkBridge: typeof AppsSdkBridge;
+type appsSdk_AppsSdkStore = AppsSdkStore;
+declare const appsSdk_AppsSdkStore: typeof AppsSdkStore;
+type appsSdk_CallToolResult<TOutput = unknown> = CallToolResult<TOutput>;
+type appsSdk_ContentBlock = ContentBlock;
+type appsSdk_DisplayMode = DisplayMode;
+type appsSdk_ModalOptions = ModalOptions;
+type appsSdk_OpenAiGlobals = OpenAiGlobals;
+type appsSdk_OpenAiMethods = OpenAiMethods;
+type appsSdk_OpenAiRuntime = OpenAiRuntime;
+declare const appsSdk_SET_GLOBALS_EVENT_TYPE: typeof SET_GLOBALS_EVENT_TYPE;
+type appsSdk_SafeAreaInsets = SafeAreaInsets;
+type appsSdk_SetGlobalsEvent = SetGlobalsEvent;
+type appsSdk_SetGlobalsEventDetail = SetGlobalsEventDetail;
+type appsSdk_Theme = Theme;
+declare const appsSdk_callTool: typeof callTool;
+declare const appsSdk_createOpenAiGlobalHook: typeof createOpenAiGlobalHook;
+declare const appsSdk_getBridge: typeof getBridge;
+declare const appsSdk_getFileDownloadUrl: typeof getFileDownloadUrl;
+declare const appsSdk_getStore: typeof getStore;
+declare const appsSdk_isAppsSdkAvailable: typeof isAppsSdkAvailable;
+declare const appsSdk_notifyIntrinsicHeight: typeof notifyIntrinsicHeight;
+declare const appsSdk_openExternal: typeof openExternal;
+declare const appsSdk_requestClose: typeof requestClose;
+declare const appsSdk_requestDisplayMode: typeof requestDisplayMode;
+declare const appsSdk_requestModal: typeof requestModal;
+declare const appsSdk_sendFollowUpMessage: typeof sendFollowUpMessage;
+declare const appsSdk_setOpenInAppUrl: typeof setOpenInAppUrl;
+declare const appsSdk_uploadFile: typeof uploadFile;
+declare const appsSdk_useDisplayMode: typeof useDisplayMode;
+declare const appsSdk_useLocale: typeof useLocale;
+declare const appsSdk_useMaxHeight: typeof useMaxHeight;
+declare const appsSdk_useOpenAiGlobal: typeof useOpenAiGlobal;
+declare const appsSdk_useSafeArea: typeof useSafeArea;
+declare const appsSdk_useTheme: typeof useTheme;
+declare const appsSdk_useToolInput: typeof useToolInput;
+declare const appsSdk_useToolOutput: typeof useToolOutput;
+declare const appsSdk_useToolResponseMetadata: typeof useToolResponseMetadata;
+declare const appsSdk_useUserAgent: typeof useUserAgent;
+declare const appsSdk_useView: typeof useView;
+declare const appsSdk_useWidgetState: typeof useWidgetState;
+declare namespace appsSdk {
+  export { appsSdk_AppsSdkBridge as AppsSdkBridge, appsSdk_AppsSdkStore as AppsSdkStore, type appsSdk_CallToolResult as CallToolResult, type appsSdk_ContentBlock as ContentBlock, type appsSdk_DisplayMode as DisplayMode, type appsSdk_ModalOptions as ModalOptions, type appsSdk_OpenAiGlobals as OpenAiGlobals, type appsSdk_OpenAiMethods as OpenAiMethods, type appsSdk_OpenAiRuntime as OpenAiRuntime, appsSdk_SET_GLOBALS_EVENT_TYPE as SET_GLOBALS_EVENT_TYPE, type appsSdk_SafeAreaInsets as SafeAreaInsets, type appsSdk_SetGlobalsEvent as SetGlobalsEvent, type appsSdk_SetGlobalsEventDetail as SetGlobalsEventDetail, type appsSdk_Theme as Theme, appsSdk_callTool as callTool, appsSdk_createOpenAiGlobalHook as createOpenAiGlobalHook, appsSdk_getBridge as getBridge, appsSdk_getFileDownloadUrl as getFileDownloadUrl, appsSdk_getStore as getStore, appsSdk_isAppsSdkAvailable as isAppsSdkAvailable, appsSdk_notifyIntrinsicHeight as notifyIntrinsicHeight, appsSdk_openExternal as openExternal, appsSdk_requestClose as requestClose, appsSdk_requestDisplayMode as requestDisplayMode, appsSdk_requestModal as requestModal, appsSdk_sendFollowUpMessage as sendFollowUpMessage, appsSdk_setOpenInAppUrl as setOpenInAppUrl, appsSdk_uploadFile as uploadFile, appsSdk_useDisplayMode as useDisplayMode, appsSdk_useLocale as useLocale, appsSdk_useMaxHeight as useMaxHeight, appsSdk_useOpenAiGlobal as useOpenAiGlobal, appsSdk_useSafeArea as useSafeArea, appsSdk_useTheme as useTheme, appsSdk_useToolInput as useToolInput, appsSdk_useToolOutput as useToolOutput, appsSdk_useToolResponseMetadata as useToolResponseMetadata, appsSdk_useUserAgent as useUserAgent, appsSdk_useView as useView, appsSdk_useWidgetState as useWidgetState };
+}
+
+export { AppsSdkBridge as A, uploadFile as B, type ContentBlock as C, type DisplayMode as D, getFileDownloadUrl as E, requestDisplayMode as F, requestModal as G, notifyIntrinsicHeight as H, requestClose as I, openExternal as J, setOpenInAppUrl as K, type ModalOptions as M, type OpenAiGlobals as O, type SafeAreaInsets as S, type Theme as T, appsSdk as a, type CallToolResult as b, type OpenAiMethods as c, type OpenAiRuntime as d, type SetGlobalsEventDetail as e, type SetGlobalsEvent as f, SET_GLOBALS_EVENT_TYPE as g, getBridge as h, isAppsSdkAvailable as i, AppsSdkStore as j, getStore as k, createOpenAiGlobalHook as l, useTheme as m, useLocale as n, useDisplayMode as o, useMaxHeight as p, useSafeArea as q, useView as r, useUserAgent as s, useToolInput as t, useOpenAiGlobal as u, useToolOutput as v, useToolResponseMetadata as w, useWidgetState as x, callTool as y, sendFollowUpMessage as z };