@creature-ai/sdk 0.1.1

package/dist/core/index.d.ts

@@ -0,0 +1,215 @@
+import { g as StateListener, f as HostClientEvents, e as HostClientState, H as HostClient, d as HostClientConfig, T as ToolResult, W as WidgetState, L as LogLevel, E as Environment, a as AppSessionState, b as AppSessionListener } from '../types-DcoqlK46.js';
+export { A as AppSessionOptions, c as HostContext, S as StructuredWidgetState } from '../types-DcoqlK46.js';
+export { applyDocumentTheme, applyHostFonts, applyHostStyleVariables, getDocumentTheme } from '@modelcontextprotocol/ext-apps';
+
+declare abstract class Subscribable {
+    private stateListeners;
+    private eventHandlers;
+    subscribe(listener: StateListener): () => void;
+    on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
+    protected notifyStateChange(state: HostClientState, prevState: HostClientState): void;
+    protected emit<K extends keyof HostClientEvents>(event: K, ...args: Parameters<HostClientEvents[K]>): void;
+    protected onSubscribe(): void;
+    protected onUnsubscribe(): void;
+}
+
+/**
+ * MCP Apps host client implementation.
+ *
+ * Wraps the official MCP Apps SDK `App` class to provide a consistent interface
+ * with the ChatGPT host client. Handles the protocol handshake, tool calls,
+ * notifications, and automatic style/theme application.
+ */
+declare class McpHostClient extends Subscribable implements HostClient {
+    private state;
+    private config;
+    private app;
+    private connected;
+    constructor(config: HostClientConfig);
+    getState(): HostClientState;
+    private setState;
+    /**
+     * Connect to the MCP Apps host.
+     *
+     * Creates the App instance, registers notification handlers, and initiates
+     * the protocol handshake. The host will receive `ui/initialize` and respond
+     * with host context including theme, styles, and widgetState.
+     */
+    connect(): void;
+    /**
+     * Set up notification handlers on the App instance.
+     *
+     * Maps the official SDK's callback pattern to our event emitter pattern,
+     * allowing consumers to use `.on("tool-result", ...)` etc.
+     */
+    private setupHandlers;
+    /**
+     * Initiate connection using PostMessageTransport.
+     *
+     * The SDK's App.connect() handles the protocol handshake correctly:
+     * the guest (App) sends `ui/initialize` to the host.
+     */
+    private initiateConnection;
+    /**
+     * Disconnect from the host.
+     *
+     * Cleans up the App instance and resets state.
+     */
+    disconnect(): void;
+    /**
+     * Call a tool on the MCP server via the host.
+     *
+     * Uses the SDK's callServerTool method which properly routes through
+     * the host to the MCP server.
+     *
+     * @param toolName - Name of the tool to call
+     * @param args - Arguments to pass to the tool
+     * @returns Tool result with content and structuredContent
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Send a notification to the host.
+     *
+     * Sends a notification via the ext-apps SDK transport. Can be used for both
+     * spec-compliant and custom (Creature-specific) notifications.
+     *
+     * @param method - Notification method name
+     * @param params - Notification parameters
+     */
+    sendNotification(method: string, params: unknown): void;
+    /**
+     * Set widget state and notify the host.
+     *
+     * Widget state is synchronized with the host for persistence across
+     * sessions and visibility to the AI model.
+     *
+     * Note: This is a Creature-specific extension, not part of the MCP Apps spec.
+     * The host should handle `ui/notifications/widget-state-changed` notifications.
+     *
+     * @param state - New widget state (or null to clear)
+     */
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Send a log message to the host's DevConsole.
+     *
+     * Uses the MCP protocol's `notifications/message` notification to send logs
+     * to the host. Logs appear in the unified DevConsole alongside server logs,
+     * with appropriate color coding based on level.
+     *
+     * The logger name is automatically set to the app name from config.
+     *
+     * @param level - Log severity level (debug, info, notice, warning, error)
+     * @param message - Log message
+     * @param data - Optional structured data to include with the log
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+}
+
+interface OpenAIBridge {
+    toolOutput?: Record<string, unknown>;
+    widgetState?: WidgetState;
+    setWidgetState?: (state: WidgetState) => void;
+    callTool?: (name: string, args: Record<string, unknown>) => Promise<{
+        structuredContent?: Record<string, unknown>;
+        content?: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }>;
+}
+declare global {
+    interface Window {
+        openai?: OpenAIBridge;
+    }
+}
+declare class ChatGPTHostClient extends Subscribable implements HostClient {
+    private state;
+    private config;
+    private connected;
+    private hasProcessedInitialData;
+    private globalsHandler;
+    constructor(config: HostClientConfig);
+    getState(): HostClientState;
+    private setState;
+    connect(): void;
+    disconnect(): void;
+    private processInitialData;
+    private setupGlobalsListener;
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    sendNotification(_method: string, _params: unknown): void;
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Log a message to the console.
+     *
+     * ChatGPT doesn't have a DevConsole, so logs go to browser console only.
+     * This provides API parity with McpHostClient.
+     *
+     * @param level - Log severity level
+     * @param message - Log message
+     * @param data - Optional structured data
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+}
+
+/**
+ * Detect the current host environment.
+ *
+ * Used to auto-select the appropriate host client implementation:
+ * - "chatgpt": Running inside ChatGPT's widget system
+ * - "mcp-apps": Running inside an MCP Apps host (iframe with parent)
+ * - "standalone": Running outside any host environment
+ *
+ * @returns The detected environment
+ */
+declare function detectEnvironment(): Environment;
+
+type PartialState<TState extends AppSessionState> = {
+    [K in keyof TState]?: Partial<TState[K]> | TState[K];
+};
+declare class AppSession<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null> {
+    readonly id: string;
+    private _state;
+    private listeners;
+    private hostClient;
+    private hostUnsubscribe;
+    constructor(initialState?: Partial<AppSessionState<TInternal, TBackend, TUi>>, options?: {
+        id?: string;
+    });
+    private generateId;
+    get state(): AppSessionState<TInternal, TBackend, TUi>;
+    get internal(): TInternal;
+    get backend(): TBackend;
+    get ui(): TUi;
+    subscribe(listener: AppSessionListener<AppSessionState<TInternal, TBackend, TUi>>): () => void;
+    private notify;
+    setState(partial: PartialState<AppSessionState<TInternal, TBackend, TUi>>): void;
+    setInternal(internal: TInternal | Partial<TInternal>): void;
+    setBackend(backend: TBackend | Partial<TBackend>): void;
+    setUi(ui: TUi): void;
+    updateUi(partial: TUi extends null ? never : Partial<NonNullable<TUi>>): void;
+    bindHost(host: HostClient): () => void;
+    unbindHost(): void;
+    injectAppSessionId<T extends Record<string, unknown>>(data: T): T & {
+        appSessionId: string;
+    };
+}
+
+type ChannelStatus = "disconnected" | "connecting" | "connected" | "error";
+interface ChannelClientConfig<TReceive = unknown> {
+    onMessage?: (message: TReceive) => void;
+    onStatusChange?: (status: ChannelStatus, error?: string) => void;
+    reconnect?: boolean;
+    reconnectInterval?: number;
+}
+interface ChannelClient<TSend = unknown, TReceive = unknown> {
+    readonly status: ChannelStatus;
+    readonly error: string | undefined;
+    connect(): void;
+    disconnect(): void;
+    send(message: TSend): void;
+}
+declare function createChannel<TSend = unknown, TReceive = unknown>(url: string, config?: ChannelClientConfig<TReceive>): ChannelClient<TSend, TReceive>;
+
+declare function createHost(config: HostClientConfig): HostClient;
+
+export { AppSession, AppSessionListener, AppSessionState, type ChannelClient, type ChannelClientConfig, type ChannelStatus, ChatGPTHostClient, Environment, HostClient, HostClientConfig, HostClientEvents, HostClientState, LogLevel, McpHostClient, StateListener, ToolResult, WidgetState, createChannel, createHost, detectEnvironment };