@creature-ai/sdk 0.1.1

package/dist/react/index.d.ts

@@ -0,0 +1,152 @@
+import { ChannelStatus, AppSession } from '../core/index.js';
+export { ChannelClient, ChannelClientConfig, ChatGPTHostClient, McpHostClient, createChannel, createHost, detectEnvironment } from '../core/index.js';
+import { T as ToolResult, W as WidgetState, E as Environment, H as HostClient, a as AppSessionState } from '../types-DcoqlK46.js';
+export { b as AppSessionListener, A as AppSessionOptions, d as HostClientConfig, f as HostClientEvents, e as HostClientState, c as HostContext, L as LogLevel, S as StructuredWidgetState } from '../types-DcoqlK46.js';
+import * as react from 'react';
+export { applyDocumentTheme, applyHostFonts, applyHostStyleVariables, getDocumentTheme } from '@modelcontextprotocol/ext-apps';
+
+interface UseHostConfig {
+    name: string;
+    version: string;
+    onToolInput?: (args: Record<string, unknown>) => void;
+    onToolResult?: (result: ToolResult) => void;
+    onThemeChange?: (theme: "light" | "dark") => void;
+    onTeardown?: () => Promise<void>;
+    /** Called when widget state changes (restored from host or updated) */
+    onWidgetStateChange?: (widgetState: WidgetState | null) => void;
+}
+/**
+ * Logger interface with convenience methods for each log level.
+ *
+ * Provides both a default `log(message, data?)` method (logs at "info" level)
+ * and explicit level methods: `debug()`, `info()`, `notice()`, `warn()`, `error()`.
+ */
+interface Logger {
+    /**
+     * Log a message at "info" level (default).
+     * @param message - Log message
+     * @param data - Optional structured data
+     */
+    (message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log at "debug" level. Gray in DevConsole, typically hidden by default.
+     */
+    debug: (message: string, data?: Record<string, unknown>) => void;
+    /**
+     * Log at "info" level. Normal text color in DevConsole.
+     */
+    info: (message: string, data?: Record<string, unknown>) => void;
+    /**
+     * Log at "notice" level. Blue in DevConsole, for notable events.
+     */
+    notice: (message: string, data?: Record<string, unknown>) => void;
+    /**
+     * Log at "warning" level. Yellow in DevConsole.
+     */
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    /**
+     * Log at "error" level. Red in DevConsole.
+     */
+    error: (message: string, data?: Record<string, unknown>) => void;
+}
+interface UseHostReturn {
+    isReady: boolean;
+    callTool: <T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>) => Promise<ToolResult<T>>;
+    sendNotification: (method: string, params: unknown) => void;
+    environment: Environment;
+    widgetState: WidgetState | null;
+    setWidgetState: (state: WidgetState | null) => void;
+    /**
+     * Logger for sending messages to the host's DevConsole.
+     *
+     * @example
+     * ```tsx
+     * const { log } = useHost({ name: "my-app", version: "1.0.0" });
+     *
+     * // Default level (info)
+     * log("User clicked button");
+     *
+     * // With data
+     * log("Processing item", { itemId: 123 });
+     *
+     * // Specific levels
+     * log.debug("Verbose debugging info");
+     * log.info("General information");
+     * log.notice("Notable event");
+     * log.warn("Something looks off");
+     * log.error("Something went wrong", { error: err.message });
+     * ```
+     */
+    log: Logger;
+}
+
+/**
+ * React hook for connecting to an MCP Apps host.
+ *
+ * Creates a host client instance and manages its lifecycle. Automatically
+ * connects on mount and disconnects on unmount. Uses refs for callbacks
+ * to prevent reconnection loops when consumers pass inline functions.
+ *
+ * @param config - Configuration including app info and event handlers
+ * @returns Current state and methods for interacting with the host
+ *
+ * @example
+ * ```tsx
+ * const { isReady, callTool, log } = useHost({
+ *   name: "my-app",
+ *   version: "1.0.0",
+ *   onToolResult: (result) => setData(result.structuredContent),
+ * });
+ *
+ * // Logging
+ * log("User action"); // default info level
+ * log.debug("Verbose info");
+ * log.error("Something failed", { error: err.message });
+ * ```
+ */
+declare function useHost(config: UseHostConfig): UseHostReturn;
+
+interface UseToolResultReturn<T> {
+    data: T | null;
+    title: string | null;
+    isError: boolean;
+    text: string | null;
+    onToolResult: (result: ToolResult) => void;
+    reset: () => void;
+}
+declare function useToolResult<T = Record<string, unknown>>(): UseToolResultReturn<T>;
+
+type SetStateAction<T> = T | ((prev: T) => T);
+interface WidgetStateContextValue {
+    widgetState: WidgetState | null;
+    setWidgetState: (state: WidgetState | null) => void;
+}
+declare const WidgetStateContext: react.Context<WidgetStateContextValue | null>;
+declare function useWidgetState<T extends WidgetState>(initialState?: T | (() => T | null) | null): readonly [T | null, (state: SetStateAction<T | null>) => void];
+
+interface UseChannelConfig<TReceive = unknown> {
+    onMessage?: (message: TReceive) => void;
+    enabled?: boolean;
+}
+interface UseChannelReturn<TSend = unknown> {
+    status: ChannelStatus;
+    error: string | undefined;
+    send: (message: TSend) => void;
+}
+declare function useChannel<TSend = unknown, TReceive = unknown>(url: string | undefined, config?: UseChannelConfig<TReceive>): UseChannelReturn<TSend>;
+
+interface UseAppSessionConfig<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null> {
+    hostClient?: HostClient;
+    initialState?: Partial<AppSessionState<TInternal, TBackend, TUi>>;
+    id?: string;
+}
+interface UseAppSessionReturn<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null> {
+    session: AppSession<TInternal, TBackend, TUi>;
+    state: AppSessionState<TInternal, TBackend, TUi>;
+    ui: TUi;
+    setUi: (ui: TUi) => void;
+    updateUi: (partial: TUi extends null ? never : Partial<NonNullable<TUi>>) => void;
+}
+declare function useAppSession<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null>(config?: UseAppSessionConfig<TInternal, TBackend, TUi>): UseAppSessionReturn<TInternal, TBackend, TUi>;
+
+export { AppSession, AppSessionState, ChannelStatus, Environment, HostClient, type Logger, ToolResult, type UseAppSessionConfig, type UseAppSessionReturn, type UseChannelConfig, type UseChannelReturn, type UseHostConfig, type UseHostReturn, type UseToolResultReturn, WidgetState, WidgetStateContext, useAppSession, useChannel, useHost, useToolResult, useWidgetState };