@brixel_ai/artifact-sdk 1.0.2 → 1.0.4

package/README.md

@@ -157,6 +157,9 @@ interface BrixelContext {
 ## Executing Other UI Tasks
 
 The SDK allows UI Tasks to execute other UI Tasks programmatically using the `executeTask` function.
+`executeTask` returns `{ success, data }`:
+- `success: true` => `data` is the task result
+- `success: false` => `data` is an `ExecuteTaskError`
 
 ### Basic Usage
 
@@ -167,16 +170,17 @@ function MyUITask() {
   const { executeTask } = useBrixelArtifact();
 
   const handleExecuteTask = async () => {
-    const result = await executeTask({
+    const response = await executeTask<{ message: string }>({
       taskId: "78c2482f-b47d-461c-9fd0-509476687be9",
       inputs: { name: "value" },
     });
 
-    if (result.success) {
-      console.debug("Task executed:", result.data);
-    } else {
-      console.error("Error:", result.error);
+    if (!response.success) {
+      console.error("Error:", response.data);
+      return;
     }
+
+    console.debug("Task executed:", response.data);
   };
 
   return <button onClick={handleExecuteTask}>Execute Task</button>;

package/dist/index.d.mts

@@ -241,17 +241,31 @@ interface ExecuteTaskParams {
     apiBaseUrl?: string;
 }
 /**
- * Response from the execute task API
+ * Error returned by executeTask when execution fails.
  */
-interface ExecuteTaskResponse<TOutput = unknown> {
-    success: boolean;
-    data?: TOutput;
-    error?: {
-        code: string;
-        message: string;
-        details?: unknown;
-    };
+interface ExecuteTaskError {
+    code: string;
+    message: string;
+    details?: unknown;
 }
+/**
+ * Successful executeTask response.
+ */
+interface ExecuteTaskSuccessResponse<TOutput = unknown> {
+    success: true;
+    data: TOutput;
+}
+/**
+ * Failed executeTask response.
+ */
+interface ExecuteTaskFailureResponse {
+    success: false;
+    data: ExecuteTaskError;
+}
+/**
+ * Return value from executeTask.
+ */
+type ExecuteTaskResponse<TOutput = unknown> = ExecuteTaskSuccessResponse<TOutput> | ExecuteTaskFailureResponse;
 /**
  * Parameters for uploading a file to Brixel
  */
@@ -347,6 +361,7 @@ declare function createExecuteTask(contextAuth?: {
 }): <TOutput = unknown>(params: Omit<ExecuteTaskParams, "conversationId" | "apiToken" | "apiBaseUrl"> & {
     organizationId?: string;
 }) => Promise<ExecuteTaskResponse<TOutput>>;
+declare function isExecuteTaskError(value: unknown): value is ExecuteTaskError | ExecuteTaskFailureResponse;
 
 declare function uploadFile<TOutput = InternalFilePublicOut>(params: UploadFileParams): Promise<UploadFileResponse<TOutput>>;
 declare function createUploadFile(contextAuth?: {
@@ -410,4 +425,4 @@ declare function simulateBrixelInit<TInputs = unknown>(inputs: TInputs, options?
  */
 declare function listenToUITaskMessages(callback: (message: unknown) => void): () => void;
 
-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 };
+export { type ArtifactManifest, type BrixelContext, type CancelMessage, type CompleteMessage, type DestroyMessage, type ErrorMessage, type ExecuteTaskError, type ExecuteTaskFailureResponse, type ExecuteTaskParams, type ExecuteTaskResponse, type ExecuteTaskSuccessResponse, 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, isExecuteTaskError, listenToUITaskMessages, simulateBrixelInit, uploadFile, useBrixelArtifact };

package/dist/index.d.ts

@@ -241,17 +241,31 @@ interface ExecuteTaskParams {
     apiBaseUrl?: string;
 }
 /**
- * Response from the execute task API
+ * Error returned by executeTask when execution fails.
  */
-interface ExecuteTaskResponse<TOutput = unknown> {
-    success: boolean;
-    data?: TOutput;
-    error?: {
-        code: string;
-        message: string;
-        details?: unknown;
-    };
+interface ExecuteTaskError {
+    code: string;
+    message: string;
+    details?: unknown;
 }
+/**
+ * Successful executeTask response.
+ */
+interface ExecuteTaskSuccessResponse<TOutput = unknown> {
+    success: true;
+    data: TOutput;
+}
+/**
+ * Failed executeTask response.
+ */
+interface ExecuteTaskFailureResponse {
+    success: false;
+    data: ExecuteTaskError;
+}
+/**
+ * Return value from executeTask.
+ */
+type ExecuteTaskResponse<TOutput = unknown> = ExecuteTaskSuccessResponse<TOutput> | ExecuteTaskFailureResponse;
 /**
  * Parameters for uploading a file to Brixel
  */
@@ -347,6 +361,7 @@ declare function createExecuteTask(contextAuth?: {
 }): <TOutput = unknown>(params: Omit<ExecuteTaskParams, "conversationId" | "apiToken" | "apiBaseUrl"> & {
     organizationId?: string;
 }) => Promise<ExecuteTaskResponse<TOutput>>;
+declare function isExecuteTaskError(value: unknown): value is ExecuteTaskError | ExecuteTaskFailureResponse;
 
 declare function uploadFile<TOutput = InternalFilePublicOut>(params: UploadFileParams): Promise<UploadFileResponse<TOutput>>;
 declare function createUploadFile(contextAuth?: {
@@ -410,4 +425,4 @@ declare function simulateBrixelInit<TInputs = unknown>(inputs: TInputs, options?
  */
 declare function listenToUITaskMessages(callback: (message: unknown) => void): () => void;
 
-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 };
+export { type ArtifactManifest, type BrixelContext, type CancelMessage, type CompleteMessage, type DestroyMessage, type ErrorMessage, type ExecuteTaskError, type ExecuteTaskFailureResponse, type ExecuteTaskParams, type ExecuteTaskResponse, type ExecuteTaskSuccessResponse, 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, isExecuteTaskError, listenToUITaskMessages, simulateBrixelInit, uploadFile, useBrixelArtifact };

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   createUploadFile: () => createUploadFile,
   executeTask: () => executeTask,
   getFileContent: () => getFileContent,
+  isExecuteTaskError: () => isExecuteTaskError,
   listenToUITaskMessages: () => listenToUITaskMessages,
   simulateBrixelInit: () => simulateBrixelInit,
   uploadFile: () => uploadFile,
@@ -89,22 +90,16 @@ async function executeTask(params) {
   debugApiBaseUrl(baseUrl);
   try {
     if (!organizationId) {
-      return {
-        success: false,
-        error: {
-          code: "MISSING_ORGANIZATION_ID",
-          message: "organizationId is required to execute a task"
-        }
-      };
+      return toExecuteTaskFailure({
+        code: "MISSING_ORGANIZATION_ID",
+        message: "organizationId is required to execute a task"
+      });
     }
     if (!taskId) {
-      return {
-        success: false,
-        error: {
-          code: "MISSING_TASK_ID",
-          message: "taskId is required to execute a task"
-        }
-      };
+      return toExecuteTaskFailure({
+        code: "MISSING_TASK_ID",
+        message: "taskId is required to execute a task"
+      });
     }
     const headers = {
       "Content-Type": "application/json"
@@ -127,20 +122,19 @@ async function executeTask(params) {
     );
     const data = await parseJsonOrText(response);
     if (!response.ok) {
-      return {
-        success: false,
-        error: toHttpError(response, data)
-      };
+      return toExecuteTaskFailure(toHttpError(response, data));
     }
-    return {
-      success: true,
-      data: data ?? void 0
-    };
+    if (isActionExecutePayload(data)) {
+      if (data.success === false) {
+        return toExecuteTaskFailure(toActionExecutionError(data));
+      }
+      if ("result" in data) {
+        return toExecuteTaskSuccess(data.result);
+      }
+    }
+    return toExecuteTaskSuccess(data ?? void 0);
   } catch (error) {
-    return {
-      success: false,
-      error: toNetworkError(error)
-    };
+    return toExecuteTaskFailure(toNetworkError(error));
   }
 }
 function createExecuteTask(contextAuth) {
@@ -155,6 +149,44 @@ function createExecuteTask(contextAuth) {
     });
   };
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isActionExecutePayload(value) {
+  return isRecord(value) && ("result" in value || "success" in value || "error" in value);
+}
+function toActionExecutionError(payload) {
+  const message = typeof payload.error === "string" && payload.error.trim() ? payload.error : "Task execution failed";
+  return {
+    code: "TASK_EXECUTION_FAILED",
+    message,
+    details: payload
+  };
+}
+function toExecuteTaskSuccess(data) {
+  return {
+    success: true,
+    data
+  };
+}
+function toExecuteTaskFailure(error) {
+  return {
+    success: false,
+    data: error
+  };
+}
+function isExecuteTaskError(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (typeof value.code === "string" && typeof value.message === "string") {
+    return true;
+  }
+  if (value.success !== false || !("data" in value) || !isRecord(value.data)) {
+    return false;
+  }
+  return typeof value.data.code === "string" && typeof value.data.message === "string";
+}
 
 // src/uploadFile.ts
 async function uploadFile(params) {
@@ -557,6 +589,7 @@ function listenToUITaskMessages(callback) {
   createUploadFile,
   executeTask,
   getFileContent,
+  isExecuteTaskError,
   listenToUITaskMessages,
   simulateBrixelInit,
   uploadFile,

package/dist/index.mjs

@@ -55,22 +55,16 @@ async function executeTask(params) {
   debugApiBaseUrl(baseUrl);
   try {
     if (!organizationId) {
-      return {
-        success: false,
-        error: {
-          code: "MISSING_ORGANIZATION_ID",
-          message: "organizationId is required to execute a task"
-        }
-      };
+      return toExecuteTaskFailure({
+        code: "MISSING_ORGANIZATION_ID",
+        message: "organizationId is required to execute a task"
+      });
     }
     if (!taskId) {
-      return {
-        success: false,
-        error: {
-          code: "MISSING_TASK_ID",
-          message: "taskId is required to execute a task"
-        }
-      };
+      return toExecuteTaskFailure({
+        code: "MISSING_TASK_ID",
+        message: "taskId is required to execute a task"
+      });
     }
     const headers = {
       "Content-Type": "application/json"
@@ -93,20 +87,19 @@ async function executeTask(params) {
     );
     const data = await parseJsonOrText(response);
     if (!response.ok) {
-      return {
-        success: false,
-        error: toHttpError(response, data)
-      };
+      return toExecuteTaskFailure(toHttpError(response, data));
     }
-    return {
-      success: true,
-      data: data ?? void 0
-    };
+    if (isActionExecutePayload(data)) {
+      if (data.success === false) {
+        return toExecuteTaskFailure(toActionExecutionError(data));
+      }
+      if ("result" in data) {
+        return toExecuteTaskSuccess(data.result);
+      }
+    }
+    return toExecuteTaskSuccess(data ?? void 0);
   } catch (error) {
-    return {
-      success: false,
-      error: toNetworkError(error)
-    };
+    return toExecuteTaskFailure(toNetworkError(error));
   }
 }
 function createExecuteTask(contextAuth) {
@@ -121,6 +114,44 @@ function createExecuteTask(contextAuth) {
     });
   };
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isActionExecutePayload(value) {
+  return isRecord(value) && ("result" in value || "success" in value || "error" in value);
+}
+function toActionExecutionError(payload) {
+  const message = typeof payload.error === "string" && payload.error.trim() ? payload.error : "Task execution failed";
+  return {
+    code: "TASK_EXECUTION_FAILED",
+    message,
+    details: payload
+  };
+}
+function toExecuteTaskSuccess(data) {
+  return {
+    success: true,
+    data
+  };
+}
+function toExecuteTaskFailure(error) {
+  return {
+    success: false,
+    data: error
+  };
+}
+function isExecuteTaskError(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (typeof value.code === "string" && typeof value.message === "string") {
+    return true;
+  }
+  if (value.success !== false || !("data" in value) || !isRecord(value.data)) {
+    return false;
+  }
+  return typeof value.data.code === "string" && typeof value.data.message === "string";
+}
 
 // src/uploadFile.ts
 async function uploadFile(params) {
@@ -522,6 +553,7 @@ export {
   createUploadFile,
   executeTask,
   getFileContent,
+  isExecuteTaskError,
   listenToUITaskMessages,
   simulateBrixelInit,
   uploadFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brixel_ai/artifact-sdk",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "SDK for building Brixel Artifacts - interactive React components that integrate with Brixel workflows",
   "main": "dist/index.js",
   "module": "dist/index.mjs",