tale-js-sdk 1.1.0 → 1.2.0

package/README.md

@@ -47,6 +47,10 @@ pnpm test      # 对应 package.json 中的 "test": "jest"
 
 遵循语义化版本（SemVer）。发布与变更说明将按迭代在仓库中维护。
 
+## TODO
+
+- [ ] 修改 User Group 等分页格式，统一为 PageResponse。
+
 ## 许可证
 
 本项目基于 MIT 许可证开源，详见 `LICENSE` 文件。版权归 Turinhub 团队所有。

package/dist/acl/index.d.ts

@@ -1,4 +1,5 @@
 import type { AclRecord, CreateAclRecordRequest, UpdateAclRecordRequest, ListAclRecordsRequest, AclBatchCreateResponse, AclTemplate, CreateAclTemplateRequest, UpdateAclTemplateRequest, ListAclTemplatesRequest, AclOptions } from "./types.js";
+import type { PageResponse } from "../common/types.js";
 export type { AclRecord, CreateAclRecordRequest, UpdateAclRecordRequest, ListAclRecordsRequest, AclBatchCreateResponse, AclTemplate, CreateAclTemplateRequest, UpdateAclTemplateRequest, ListAclTemplatesRequest, AclOptions, };
 /**
  * Gets an ACL record by ID.
@@ -42,16 +43,13 @@ export declare function getAclRecord(recordId: string, options?: AclOptions): Pr
  *     size: 20,
  *     resource_type: 'document'
  *   });
- *   console.log(`Found ${result.totalElements} records`);
+ *   console.log(`Found ${result.total} records`);
  * } catch (error) {
  *   console.error('Failed to list ACL records:', error.message);
  * }
  * ```
  */
-export declare function listAclRecords(options?: ListAclRecordsRequest & AclOptions): Promise<{
-    content: AclRecord[];
-    totalElements: number;
-}>;
+export declare function listAclRecords(options?: ListAclRecordsRequest & AclOptions): Promise<PageResponse<AclRecord>>;
 /**
  * Creates a new ACL record.
  *
@@ -209,16 +207,13 @@ export declare function getAclTemplate(templateId: string, options?: AclOptions)
  *     size: 20,
  *     resource_type: 'document'
  *   });
- *   console.log(`Found ${result.totalElements} templates`);
+ *   console.log(`Found ${result.total} templates`);
  * } catch (error) {
  *   console.error('Failed to list ACL templates:', error.message);
  * }
  * ```
  */
-export declare function listAclTemplates(options?: ListAclTemplatesRequest & AclOptions): Promise<{
-    content: AclTemplate[];
-    totalElements: number;
-}>;
+export declare function listAclTemplates(options?: ListAclTemplatesRequest & AclOptions): Promise<PageResponse<AclTemplate>>;
 /**
  * Creates a new ACL template.
  *

package/dist/acl/index.js

@@ -5,7 +5,7 @@ import { ApiError, ConfigurationError, NetworkError } from "../errors.js";
  * Parses standard API response format: { code, msg, data }
  */
 function parseApiResponse(json, errorMessage, statusCode) {
-    if (typeof json !== 'object' || json === null) {
+    if (typeof json !== "object" || json === null) {
         throw new ApiError(`Invalid response: ${errorMessage} - not an object`, statusCode);
     }
     const response = json;
@@ -88,7 +88,7 @@ export async function getAclRecord(recordId, options) {
  *     size: 20,
  *     resource_type: 'document'
  *   });
- *   console.log(`Found ${result.totalElements} records`);
+ *   console.log(`Found ${result.total} records`);
  * } catch (error) {
  *   console.error('Failed to list ACL records:', error.message);
  * }
@@ -107,6 +107,7 @@ export async function listAclRecords(options) {
     const queryParams = {
         page: 0,
         size: 20,
+        sort: "createdAt,desc",
         ...requestParams,
     };
     Object.entries(queryParams).forEach(([key, value]) => {
@@ -128,11 +129,7 @@ export async function listAclRecords(options) {
         throw new NetworkError(`Failed to list ACL records: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
     const json = await response.json();
-    const data = parseApiResponse(json, "Failed to list ACL records", response.status);
-    if (!Array.isArray(data.content)) {
-        throw new ApiError("Invalid ACL records response: content is not an array", response.status);
-    }
-    return data;
+    return parseApiResponse(json, "Failed to list ACL records", response.status);
 }
 /**
  * Creates a new ACL record.
@@ -363,12 +360,14 @@ export async function deleteAclRecord(recordId, options) {
     }
     const json = await response.json();
     // Delete response may not have data field, handle differently
-    if (typeof json !== 'object' || json === null) {
+    if (typeof json !== "object" || json === null) {
         throw new ApiError("Invalid ACL record deletion response", response.status);
     }
     const apiResponse = json;
     if (apiResponse.code !== 200) {
-        const errorMsg = typeof apiResponse.msg === "string" ? apiResponse.msg : "Failed to delete ACL record";
+        const errorMsg = typeof apiResponse.msg === "string"
+            ? apiResponse.msg
+            : "Failed to delete ACL record";
         throw new ApiError(errorMsg, response.status, apiResponse.code);
     }
 }
@@ -420,15 +419,8 @@ export async function getAclTemplate(templateId, options) {
     catch (error) {
         throw new NetworkError(`Failed to get ACL template: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
-    const json = (await response.json());
-    if (json.code !== 200) {
-        const errorMsg = typeof json.msg === "string" ? json.msg : "Failed to get ACL template";
-        throw new ApiError(errorMsg, response.status, json.code);
-    }
-    if (!json.data) {
-        throw new ApiError("Invalid ACL template response: missing data", response.status);
-    }
-    return json.data;
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to get ACL template", response.status);
 }
 /**
  * Lists ACL templates with pagination and optional filtering.
@@ -449,7 +441,7 @@ export async function getAclTemplate(templateId, options) {
  *     size: 20,
  *     resource_type: 'document'
  *   });
- *   console.log(`Found ${result.totalElements} templates`);
+ *   console.log(`Found ${result.total} templates`);
  * } catch (error) {
  *   console.error('Failed to list ACL templates:', error.message);
  * }
@@ -462,19 +454,18 @@ export async function listAclTemplates(options) {
     if (!base) {
         throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
     }
-    const url = new URL(String(base).replace(/\/+$/, "") + "/acl/v1/templates");
+    const url = new URL(String(base).replace(/\/+$/, "") + "/acl/v2/templates");
     // 分离 AclOptions 字段，只保留请求参数
     const { appToken, baseUrl, ...requestParams } = options || {};
     const queryParams = {
         page: 0,
         size: 20,
-        sort_by: "createdAt",
-        sort_direction: "desc",
+        sort: "createdAt,desc",
         ...requestParams,
     };
     Object.entries(queryParams).forEach(([key, value]) => {
         if (value !== undefined) {
-            url.searchParams.append(key === "sortBy" ? "sort_by" : key === "sortDirection" ? "sort_direction" : key, String(value));
+            url.searchParams.append(key, String(value));
         }
     });
     let response;
@@ -490,15 +481,8 @@ export async function listAclTemplates(options) {
     catch (error) {
         throw new NetworkError(`Failed to list ACL templates: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
-    const json = (await response.json());
-    if (json.code !== 200) {
-        const errorMsg = typeof json.msg === "string" ? json.msg : "Failed to list ACL templates";
-        throw new ApiError(errorMsg, response.status, json.code);
-    }
-    if (!json.data || !Array.isArray(json.data.content)) {
-        throw new ApiError("Invalid ACL templates response: missing data", response.status);
-    }
-    return json.data;
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to list ACL templates", response.status);
 }
 /**
  * Creates a new ACL template.
@@ -556,15 +540,8 @@ export async function createAclTemplate(request, options) {
     catch (error) {
         throw new NetworkError(`Failed to create ACL template: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
-    const json = (await response.json());
-    if (json.code !== 200) {
-        const errorMsg = typeof json.msg === "string" ? json.msg : "Failed to create ACL template";
-        throw new ApiError(errorMsg, response.status, json.code);
-    }
-    if (!json.data) {
-        throw new ApiError("Invalid ACL template creation response: missing data", response.status);
-    }
-    return json.data;
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to create ACL template", response.status);
 }
 /**
  * Updates an existing ACL template.
@@ -618,15 +595,8 @@ export async function updateAclTemplate(templateId, request, options) {
     catch (error) {
         throw new NetworkError(`Failed to update ACL template: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
-    const json = (await response.json());
-    if (json.code !== 200) {
-        const errorMsg = typeof json.msg === "string" ? json.msg : "Failed to update ACL template";
-        throw new ApiError(errorMsg, response.status, json.code);
-    }
-    if (!json.data) {
-        throw new ApiError("Invalid ACL template update response: missing data", response.status);
-    }
-    return json.data;
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to update ACL template", response.status);
 }
 /**
  * Deletes an ACL template.

package/dist/acl/types.d.ts

@@ -131,8 +131,7 @@ export interface UpdateAclTemplateRequest {
 export interface ListAclTemplatesRequest {
     page?: number;
     size?: number;
-    sort_by?: string;
-    sort_direction?: "asc" | "desc";
+    sort?: string;
     resource_type?: string;
     subject_type?: string;
 }

package/dist/auth/index.d.ts

@@ -26,9 +26,34 @@ export type { LoginRequest, LoginOptions, LoginWithSmsOptions, VerifySmsOptions,
  * }
  * ```
  *
+ * @example
+ * ```typescript
+ * import { login } from '@tale/client';
+ *
+ * // Login with include parameters to control what data is returned
+ * const result = await login({
+ *   username: 'johndoe',
+ *   password: 'secure_password_123'
+ * }, {
+ *   include_rbac: true,           // Include roles and privileges (SDK default: false)
+ *   include_user_groups: true,    // Include user groups (SDK default: false)
+ *   include_login_methods: true,  // Include login methods (SDK default: false)
+ *   include_attributes: true,     // Include user attributes (SDK default: false)
+ *   include_acl: true             // Include ACL records (SDK default: false)
+ * });
+ * ```
+ *
  * @note The function requires the following environment variables:
  * - TALE_BASE_URL: Base URL for Tale backend services
  * - TALE_APP_KEY: Application key for authentication
+ * @note By default, all include parameters are set to false for better performance.
+ *       Explicitly set them to true if you need the additional data.
+ *
+ * @param options.include_rbac Include roles and privileges; default false
+ * @param options.include_login_methods Include user login methods; default false
+ * @param options.include_user_groups Include user groups; default false
+ * @param options.include_attributes Include user attributes; default false
+ * @param options.include_acl Include ACL records; default false
  */
 export declare function login(credentials: LoginRequest, options?: LoginOptions): Promise<LoginResponse>;
 /**

package/dist/auth/index.js

@@ -26,9 +26,34 @@ import { ApiError, ConfigurationError, NetworkError } from "../errors.js";
  * }
  * ```
  *
+ * @example
+ * ```typescript
+ * import { login } from '@tale/client';
+ *
+ * // Login with include parameters to control what data is returned
+ * const result = await login({
+ *   username: 'johndoe',
+ *   password: 'secure_password_123'
+ * }, {
+ *   include_rbac: true,           // Include roles and privileges (SDK default: false)
+ *   include_user_groups: true,    // Include user groups (SDK default: false)
+ *   include_login_methods: true,  // Include login methods (SDK default: false)
+ *   include_attributes: true,     // Include user attributes (SDK default: false)
+ *   include_acl: true             // Include ACL records (SDK default: false)
+ * });
+ * ```
+ *
  * @note The function requires the following environment variables:
  * - TALE_BASE_URL: Base URL for Tale backend services
  * - TALE_APP_KEY: Application key for authentication
+ * @note By default, all include parameters are set to false for better performance.
+ *       Explicitly set them to true if you need the additional data.
+ *
+ * @param options.include_rbac Include roles and privileges; default false
+ * @param options.include_login_methods Include user login methods; default false
+ * @param options.include_user_groups Include user groups; default false
+ * @param options.include_attributes Include user attributes; default false
+ * @param options.include_acl Include ACL records; default false
  */
 export async function login(credentials, options) {
     // Validate required fields
@@ -49,7 +74,14 @@ export async function login(credentials, options) {
     if (!appKey) {
         throw new ConfigurationError("Missing required environment variable: TALE_APP_KEY");
     }
-    const url = String(base).replace(/\/+$/, "") + "/auth/v1/login/username-password";
+    // Build URL with query parameters
+    const url = new URL(String(base).replace(/\/+$/, "") + "/auth/v1/login/username-password");
+    // Add include parameters as query params (SDK defaults to false)
+    url.searchParams.set("include_rbac", String(options?.include_rbac ?? false));
+    url.searchParams.set("include_login_methods", String(options?.include_login_methods ?? false));
+    url.searchParams.set("include_user_groups", String(options?.include_user_groups ?? false));
+    url.searchParams.set("include_attributes", String(options?.include_attributes ?? false));
+    url.searchParams.set("include_acl", String(options?.include_acl ?? false));
     // Build request body
     const requestBody = {
         username: credentials.username.trim(),
@@ -61,7 +93,7 @@ export async function login(credentials, options) {
     };
     let response;
     try {
-        response = await globalThis.fetch(url, {
+        response = await globalThis.fetch(url.toString(), {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",

package/dist/auth/types.d.ts

@@ -54,6 +54,11 @@ export interface LoginOptions {
     device_name?: string;
     device_fingerprint?: string;
     scope?: string;
+    include_rbac?: boolean;
+    include_login_methods?: boolean;
+    include_user_groups?: boolean;
+    include_attributes?: boolean;
+    include_acl?: boolean;
 }
 export interface LoginResponse {
     app: AppInfo;

package/dist/common/types.d.ts

@@ -3,41 +3,31 @@ export interface CommonOptions {
     appToken?: string;
 }
 /**
- * Spring Boot Page serialization format
+ * Pagination response format used by Tale backend
  *
- * This matches the default JSON serialization format of Spring Data's Page object
- *
- * @see https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/Page.html
+ * This matches the actual backend response format with simplified pagination metadata
  */
 export interface PageResponse<T> {
     /** Page content */
     content: T[];
+    /** Total number of elements across all pages */
+    total: number;
     /** Pagination information */
     pageable: {
+        /** Current page number (0-based) */
         pageNumber: number;
+        /** Page size */
         pageSize: number;
-        sort: {
-            sorted: boolean;
-            unsorted: boolean;
-            empty: boolean;
+        /** Sort information */
+        sort?: {
+            orders?: Array<{
+                direction: "ASC" | "DESC";
+                property: string;
+                ignoreCase: boolean;
+                nullHandling: string;
+            }>;
         };
     };
-    /** Total number of pages */
-    totalPages: number;
-    /** Total number of elements */
-    totalElements: number;
-    /** Whether this is the last page */
-    last: boolean;
-    /** Whether this is the first page */
-    first: boolean;
-    /** Number of elements in current page */
-    numberOfElements: number;
-    /** Page size */
-    size: number;
-    /** Current page number */
-    number: number;
-    /** Whether the page is empty */
-    empty: boolean;
 }
 export interface UserGroup {
     group_id: string;
@@ -83,3 +73,19 @@ export interface User {
     updated_at: string;
     remark?: string;
 }
+/**
+ * Attachment data (common type used across modules)
+ */
+export interface Attachment {
+    attachment_id: string;
+    app_id: string;
+    attachment_type_id: string;
+    ref_id: string;
+    file_name: string;
+    file_url: string;
+    file_size: number;
+    mime_type: string;
+    remark?: string;
+    created_at: string;
+    updated_at: string;
+}

package/dist/index.d.ts

@@ -6,5 +6,7 @@ export * from "./user-group/index.js";
 export * from "./rbac/index.js";
 export * from "./acl/index.js";
 export * from "./user-attribute/index.js";
+export * from "./task-type/index.js";
+export * from "./task/index.js";
 export * from "./errors.js";
-export type { CommonOptions, PageResponse, UserGroup, Role, Privilege, AppInfo, User } from "./common/types.js";
+export type { CommonOptions, PageResponse, UserGroup, Role, Privilege, AppInfo, User, Attachment, } from "./common/types.js";

package/dist/index.js

@@ -6,4 +6,6 @@ export * from "./user-group/index.js";
 export * from "./rbac/index.js";
 export * from "./acl/index.js";
 export * from "./user-attribute/index.js";
+export * from "./task-type/index.js";
+export * from "./task/index.js";
 export * from "./errors.js";

package/dist/rbac/index.js

@@ -846,9 +846,7 @@ export async function getUserPrivileges(userId, options) {
     }
     const json = (await response.json());
     if (json.code !== 200) {
-        const errorMsg = typeof json.msg === "string"
-            ? json.msg
-            : "Failed to get user privileges";
+        const errorMsg = typeof json.msg === "string" ? json.msg : "Failed to get user privileges";
         throw new ApiError(errorMsg, response.status, json.code);
     }
     if (!json.data || !Array.isArray(json.data)) {

package/dist/task/index.d.ts

@@ -0,0 +1,163 @@
+import type { UserTask, CreateUserTaskRequest, UpdateUserTaskRequest, BatchCreateUserTasksRequest, BatchQueryUserTasksRequest, BatchCreateUserTasksResponse, ListUserTasksRequest, UpdateTaskStatusRequest, TaskStatistics, TaskStatusResponse, UserTaskOptions } from "./types.js";
+import type { PageResponse } from "../common/types.js";
+export type { UserTask, CreateUserTaskRequest, UpdateUserTaskRequest, BatchCreateUserTasksRequest, BatchQueryUserTasksRequest, BatchCreateUserTasksResponse, ListUserTasksRequest, UpdateTaskStatusRequest, TaskStatistics, TaskStatusResponse, UserTaskOptions, };
+/**
+ * Creates a new user task.
+ *
+ * @param request - Task creation request
+ * @param options - Optional configuration
+ * @returns Promise resolving to created task
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function createUserTask(request: CreateUserTaskRequest, options?: UserTaskOptions): Promise<UserTask>;
+/**
+ * Batch creates user tasks.
+ *
+ * @param request - Batch creation request
+ * @param options - Optional configuration
+ * @returns Promise resolving to batch creation response
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function batchCreateUserTasks(request: BatchCreateUserTasksRequest, options?: UserTaskOptions): Promise<BatchCreateUserTasksResponse>;
+/**
+ * Gets a user task by ID.
+ *
+ * @param taskId - Task ID
+ * @param options - Optional configuration (include_attachments, include_sub_tasks)
+ * @returns Promise resolving to task
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function getUserTask(taskId: string, options?: UserTaskOptions & {
+    include_attachments?: boolean;
+    include_sub_tasks?: boolean;
+}): Promise<UserTask>;
+/**
+ * Batch gets user tasks by IDs.
+ *
+ * @param request - Batch query request
+ * @param options - Optional configuration
+ * @returns Promise resolving to array of tasks
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function batchGetUserTasks(request: BatchQueryUserTasksRequest, options?: UserTaskOptions): Promise<UserTask[]>;
+/**
+ * Lists user tasks with pagination and optional filtering.
+ *
+ * @param request - List request parameters
+ * @param options - Optional configuration
+ * @returns Promise resolving to paginated list of tasks
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function listUserTasks(request?: ListUserTasksRequest & UserTaskOptions): Promise<PageResponse<UserTask>>;
+/**
+ * Updates a user task.
+ *
+ * @param taskId - Task ID
+ * @param request - Update request
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated task
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function updateUserTask(taskId: string, request: UpdateUserTaskRequest, options?: UserTaskOptions): Promise<UserTask>;
+/**
+ * Deletes a user task.
+ *
+ * @param taskId - Task ID
+ * @param options - Optional configuration
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function deleteUserTask(taskId: string, options?: UserTaskOptions): Promise<void>;
+/**
+ * Gets task input data.
+ *
+ * @param taskId - Task ID
+ * @param options - Optional configuration
+ * @returns Promise resolving to task input data
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function getTaskInput(taskId: string, options?: UserTaskOptions): Promise<Record<string, unknown>>;
+/**
+ * Gets task output data.
+ *
+ * @param taskId - Task ID
+ * @param options - Optional configuration
+ * @returns Promise resolving to task output data
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function getTaskOutput(taskId: string, options?: UserTaskOptions): Promise<Record<string, unknown>>;
+/**
+ * Updates task input data.
+ *
+ * @param taskId - Task ID
+ * @param taskInput - New task input data
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated task
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function updateTaskInput(taskId: string, taskInput: Record<string, unknown>, options?: UserTaskOptions): Promise<UserTask>;
+/**
+ * Updates task output data.
+ *
+ * @param taskId - Task ID
+ * @param taskOutput - New task output data
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated task
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function updateTaskOutput(taskId: string, taskOutput: Record<string, unknown>, options?: UserTaskOptions): Promise<UserTask>;
+/**
+ * Gets task status.
+ *
+ * @param taskId - Task ID
+ * @param options - Optional configuration
+ * @returns Promise resolving to task status
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function getTaskStatus(taskId: string, options?: UserTaskOptions): Promise<string>;
+/**
+ * Updates task status.
+ *
+ * @param taskId - Task ID
+ * @param request - Status update request
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated task
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function updateTaskStatus(taskId: string, request: UpdateTaskStatusRequest, options?: UserTaskOptions): Promise<UserTask>;
+/**
+ * Gets task statistics.
+ *
+ * @param userId - Optional user ID filter
+ * @param options - Optional configuration
+ * @returns Promise resolving to task statistics
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ */
+export declare function getTaskStatistics(userId?: string, options?: UserTaskOptions): Promise<TaskStatistics>;