@brixel_ai/artifact-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,443 @@
+/**
+ * Brixel UI Task Protocol Types
+ *
+ * This file defines the postMessage protocol between the Brixel host (chat)
+ * and the UI Task iframe.
+ */
+/**
+ * Render mode determines if the UI Task requires user interaction
+ * - "display": Just shows content, no output expected
+ * - "interaction": Requires user action, workflow waits for completion
+ */
+type RenderMode = "display" | "interaction";
+/**
+ * Context provided by Brixel host to the UI Task
+ */
+interface BrixelContext {
+    /** Unique run identifier for this execution */
+    runId: string;
+    /** Step ID within the workflow (if part of a workflow) */
+    stepId?: string;
+    /** User identifier */
+    userId?: string;
+    /** Organization identifier */
+    organizationId?: string;
+    /** UI preferences */
+    theme: "light" | "dark" | "system";
+    locale: string;
+    /** Conversation ID for API calls (optional) */
+    conversationId?: string;
+    /** API token passed by parent for authenticated requests (recommended over cookies) */
+    apiToken?: string;
+    /** Optional custom API base URL (for development/testing) */
+    apiBaseUrl?: string;
+}
+/**
+ * Artifact manifest schema
+ */
+interface ArtifactManifest {
+    id: string;
+    version: string;
+    type: "ui_component";
+    name: string;
+    description?: string;
+    renderMode: RenderMode;
+    entry: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    ui?: {
+        height?: "auto" | number;
+        minHeight?: number;
+        maxHeight?: number;
+        preferredWidth?: "message" | "full" | number;
+    };
+    permissions?: {
+        network?: string[];
+        files?: boolean;
+        clipboard?: boolean;
+    };
+}
+/**
+ * INIT: Sent by host when iframe is ready to receive data
+ */
+interface InitMessage<TInputs = unknown> {
+    type: "BRIXEL_INIT";
+    payload: {
+        runId: string;
+        inputs: TInputs;
+        context: BrixelContext;
+        renderMode: RenderMode;
+    };
+}
+/**
+ * UPDATE_INPUTS: Sent when inputs change during execution
+ */
+interface UpdateInputsMessage<TInputs = unknown> {
+    type: "BRIXEL_UPDATE_INPUTS";
+    payload: {
+        runId: string;
+        inputs: Partial<TInputs>;
+    };
+}
+/**
+ * DESTROY: Sent when the UI Task should clean up
+ */
+interface DestroyMessage {
+    type: "BRIXEL_DESTROY";
+    payload: {
+        runId: string;
+    };
+}
+/**
+ * UPDATE_THEME: Sent when the host theme changes
+ */
+interface UpdateThemeMessage {
+    type: "BRIXEL_UPDATE_THEME";
+    payload: {
+        runId: string;
+        theme: BrixelContext["theme"];
+    };
+}
+/**
+ * UPDATE_LOCALE: Sent when the host locale changes
+ */
+interface UpdateLocaleMessage {
+    type: "BRIXEL_UPDATE_LOCALE";
+    payload: {
+        runId: string;
+        locale: string;
+    };
+}
+type HostToIframeMessage<TInputs = unknown> = InitMessage<TInputs> | UpdateInputsMessage<TInputs> | DestroyMessage | UpdateThemeMessage | UpdateLocaleMessage;
+/**
+ * READY: Iframe signals it's ready to receive INIT
+ */
+interface ReadyMessage {
+    type: "BRIXEL_READY";
+    payload: {
+        version: string;
+    };
+}
+/**
+ * RESIZE: Request height change
+ */
+interface ResizeMessage {
+    type: "BRIXEL_RESIZE";
+    payload: {
+        runId: string;
+        height: number | "auto";
+    };
+}
+/**
+ * COMPLETE: Task finished with output (for interaction mode)
+ */
+interface CompleteMessage<TOutput = unknown> {
+    type: "BRIXEL_COMPLETE";
+    payload: {
+        runId: string;
+        output: TOutput;
+    };
+}
+/**
+ * CANCEL: User cancelled the task
+ */
+interface CancelMessage {
+    type: "BRIXEL_CANCEL";
+    payload: {
+        runId: string;
+        reason?: string;
+    };
+}
+/**
+ * ERROR: An error occurred in the UI Task
+ */
+interface ErrorMessage {
+    type: "BRIXEL_ERROR";
+    payload: {
+        runId: string;
+        error: {
+            code: string;
+            message: string;
+            details?: unknown;
+        };
+    };
+}
+/**
+ * LOG: Debug log from iframe (captured by host in dev mode)
+ */
+interface LogMessage {
+    type: "BRIXEL_LOG";
+    payload: {
+        runId: string;
+        level: "debug" | "info" | "warn" | "error";
+        message: string;
+        data?: unknown;
+    };
+}
+type IframeToHostMessage<TOutput = unknown> = ReadyMessage | ResizeMessage | CompleteMessage<TOutput> | CancelMessage | ErrorMessage | LogMessage;
+type TaskStatus = "initializing" | "ready" | "completed" | "cancelled" | "error";
+interface UseBrixelTaskResult<TInputs, TOutput> {
+    /** Current inputs from the host */
+    inputs: TInputs | null;
+    /** Brixel context (user, theme, locale, etc.) */
+    context: BrixelContext | null;
+    /** Current task status */
+    status: TaskStatus;
+    /** Render mode of this task */
+    renderMode: RenderMode | null;
+    /** Run ID for this execution */
+    runId: string | null;
+    /** Complete the task with output (required for interaction mode) */
+    complete: (output: TOutput) => void;
+    /** Cancel the task */
+    cancel: (reason?: string) => void;
+    /** Request height resize */
+    setHeight: (height: number | "auto") => void;
+    /** Send a log message to the host */
+    log: (level: "debug" | "info" | "warn" | "error", message: string, data?: unknown) => void;
+    /** Whether running inside Brixel iframe */
+    isEmbedded: boolean;
+    /** Execute another UI Task (bound to current context) */
+    executeTask: <TTaskOutput = unknown>(params: Omit<ExecuteTaskParams, "conversationId" | "apiToken" | "apiBaseUrl">) => Promise<ExecuteTaskResponse<TTaskOutput>>;
+}
+interface UseBrixelTaskOptions {
+    /** Target origin for postMessage (default: "*", should be restricted in production) */
+    targetOrigin?: string;
+    /** Callback when inputs are updated */
+    onInputsUpdate?: (inputs: unknown) => void;
+    /** Callback before destroy */
+    onDestroy?: () => void;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Parameters for executing a UI Task via the API
+ */
+interface ExecuteTaskParams {
+    /** UUID of the task to execute */
+    taskUuid: string;
+    /** Input values for the task */
+    inputs: Record<string, unknown>;
+    /** Optional conversation ID for x-conversation-id header */
+    conversationId?: string;
+    /** Optional API token (if not provided, uses credentials: 'include' as fallback) */
+    apiToken?: string;
+    /** Optional custom API base URL (auto-detects dev/prod if not provided) */
+    apiBaseUrl?: string;
+}
+/**
+ * Response from the execute task API
+ */
+interface ExecuteTaskResponse<TOutput = unknown> {
+    success: boolean;
+    data?: TOutput;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+
+/**
+ * Main hook for building Brixel UI Tasks
+ *
+ * @example
+ * ```tsx
+ * import { useBrixelArtifact } from "@brixel/artifact-sdk";
+ *
+ * interface Inputs {
+ *   title: string;
+ *   options: string[];
+ * }
+ *
+ * interface Output {
+ *   selectedOption: string;
+ * }
+ *
+ * function MyUITask() {
+ *   const { inputs, complete, cancel, context } = useBrixelArtifact<Inputs, Output>();
+ *
+ *   if (!inputs) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{inputs.title}</h1>
+ *       {inputs.options.map(opt => (
+ *         <button key={opt} onClick={() => complete({ selectedOption: opt })}>
+ *           {opt}
+ *         </button>
+ *       ))}
+ *       <button onClick={() => cancel()}>Cancel</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useBrixelArtifact<TInputs = unknown, TOutput = unknown>(options?: UseBrixelTaskOptions): UseBrixelTaskResult<TInputs, TOutput>;
+
+/**
+ * Execute a UI Task via the Brixel API
+ *
+ * This function allows UI Tasks to programmatically execute other UI Tasks.
+ *
+ * **API URL auto-detection:**
+ * - Development (localhost): http://localhost:8000/backoffice/ui-components
+ * - Production: https://api.brixel.ai/backoffice/ui-components
+ * - Can be overridden via `apiBaseUrl` parameter
+ *
+ * **Authentication strategy (in order of priority):**
+ * 1. **API Token from context** (RECOMMENDED): Passed via postMessage from parent
+ *    - More secure and explicit
+ *    - Parent has full control over the token
+ * 2. **Cookies fallback**: Uses credentials: 'include' if no token provided
+ *    - Works for same-domain scenarios (*.brixel.ai)
+ *
+ * @example
+ * ```tsx
+ * import { executeTask } from "@brixel/artifact-sdk";
+ *
+ * // Recommended: Use token from context (passed by parent via postMessage)
+ * const result = await executeTask({
+ *   taskUuid: "task-123-456",
+ *   inputs: { name: "John", email: "john@example.com" },
+ *   apiToken: context?.apiToken, // Token passed by parent
+ * });
+ *
+ * // Or let the hook bind it automatically
+ * const { executeTask } = useBrixelArtifact();
+ * const result = await executeTask({
+ *   taskUuid: "task-123-456",
+ *   inputs: { name: "John", email: "john@example.com" },
+ * });
+ *
+ * if (result.success) {
+ *   console.debug("Task executed:", result.data);
+ * } else {
+ *   console.error("Error:", result.error);
+ * }
+ * ```
+ *
+ * @param params - Parameters for executing the task
+ * @returns Promise with the execution result
+ */
+declare function executeTask<TOutput = unknown>(params: ExecuteTaskParams): Promise<ExecuteTaskResponse<TOutput>>;
+/**
+ * Create an executeTask function bound to a specific context
+ *
+ * This is useful when you want to reuse the same auth context
+ * for multiple task executions.
+ *
+ * @example
+ * ```tsx
+ * const { context } = useBrixelArtifact();
+ * const boundExecuteTask = createExecuteTask({
+ *   apiToken: context?.apiToken,
+ *   conversationId: context?.conversationId
+ * });
+ *
+ * // Now you can call it without passing auth each time
+ * const result = await boundExecuteTask({
+ *   taskUuid: "task-123",
+ *   inputs: { foo: "bar" }
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Or use the executeTask from the hook directly (recommended)
+ * const { executeTask } = useBrixelArtifact();
+ *
+ * const result = await executeTask({
+ *   taskUuid: "task-123",
+ *   inputs: { foo: "bar" }
+ * });
+ * ```
+ */
+declare function createExecuteTask(contextAuth?: {
+    apiToken?: string;
+    conversationId?: string;
+    apiBaseUrl?: string;
+}): <TOutput = unknown>(params: Omit<ExecuteTaskParams, "conversationId" | "apiToken" | "apiBaseUrl">) => Promise<ExecuteTaskResponse<TOutput>>;
+
+/**
+ * Development tools for testing UI Tasks outside of Brixel
+ *
+ * These utilities help simulate the Brixel host environment during development
+ */
+/**
+ * Default mock context for development
+ */
+declare const mockContext: BrixelContext;
+/**
+ * Simulate the Brixel host sending an INIT message
+ *
+ * @example
+ * ```tsx
+ * // In your main.tsx or App.tsx for development
+ * if (import.meta.env.DEV) {
+ *   simulateBrixelInit({
+ *     title: "Test Survey",
+ *     questions: [
+ *       { id: "q1", text: "How are you?", options: ["Good", "Bad"] }
+ *     ]
+ *   });
+ * }
+ * ```
+ */
+declare function simulateBrixelInit<TInputs = unknown>(inputs: TInputs, options?: {
+    runId?: string;
+    renderMode?: RenderMode;
+    context?: Partial<BrixelContext>;
+    delay?: number;
+}): void;
+/**
+ * Listen for messages from the UI Task (useful for debugging)
+ *
+ * @example
+ * ```tsx
+ * useEffect(() => {
+ *   const cleanup = listenToUITaskMessages((message) => {
+ *     console.debug("Artifact sent:", message);
+ *   });
+ *   return cleanup;
+ * }, []);
+ * ```
+ */
+declare function listenToUITaskMessages(callback: (message: unknown) => void): () => void;
+/**
+ * Create a mock Brixel host for development
+ *
+ * @example
+ * ```tsx
+ * const host = createMockBrixelHost({
+ *   onComplete: (output) => console.debug("Completed:", output),
+ *   onCancel: (reason) => console.debug("Cancelled:", reason),
+ * });
+ *
+ * // Send init
+ * host.init({ title: "Test" });
+ *
+ * // Cleanup
+ * host.destroy();
+ * ```
+ */
+declare function createMockBrixelHost<TInputs = unknown, TOutput = unknown>(options: {
+    onReady?: (version: string) => void;
+    onComplete?: (output: TOutput) => void;
+    onCancel?: (reason?: string) => void;
+    onResize?: (height: number | "auto") => void;
+    onLog?: (level: string, message: string, data?: unknown) => void;
+    onError?: (error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    }) => void;
+}): {
+    init(inputs: TInputs, runId?: string, renderMode?: RenderMode): void;
+    updateInputs(inputs: Partial<TInputs>): void;
+    destroy(): void;
+    updateTheme(theme: BrixelContext["theme"]): void;
+    updateLocale(locale: string): void;
+};
+
+export { type ArtifactManifest, type BrixelContext, type CancelMessage, type CompleteMessage, type DestroyMessage, type ErrorMessage, type ExecuteTaskParams, type ExecuteTaskResponse, type HostToIframeMessage, type IframeToHostMessage, type InitMessage, type LogMessage, type ReadyMessage, type RenderMode, type ResizeMessage, type TaskStatus, type UpdateInputsMessage, type UpdateLocaleMessage, type UpdateThemeMessage, type UseBrixelTaskOptions, type UseBrixelTaskResult, createExecuteTask, createMockBrixelHost, executeTask, listenToUITaskMessages, mockContext, simulateBrixelInit, useBrixelArtifact };