oomol-cloud-block-sdk 1.0.1

package/README.md

@@ -0,0 +1,427 @@
+# OOMOL Cloud Block SDK
+
+[![npm version](https://badge.fury.io/js/oomol-cloud-block-sdk.svg)](https://www.npmjs.com/package/oomol-cloud-block-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+OOMOL Cloud Block SDK 是一个用于与 OOMOL Cloud Block API 交互的 TypeScript/JavaScript SDK，支持创建和执行无服务器 Block 任务。
+
+## 特性
+
+- 🚀 **简单易用** - 提供简洁的 API 接口
+- 📦 **TypeScript 支持** - 完整的类型定义
+- 🔄 **自动轮询** - 内置任务状态轮询机制
+- ⬆️ **文件上传** - 支持大文件分片上传
+- ♻️ **自动重试** - 内置错误处理和重试机制
+- 🎯 **进度跟踪** - 实时进度回调
+- 🛑 **可取消** - 支持 AbortController 取消操作
+
+## 安装
+
+```bash
+npm install oomol-cloud-block-sdk
+```
+
+或使用 yarn:
+
+```bash
+yarn add oomol-cloud-block-sdk
+```
+
+或使用 pnpm:
+
+```bash
+pnpm add oomol-cloud-block-sdk
+```
+
+## 快速开始
+
+### 基本使用
+
+```typescript
+import { OomolCloudBlockSDK } from "oomol-cloud-block-sdk";
+
+// 创建 SDK 实例
+const sdk = new OomolCloudBlockSDK();
+
+// 创建并执行任务
+const result = await sdk.runTask(
+  {
+    blockName: "my-block",
+    packageName: "my-package",
+    packageVersion: "1.0.0",
+    inputValues: {
+      input1: "value1",
+      input2: "value2",
+    },
+  },
+  {
+    onProgress: (progress) => {
+      console.log(`进度: ${progress}%`);
+    },
+  }
+);
+
+console.log("任务完成:", result.resultData);
+```
+
+### 分步执行
+
+```typescript
+import { OomolCloudBlockSDK } from "oomol-cloud-block-sdk";
+
+const sdk = new OomolCloudBlockSDK();
+
+// 步骤 1: 创建任务
+const { taskID } = await sdk.createTask({
+  blockName: "image-processor",
+  packageName: "image-tools",
+  packageVersion: "latest",
+  inputValues: {
+    imageUrl: "https://example.com/image.png",
+    filter: "blur",
+  },
+});
+
+console.log("任务已创建:", taskID);
+
+// 步骤 2: 等待任务完成
+const result = await sdk.awaitTaskResult(taskID, {
+  intervalMs: 2000, // 每 2 秒轮询一次
+  maxTimeoutMs: 10 * 60 * 1000, // 最多等待 10 分钟
+  onProgress: (progress) => {
+    console.log(`进度: ${progress}%`);
+  },
+});
+
+if (result.status === "success") {
+  console.log("任务成功:", result.resultData);
+  console.log("结果 URL:", result.resultURL);
+}
+```
+
+### 文件上传
+
+```typescript
+import { OomolCloudBlockSDK } from "oomol-cloud-block-sdk";
+
+const sdk = new OomolCloudBlockSDK();
+
+// 从 input[type="file"] 获取文件
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+
+// 上传文件
+const fileUrl = await sdk.uploadFile(file, {
+  onProgress: (progress) => {
+    console.log(`上传进度: ${progress}%`);
+  },
+  retries: 3, // 失败时重试 3 次
+});
+
+console.log("文件已上传:", fileUrl);
+
+// 使用上传的文件 URL 创建任务
+const result = await sdk.runTask({
+  blockName: "document-analyzer",
+  packageName: "document-tools",
+  packageVersion: "1.0.0",
+  inputValues: {
+    documentUrl: fileUrl,
+  },
+});
+```
+
+### 取消操作
+
+```typescript
+import { OomolCloudBlockSDK } from "oomol-cloud-block-sdk";
+
+const sdk = new OomolCloudBlockSDK();
+const controller = new AbortController();
+
+// 5 秒后取消操作
+setTimeout(() => {
+  controller.abort();
+  console.log("操作已取消");
+}, 5000);
+
+try {
+  const result = await sdk.runTask(
+    {
+      blockName: "long-running-task",
+      packageName: "tools",
+      packageVersion: "1.0.0",
+      inputValues: {},
+    },
+    {
+      signal: controller.signal,
+    }
+  );
+} catch (error) {
+  if (error.name === "AbortError") {
+    console.log("任务被用户取消");
+  } else {
+    console.error("任务失败:", error);
+  }
+}
+```
+
+### 错误处理
+
+```typescript
+import { OomolCloudBlockSDK, OomolCloudBlockError } from "oomol-cloud-block-sdk";
+
+const sdk = new OomolCloudBlockSDK();
+
+try {
+  const result = await sdk.runTask({
+    blockName: "my-block",
+    packageName: "my-package",
+    packageVersion: "1.0.0",
+    inputValues: {},
+  });
+
+  console.log("成功:", result);
+} catch (error) {
+  if (error instanceof OomolCloudBlockError) {
+    console.error("SDK 错误:");
+    console.error("- 消息:", error.message);
+    console.error("- 错误码:", error.code);
+    console.error("- 状态码:", error.statusCode);
+  } else {
+    console.error("未知错误:", error);
+  }
+}
+```
+
+## API 文档
+
+### OomolCloudBlockSDK
+
+主 SDK 类。
+
+#### 构造函数
+
+```typescript
+constructor(config?: OomolCloudBlockSDKConfig)
+```
+
+**参数:**
+
+- `config.taskApiBase` (可选) - 任务 API 基础 URL，默认 `https://cloud-task.oomol.com/v1`
+- `config.uploadApiBase` (可选) - 上传 API 基础 URL，默认 `https://llm.oomol.com/api/tasks/files/remote-cache`
+- `config.credentials` (可选) - 是否包含凭证（cookies），默认 `true`
+
+#### 方法
+
+##### `createTask(params: RunBlockParams): Promise<RunBlockResponse>`
+
+创建一个 Block 任务。
+
+**参数:**
+
+- `params.blockName` - Block 名称
+- `params.packageName` - Package 名称
+- `params.packageVersion` - Package 版本
+- `params.inputValues` - 输入参数对象
+
+**返回:** 包含 `taskID` 的响应对象
+
+##### `getTaskResult(taskID: string, signal?: AbortSignal): Promise<TaskResultResponse>`
+
+获取任务执行结果（单次查询）。
+
+**参数:**
+
+- `taskID` - 任务 ID
+- `signal` (可选) - AbortSignal，用于取消请求
+
+**返回:** 任务结果对象
+
+##### `awaitTaskResult(taskID: string, options?: AwaitTaskOptions): Promise<TaskResultResponse>`
+
+等待任务完成（自动轮询）。
+
+**参数:**
+
+- `taskID` - 任务 ID
+- `options.intervalMs` (可选) - 轮询间隔（毫秒），默认 1000
+- `options.maxIntervalMs` (可选) - 最大轮询间隔（毫秒），默认 10000
+- `options.maxTimeoutMs` (可选) - 最大超时时间（毫秒），默认 30 分钟
+- `options.onProgress` (可选) - 进度回调函数 `(progress: number) => void`
+- `options.signal` (可选) - AbortSignal，用于取消轮询
+
+**返回:** 任务完成时的结果（status 为 "success"）
+
+##### `uploadFile(file: File, options?: UploadOptions): Promise<string>`
+
+上传文件到云端缓存。
+
+**参数:**
+
+- `file` - 要上传的文件对象
+- `options.signal` (可选) - AbortSignal，用于取消上传
+- `options.onProgress` (可选) - 进度回调函数 `(progress: number) => void`
+- `options.retries` (可选) - 重试次数，默认 3
+
+**返回:** 上传后的文件 URL
+
+##### `runTask(params: RunBlockParams, awaitOptions?: AwaitTaskOptions): Promise<TaskResultResponse>`
+
+完整流程：创建任务并等待完成。
+
+**参数:**
+
+- `params` - 任务参数（同 `createTask`）
+- `awaitOptions` - 等待选项（同 `awaitTaskResult`）
+
+**返回:** 任务完成时的结果
+
+### 类型定义
+
+#### TaskResultResponse
+
+任务结果响应（联合类型）：
+
+```typescript
+type TaskResultResponse =
+  | {
+      status: "pending";
+      progress: number; // 0-100
+    }
+  | {
+      status: "success";
+      resultURL: string;
+      resultData: Record<string, any>;
+    }
+  | {
+      status: "failed";
+      failedMessage: string;
+    };
+```
+
+#### OomolCloudBlockError
+
+SDK 自定义错误类：
+
+```typescript
+class OomolCloudBlockError extends Error {
+  code?: string; // 错误码
+  statusCode?: number; // HTTP 状态码
+}
+```
+
+常见错误码：
+
+- `CREATE_TASK_FAILED` - 创建任务失败
+- `GET_RESULT_FAILED` - 获取结果失败
+- `TASK_FAILED` - 任务执行失败
+- `POLLING_TIMEOUT` - 轮询超时
+- `NETWORK_ERROR` - 网络错误
+- `INIT_UPLOAD_FAILED` - 初始化上传失败
+- `RETRY_EXHAUSTED` - 重试次数用尽
+
+## 高级用法
+
+### 自定义配置
+
+```typescript
+import { OomolCloudBlockSDK } from "oomol-cloud-block-sdk";
+
+const sdk = new OomolCloudBlockSDK({
+  taskApiBase: "https://custom-api.example.com/v1",
+  uploadApiBase: "https://custom-upload.example.com/api",
+  credentials: false, // 不发送 cookies
+});
+```
+
+### 进度监控
+
+```typescript
+const sdk = new OomolCloudBlockSDK();
+
+let lastProgress = 0;
+
+const result = await sdk.runTask(
+  {
+    blockName: "video-processor",
+    packageName: "media-tools",
+    packageVersion: "2.0.0",
+    inputValues: { videoUrl: "..." },
+  },
+  {
+    onProgress: (progress) => {
+      if (progress > lastProgress) {
+        console.log(`进度更新: ${lastProgress}% -> ${progress}%`);
+        lastProgress = progress;
+
+        // 更新 UI 进度条
+        document.getElementById("progress-bar").style.width = `${progress}%`;
+      }
+    },
+  }
+);
+```
+
+### 批量任务处理
+
+```typescript
+const sdk = new OomolCloudBlockSDK();
+
+const tasks = [
+  { blockName: "task1", inputValues: { input: "a" } },
+  { blockName: "task2", inputValues: { input: "b" } },
+  { blockName: "task3", inputValues: { input: "c" } },
+];
+
+// 并行创建所有任务
+const taskIDs = await Promise.all(
+  tasks.map((task) =>
+    sdk.createTask({
+      ...task,
+      packageName: "batch-processor",
+      packageVersion: "1.0.0",
+    })
+  )
+);
+
+console.log("创建的任务 IDs:", taskIDs.map((r) => r.taskID));
+
+// 并行等待所有任务完成
+const results = await Promise.all(
+  taskIDs.map((r) =>
+    sdk.awaitTaskResult(r.taskID, {
+      onProgress: (progress) => {
+        console.log(`任务 ${r.taskID}: ${progress}%`);
+      },
+    })
+  )
+);
+
+console.log("所有任务完成:", results);
+```
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式（监听文件变化）
+npm run dev
+
+# 构建
+npm run build
+```
+
+## 许可证
+
+MIT
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 支持
+
+如有问题，请访问 [GitHub Issues](https://github.com/your-org/oomol-cloud-block-sdk/issues)

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+export declare class TaskFailedError extends Error {
+    readonly taskID: string;
+    readonly detail?: unknown;
+    constructor(taskID: string, detail?: unknown);
+}
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+export declare class UploadError extends Error {
+    readonly statusCode?: number;
+    readonly code?: string;
+    constructor(message: string, statusCode?: number, code?: string);
+}

package/dist/errors.js

@@ -0,0 +1,30 @@
+export class ApiError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class TaskFailedError extends Error {
+    constructor(taskID, detail) {
+        super("Task execution failed");
+        this.name = "TaskFailedError";
+        this.taskID = taskID;
+        this.detail = detail;
+    }
+}
+export class TimeoutError extends Error {
+    constructor(message = "Operation timed out") {
+        super(message);
+        this.name = "TimeoutError";
+    }
+}
+export class UploadError extends Error {
+    constructor(message, statusCode, code) {
+        super(message);
+        this.name = "UploadError";
+        this.statusCode = statusCode;
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { AwaitOptions, BlockInfo, BlockTaskRequest, BlockTaskResponse, ClientOptions, ListBlocksRequest, TaskResultResponse, UploadOptions } from "./types.js";
+export declare class OomolBlockClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    private readonly defaultHeaders;
+    constructor(options: ClientOptions);
+    createTask(request: BlockTaskRequest): Promise<BlockTaskResponse>;
+    getTaskResult<T = unknown>(taskID: string): Promise<TaskResultResponse<T>>;
+    awaitResult<T = unknown>(taskID: string, options?: AwaitOptions): Promise<TaskResultResponse<T>>;
+    createAndWait<T = unknown>(request: BlockTaskRequest, awaitOptions?: AwaitOptions): Promise<{
+        taskID: string;
+        result: TaskResultResponse<T>;
+    }>;
+    listBlocks(request: ListBlocksRequest): Promise<BlockInfo[]>;
+    uploadFile(file: File, options?: UploadOptions): Promise<string>;
+    private uploadInit;
+    private uploadParts;
+    private uploadPart;
+    private uploadFinal;
+    private request;
+    private buildUrl;
+}
+export * from "./types.js";
+export * from "./errors.js";

package/dist/index.js

@@ -0,0 +1,269 @@
+import { ApiError, TaskFailedError, TimeoutError, UploadError } from "./errors.js";
+import { BackoffStrategy, } from "./types.js";
+const DEFAULT_BASE_URL = "https://cloud-task.oomol.com/v1";
+const DEFAULT_UPLOAD_BASE_URL = "https://llm.oomol.com/api/tasks/files/remote-cache";
+export class OomolBlockClient {
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.fetchFn = options.fetch ?? fetch;
+        this.defaultHeaders = options.defaultHeaders ?? {};
+    }
+    async createTask(request) {
+        const body = {
+            blockName: request.blockName,
+            packageName: request.packageName,
+            packageVersion: request.packageVersion,
+            inputValues: request.inputValues,
+        };
+        if (request.webhookUrl)
+            body.webhookUrl = request.webhookUrl;
+        if (request.metadata)
+            body.metadata = request.metadata;
+        const res = await this.request("/task/serverless", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return res;
+    }
+    async getTaskResult(taskID) {
+        const res = await this.request(`/task/${taskID}/result`, { method: "GET" });
+        return res;
+    }
+    async awaitResult(taskID, options = {}) {
+        const intervalBase = options.intervalMs ?? 3000;
+        const maxInterval = options.backoff?.maxIntervalMs ?? 3000;
+        const strategy = options.backoff?.strategy ?? BackoffStrategy.Exponential;
+        const controller = new AbortController();
+        const externalSignal = options.signal;
+        let aborted = false;
+        if (externalSignal) {
+            if (externalSignal.aborted)
+                aborted = true;
+            externalSignal.addEventListener("abort", () => {
+                aborted = true;
+                controller.abort();
+            });
+        }
+        const timeoutMs = options.timeoutMs;
+        let timeoutId;
+        if (typeof timeoutMs === "number" && timeoutMs > 0) {
+            timeoutId = setTimeout(() => {
+                aborted = true;
+                controller.abort();
+            }, timeoutMs);
+        }
+        try {
+            let attempt = 0;
+            while (true) {
+                if (aborted)
+                    throw new TimeoutError();
+                const result = await this.getTaskResult(taskID);
+                if (result.status === "success") {
+                    return result;
+                }
+                if (result.status === "failed") {
+                    throw new TaskFailedError(taskID, result.error ?? result);
+                }
+                options.onProgress?.(result.progress, result.status);
+                attempt += 1;
+                const nextInterval = strategy === BackoffStrategy.Exponential
+                    ? Math.min(maxInterval, intervalBase * Math.pow(1.5, attempt))
+                    : intervalBase;
+                await new Promise((r) => setTimeout(r, nextInterval));
+            }
+        }
+        finally {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+        }
+    }
+    async createAndWait(request, awaitOptions = {}) {
+        const { taskID } = await this.createTask(request);
+        const result = await this.awaitResult(taskID, awaitOptions);
+        return { taskID, result };
+    }
+    async listBlocks(request) {
+        const { packageName, packageVersion, lang } = request;
+        const url = new URL(`https://registry.oomol.com/-/oomol/packages/${packageName}/${packageVersion}/public-blocks`);
+        if (lang) {
+            url.searchParams.set("lang", lang);
+        }
+        const res = await this.fetchFn(url.toString(), {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...this.defaultHeaders,
+            },
+        });
+        if (!res.ok) {
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch {
+                body = undefined;
+            }
+            throw new ApiError(`Failed to list blocks: ${res.status}`, res.status, body);
+        }
+        return res.json();
+    }
+    async uploadFile(file, options = {}) {
+        const uploadBaseUrl = options.uploadBaseUrl ?? DEFAULT_UPLOAD_BASE_URL;
+        const retries = options.retries ?? 3;
+        const { onProgress, signal } = options;
+        const fileSize = file.size;
+        const fileExtension = (file.name.includes(".") && file.name.split(".").pop()) || "";
+        const initResponse = await this.uploadInit(uploadBaseUrl, fileExtension, fileSize, signal);
+        const { upload_id, part_size, total_parts, presigned_urls } = initResponse.data;
+        await this.uploadParts(file, part_size, total_parts, presigned_urls, fileSize, onProgress, retries, signal);
+        const finalUrl = await this.uploadFinal(uploadBaseUrl, upload_id, signal);
+        onProgress?.(100);
+        return finalUrl;
+    }
+    async uploadInit(uploadBaseUrl, fileExtension, fileSize, signal) {
+        const res = await this.fetchFn(`${uploadBaseUrl}/init`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                file_extension: `.${fileExtension}`,
+                size: fileSize,
+            }),
+            signal,
+        });
+        if (!res.ok) {
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch {
+                body = undefined;
+            }
+            throw new UploadError(`Failed to initialize upload: ${res.status}`, res.status, "INIT_UPLOAD_FAILED");
+        }
+        return res.json();
+    }
+    async uploadParts(file, partSize, totalParts, presignedUrls, fileSize, onProgress, retries = 3, signal) {
+        const uploadPromises = [];
+        const partProgress = {};
+        const updateProgress = (partNumber, loaded) => {
+            partProgress[partNumber] = loaded;
+            const totalUploaded = Object.values(partProgress).reduce((sum, bytes) => sum + bytes, 0);
+            const progress = fileSize > 0 ? Math.floor((totalUploaded / fileSize) * 100) : 0;
+            onProgress?.(progress >= 100 ? 99 : progress);
+        };
+        for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
+            const start = (partNumber - 1) * partSize;
+            const end = Math.min(start + partSize, fileSize);
+            const partData = file.slice(start, end);
+            const presignedUrl = presignedUrls[partNumber];
+            if (!presignedUrl) {
+                throw new UploadError(`Missing presigned URL for part ${partNumber}`, undefined, "MISSING_PRESIGNED_URL");
+            }
+            uploadPromises.push(this.uploadPart(partData, presignedUrl, (loaded) => updateProgress(partNumber, loaded), retries, signal));
+        }
+        await Promise.all(uploadPromises);
+    }
+    async uploadPart(partData, presignedUrl, onProgress, retries = 3, signal) {
+        let lastError;
+        for (let attempt = 1; attempt <= retries; attempt++) {
+            if (signal?.aborted) {
+                throw new UploadError("Upload cancelled", undefined, "UPLOAD_CANCELLED");
+            }
+            try {
+                const xhr = new XMLHttpRequest();
+                return await new Promise((resolve, reject) => {
+                    xhr.upload.addEventListener("progress", (e) => {
+                        if (e.lengthComputable && onProgress) {
+                            onProgress(e.loaded);
+                        }
+                    });
+                    xhr.addEventListener("load", () => {
+                        if (xhr.status >= 200 && xhr.status < 300) {
+                            resolve();
+                        }
+                        else {
+                            reject(new UploadError(`Upload failed with status ${xhr.status}`, xhr.status, "UPLOAD_FAILED"));
+                        }
+                    });
+                    xhr.addEventListener("error", () => {
+                        reject(new UploadError("Network error during upload", undefined, "NETWORK_ERROR"));
+                    });
+                    if (signal) {
+                        signal.addEventListener("abort", () => {
+                            xhr.abort();
+                            reject(new UploadError("Upload cancelled", undefined, "UPLOAD_CANCELLED"));
+                        });
+                    }
+                    xhr.open("PUT", presignedUrl);
+                    xhr.setRequestHeader("Content-Type", "application/octet-stream");
+                    xhr.send(partData);
+                });
+            }
+            catch (error) {
+                lastError = error;
+                if (lastError.name === "UploadError" && lastError.code === "UPLOAD_CANCELLED") {
+                    throw lastError;
+                }
+                if (attempt < retries) {
+                    const delay = Math.min(1000 * Math.pow(2, attempt - 1), 30000);
+                    await new Promise((r) => setTimeout(r, delay));
+                }
+            }
+        }
+        throw new UploadError(`Failed after ${retries} attempts: ${lastError?.message || "Unknown error"}`, undefined, "RETRY_EXHAUSTED");
+    }
+    async uploadFinal(uploadBaseUrl, uploadId, signal) {
+        const res = await this.fetchFn(`${uploadBaseUrl}/${encodeURIComponent(uploadId)}/url`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            signal,
+        });
+        if (!res.ok) {
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch {
+                body = undefined;
+            }
+            throw new UploadError(`Failed to get upload URL: ${res.status}`, res.status, "GET_UPLOAD_URL_FAILED");
+        }
+        const result = await res.json();
+        return result.data.url;
+    }
+    async request(path, init) {
+        const url = this.buildUrl(path);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            ...this.defaultHeaders,
+            ...(init.headers ?? {}),
+        };
+        const res = await this.fetchFn(url, { ...init, headers });
+        if (!res.ok) {
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch {
+                body = undefined;
+            }
+            throw new ApiError(`Request failed: ${res.status}`, res.status, body);
+        }
+        const data = await res.json();
+        return data;
+    }
+    buildUrl(path) {
+        const base = this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl;
+        const p = path.startsWith("/") ? path : `/${path}`;
+        return `${base}${p}`;
+    }
+}
+export * from "./types.js";
+export * from "./errors.js";

package/dist/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Possible states of a block task during its lifecycle.
+ * - `pending`: Task is queued and waiting to be processed
+ * - `running`: Task is currently being executed
+ * - `success`: Task completed successfully
+ * - `failed`: Task failed with an error
+ */
+export type TaskStatus = "pending" | "running" | "success" | "failed";
+/**
+ * Request payload for creating a new block task.
+ */
+export interface BlockTaskRequest {
+    /** The name of the block to execute */
+    blockName: string;
+    /** The package name containing the block */
+    packageName: string;
+    /** The package version. @default "latest" */
+    packageVersion: string;
+    /** Input values to pass to the block */
+    inputValues: Record<string, unknown>;
+    /** Optional webhook URL to receive task completion notifications */
+    webhookUrl?: string;
+    /** Optional metadata to attach to the task */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response returned after creating a block task.
+ */
+export interface BlockTaskResponse {
+    /** The unique identifier of the created task */
+    taskID: string;
+}
+/**
+ * Response containing the result of a block task.
+ * @template T - Type of the result data
+ */
+export interface TaskResultResponse<T = unknown> {
+    /** Current status of the task */
+    status: TaskStatus;
+    /** Progress percentage (0-100), only available when task is running */
+    progress?: number;
+    /** Result data returned by the task on success */
+    resultData?: T;
+    /** Result file URL (if available) */
+    resultURL?: string;
+    /** Error message if the task failed */
+    error?: string;
+}
+/**
+ * Strategy for polling interval backoff.
+ */
+export declare enum BackoffStrategy {
+    /** Use a fixed interval between polls */
+    Fixed = "fixed",
+    /** Increase interval exponentially between polls (recommended for long-running tasks) */
+    Exponential = "exp"
+}
+/**
+ * Options for awaiting task completion.
+ */
+export interface AwaitOptions {
+    /** Base polling interval in milliseconds. @default 3000 */
+    intervalMs?: number;
+    /** Maximum time to wait for task completion in milliseconds. If exceeded, throws TimeoutError */
+    timeoutMs?: number;
+    /** Callback invoked on each poll with current progress and status */
+    onProgress?: (progress: number | undefined, status: TaskStatus) => void;
+    /** AbortSignal to cancel the polling operation */
+    signal?: AbortSignal;
+    /** Backoff configuration for polling intervals */
+    backoff?: {
+        /** Backoff strategy to use. @default BackoffStrategy.Exponential */
+        strategy?: BackoffStrategy;
+        /** Maximum interval between polls in milliseconds. @default 3000 */
+        maxIntervalMs?: number;
+    };
+}
+/**
+ * Configuration options for the OomolBlockClient.
+ */
+export interface ClientOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL of the task API. @default "https://cloud-task.oomol.com/v1" */
+    baseUrl?: string;
+    /** Custom fetch implementation (useful for testing or environments without native fetch) */
+    fetch?: typeof fetch;
+    /** Additional headers to include in all requests */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * Options for file upload operations.
+ */
+export interface UploadOptions {
+    /** Base URL of the upload API. @default "https://llm.oomol.com/api/tasks/files/remote-cache" */
+    uploadBaseUrl?: string;
+    /** Progress callback function (0-100) */
+    onProgress?: (progress: number) => void;
+    /** Number of retry attempts for failed uploads. @default 3 */
+    retries?: number;
+    /** AbortSignal to cancel the upload operation */
+    signal?: AbortSignal;
+}
+/**
+ * Parameters for listing blocks in a package.
+ */
+export interface ListBlocksRequest {
+    /** Package name */
+    packageName: string;
+    /** Package version */
+    packageVersion: string;
+    /** Language code (optional), e.g., "zh-CN" */
+    lang?: string;
+}
+/**
+ * Block type enumeration.
+ */
+export type BlockType = "task" | "subflow";
+/**
+ * Block input handle definition.
+ */
+export interface BlockInputHandle {
+    handle: string;
+    description?: string;
+    jsonSchema?: unknown;
+    nullable?: boolean;
+    value?: unknown;
+}
+/**
+ * Block output handle definition.
+ */
+export interface BlockOutputHandle {
+    handle: string;
+    description?: string;
+    jsonSchema?: unknown;
+    nullable?: boolean;
+}
+/**
+ * Block information structure.
+ */
+export interface BlockInfo {
+    type: BlockType;
+    resourceName: string;
+    name: string;
+    title?: string;
+    description?: string;
+    icon?: string;
+    inputHandleDefs?: BlockInputHandle[];
+    outputHandleDefs?: BlockOutputHandle[];
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Strategy for polling interval backoff.
+ */
+export var BackoffStrategy;
+(function (BackoffStrategy) {
+    /** Use a fixed interval between polls */
+    BackoffStrategy["Fixed"] = "fixed";
+    /** Increase interval exponentially between polls (recommended for long-running tasks) */
+    BackoffStrategy["Exponential"] = "exp";
+})(BackoffStrategy || (BackoffStrategy = {}));

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "oomol-cloud-block-sdk",
+  "version": "1.0.1",
+  "description": "TypeScript SDK for Oomol Cloud Block API",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "oomol",
+    "cloud-block",
+    "sdk",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  }
+}