@brixel_ai/artifact-sdk 1.0.0 → 1.0.2

package/README.md

@@ -78,9 +78,16 @@ interface UseBrixelTaskOptions {
   onInputsUpdate?: (inputs) => void;  // Callback when inputs change
   onDestroy?: () => void;     // Callback before cleanup
   debug?: boolean;            // Enable debug logging
+  autoResize?: boolean;       // Auto-send BRIXEL_RESIZE based on content height (default: false)
 }
 ```
 
+### Full Parent Space vs `setHeight`
+
+If your SDK components must always fill the space allocated by the parent, keep `autoResize` disabled (default) and use CSS layout like `height: 100%` in your component root.
+
+Use `setHeight` (or `autoResize: true`) only when the iframe height must be content-driven.
+
 ## Development Mode
 
 Test your UI Task locally without Brixel:
@@ -97,24 +104,6 @@ if (import.meta.env.DEV) {
 }
 ```
 
-### Mock Host for Testing
-
-```tsx
-import { createMockBrixelHost } from "@brixel_ai/artifact-sdk";
-
-const host = createMockBrixelHost({
-  onComplete: (output) => console.debug("Completed:", output),
-  onCancel: (reason) => console.debug("Cancelled:", reason),
-  onResize: (height) => console.debug("Resize:", height),
-});
-
-// Send init
-host.init({ title: "Test" });
-
-// Later: cleanup
-host.destroy();
-```
-
 ## Render Modes
 
 ### Display Mode
@@ -179,7 +168,7 @@ function MyUITask() {
 
   const handleExecuteTask = async () => {
     const result = await executeTask({
-      taskUuid: "78c2482f-b47d-461c-9fd0-509476687be9",
+      taskId: "78c2482f-b47d-461c-9fd0-509476687be9",
       inputs: { name: "value" },
     });
 
@@ -196,10 +185,7 @@ function MyUITask() {
 
 ### Authentication
 
-The `executeTask` function supports two authentication methods (in priority order):
-
-1. **API Token via postMessage** (RECOMMENDED): The parent interface passes the token via the INIT message
-2. **Cookies fallback**: Uses `credentials: 'include'` if no token provided
+The SDK uses Bearer token authentication. The parent interface should pass `apiToken` via the INIT message context.
 
 #### Passing Token from Parent
 
@@ -213,6 +199,7 @@ iframe.contentWindow.postMessage({
     runId: 'run-123',
     inputs: { /* ... */ },
     context: {
+      organizationId: 'org-123',
       apiToken: authToken,
       // ... other context fields
     }
@@ -227,7 +214,7 @@ const { executeTask, context } = useBrixelArtifact();
 
 // Token from context is automatically used
 await executeTask({
-  taskUuid: "task-uuid",
+  taskId: "task-uuid",
   inputs: {}
 });
 
@@ -237,16 +224,90 @@ await executeTask({
 
 The SDK automatically detects your environment and uses the appropriate API:
 
-- **Development** (localhost): `http://localhost:8000/backoffice/ui-components`
-- **Production**: `https://api.brixel.ai/backoffice/ui-components`
+- **Development** (localhost): `http://localhost:8000`
+- **Production**: `https://platform.brixel.ai`
 
 When running on localhost, you'll see:
 ```
-[Brixel SDK] Using API URL: http://localhost:8000/backoffice/ui-components
+[Brixel SDK] Using API URL: http://localhost:8000
 ```
 
 See [DEVELOPMENT.md](./DEVELOPMENT.md) for details on local development setup.
 
+## Uploading Files
+
+The SDK provides an `uploadFile` function to upload files to Brixel using:
+
+- Endpoint: `POST /v1/files/`
+- Form fields:
+  - `file`
+  - `visibility` (always forced to `"user"` by the SDK)
+- Header (optional): `X-Organization-Id`
+
+```tsx
+import { useBrixelArtifact } from "@brixel_ai/artifact-sdk";
+
+function MyUITask() {
+  const { uploadFile } = useBrixelArtifact();
+
+  const handleUpload = async (file: File) => {
+    const result = await uploadFile({
+      file,
+    });
+
+    if (!result.success) {
+      console.error("Upload error:", result.error);
+      return;
+    }
+
+    console.debug("Uploaded file:", result.data);
+  };
+
+  return <input type="file" onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])} />;
+}
+```
+
+## Getting File Content
+
+The SDK provides `getFileContent` to retrieve inline file content:
+
+- Endpoint: `GET /v1/files/{brixel_file_id}/content`
+- Headers (optional):
+  - `X-Organization-Id`
+  - `X-Conversation-Id`
+  - `If-None-Match`
+  - `If-Modified-Since`
+
+```tsx
+import { useBrixelArtifact } from "@brixel_ai/artifact-sdk";
+
+function MyUITask() {
+  const { getFileContent } = useBrixelArtifact();
+
+  const handlePreview = async (brixelFileId: string) => {
+    const result = await getFileContent({
+      brixelFileId,
+    });
+
+    if (!result.success) {
+      console.error("Get content error:", result.error);
+      return;
+    }
+
+    if (result.notModified) {
+      console.debug("File not modified");
+      return;
+    }
+
+    if (!result.data) return;
+    const url = URL.createObjectURL(result.data.blob);
+    console.debug("Preview URL:", url, "content-type:", result.data.contentType);
+  };
+
+  return <button onClick={() => handlePreview("your-brixel-file-id")}>Preview</button>;
+}
+```
+
 ## PostMessage Protocol
 
 The SDK handles the following message types automatically:

package/dist/index.d.mts

@@ -198,7 +198,18 @@ interface UseBrixelTaskResult<TInputs, TOutput> {
     /** 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>>;
+    executeTask: <TTaskOutput = unknown>(params: Omit<ExecuteTaskParams, "conversationId" | "apiToken" | "apiBaseUrl"> & {
+        organizationId?: string;
+    }) => Promise<ExecuteTaskResponse<TTaskOutput>>;
+    /** Upload a file to Brixel (visibility is always forced to "user") */
+    uploadFile: <TFileOutput = InternalFilePublicOut>(params: Omit<UploadFileParams, "organizationId" | "apiToken" | "apiBaseUrl"> & {
+        organizationId?: string;
+    }) => Promise<UploadFileResponse<TFileOutput>>;
+    /** Get inline content of a Brixel file by id */
+    getFileContent: <TContentOutput = FileContentData>(params: Omit<GetFileContentParams, "organizationId" | "conversationId" | "apiToken" | "apiBaseUrl"> & {
+        organizationId?: string;
+        conversationId?: string;
+    }) => Promise<GetFileContentResponse<TContentOutput>>;
 }
 interface UseBrixelTaskOptions {
     /** Target origin for postMessage (default: "*", should be restricted in production) */
@@ -209,18 +220,22 @@ interface UseBrixelTaskOptions {
     onDestroy?: () => void;
     /** Enable debug logging */
     debug?: boolean;
+    /** Auto-send BRIXEL_RESIZE based on document.body size changes */
+    autoResize?: boolean;
 }
 /**
  * Parameters for executing a UI Task via the API
  */
 interface ExecuteTaskParams {
-    /** UUID of the task to execute */
-    taskUuid: string;
+    /** ID of the organization owning the task */
+    organizationId: string;
+    /** ID of the task to execute */
+    taskId: 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) */
+    /** API token used as Bearer token for API requests */
     apiToken?: string;
     /** Optional custom API base URL (auto-detects dev/prod if not provided) */
     apiBaseUrl?: string;
@@ -237,137 +252,127 @@ interface ExecuteTaskResponse<TOutput = unknown> {
         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>
- *   );
- * }
- * ```
+ * Parameters for uploading a file to Brixel
  */
-declare function useBrixelArtifact<TInputs = unknown, TOutput = unknown>(options?: UseBrixelTaskOptions): UseBrixelTaskResult<TInputs, TOutput>;
-
+interface UploadFileParams {
+    /** File to upload */
+    file: File;
+    /** Optional organization ID sent as X-Organization-Id header */
+    organizationId?: string;
+    /** API token used as Bearer token for API requests */
+    apiToken?: string;
+    /** Optional custom API base URL (auto-detects dev/prod if not provided) */
+    apiBaseUrl?: string;
+}
 /**
- * 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
+ * Mime type returned by Brixel for internal files.
+ * Kept as `string` because backend enum values may evolve.
  */
-declare function executeTask<TOutput = unknown>(params: ExecuteTaskParams): Promise<ExecuteTaskResponse<TOutput>>;
+type InternalFileMimeType = string;
 /**
- * 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" }
- * });
- * ```
+ * Public schema for internal file output.
+ * Mirrors backend `InternalFilePublicOut`.
+ */
+interface InternalFilePublicOut {
+    brixel_file_id: string;
+    name: string;
+    mime_type: InternalFileMimeType;
+    size: number;
+    expires_at: string | null;
+}
+/**
+ * Response from the upload file API
+ */
+interface UploadFileResponse<TOutput = InternalFilePublicOut> {
+    success: boolean;
+    data?: TOutput;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Returned file content payload
+ */
+interface FileContentData {
+    blob: Blob;
+    contentType: string | null;
+    contentLength?: number;
+    etag?: string | null;
+    lastModified?: string | null;
+}
+/**
+ * Parameters for getting file content from Brixel
  */
+interface GetFileContentParams {
+    /** Brixel file id */
+    brixelFileId: string;
+    /** Optional organization ID sent as X-Organization-Id header */
+    organizationId?: string;
+    /** Optional conversation ID sent as X-Conversation-Id header */
+    conversationId?: string;
+    /** API token used as Bearer token for API requests */
+    apiToken?: string;
+    /** Optional custom API base URL (auto-detects dev/prod if not provided) */
+    apiBaseUrl?: string;
+    /** Optional conditional request header */
+    ifNoneMatch?: string;
+    /** Optional conditional request header */
+    ifModifiedSince?: string;
+}
+/**
+ * Response from the get file content API
+ */
+interface GetFileContentResponse<TOutput = FileContentData> {
+    success: boolean;
+    notModified?: boolean;
+    data?: TOutput;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+
+declare function useBrixelArtifact<TInputs = unknown, TOutput = unknown>(options?: UseBrixelTaskOptions): UseBrixelTaskResult<TInputs, TOutput>;
+
+declare function executeTask<TOutput = unknown>(params: ExecuteTaskParams): Promise<ExecuteTaskResponse<TOutput>>;
 declare function createExecuteTask(contextAuth?: {
+    organizationId?: string;
+    apiToken?: string;
+    conversationId?: string;
+    apiBaseUrl?: string;
+}): <TOutput = unknown>(params: Omit<ExecuteTaskParams, "conversationId" | "apiToken" | "apiBaseUrl"> & {
+    organizationId?: string;
+}) => Promise<ExecuteTaskResponse<TOutput>>;
+
+declare function uploadFile<TOutput = InternalFilePublicOut>(params: UploadFileParams): Promise<UploadFileResponse<TOutput>>;
+declare function createUploadFile(contextAuth?: {
+    organizationId?: string;
     apiToken?: string;
+    apiBaseUrl?: string;
+}): <TOutput = InternalFilePublicOut>(params: Omit<UploadFileParams, "organizationId" | "apiToken" | "apiBaseUrl"> & {
+    organizationId?: string;
+}) => Promise<UploadFileResponse<TOutput>>;
+
+declare function getFileContent<TOutput = FileContentData>(params: GetFileContentParams): Promise<GetFileContentResponse<TOutput>>;
+declare function createGetFileContent(contextAuth?: {
+    organizationId?: string;
     conversationId?: string;
+    apiToken?: string;
     apiBaseUrl?: string;
-}): <TOutput = unknown>(params: Omit<ExecuteTaskParams, "conversationId" | "apiToken" | "apiBaseUrl">) => Promise<ExecuteTaskResponse<TOutput>>;
+}): <TOutput = FileContentData>(params: Omit<GetFileContentParams, "organizationId" | "conversationId" | "apiToken" | "apiBaseUrl"> & {
+    organizationId?: string;
+    conversationId?: string;
+}) => Promise<GetFileContentResponse<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
  *
@@ -404,40 +409,5 @@ declare function simulateBrixelInit<TInputs = unknown>(inputs: TInputs, options?
  * ```
  */
 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 };
+export { type ArtifactManifest, type BrixelContext, type CancelMessage, type CompleteMessage, type DestroyMessage, type ErrorMessage, type ExecuteTaskParams, type ExecuteTaskResponse, type FileContentData, type GetFileContentParams, type GetFileContentResponse, type HostToIframeMessage, type IframeToHostMessage, type InitMessage, type InternalFileMimeType, type InternalFilePublicOut, type LogMessage, type ReadyMessage, type RenderMode, type ResizeMessage, type TaskStatus, type UpdateInputsMessage, type UpdateLocaleMessage, type UpdateThemeMessage, type UploadFileParams, type UploadFileResponse, type UseBrixelTaskOptions, type UseBrixelTaskResult, createExecuteTask, createGetFileContent, createUploadFile, executeTask, getFileContent, listenToUITaskMessages, simulateBrixelInit, uploadFile, useBrixelArtifact };