@turinhub/tale-js-sdk 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Turinhub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @tale/client
+
+官方 TypeScript SDK，用于与 Tale 后端服务集成与交互。
+
+- 项目主页：<https://github.com/turinhub/tale-js-sdk>
+- 问题反馈：<https://github.com/turinhub/tale-js-sdk/issues>
+- 许可证：MIT（详见 `LICENSE`）
+
+## 安装
+
+支持 npm、pnpm、yarn 安装：
+
+```bash
+npm install @tale/client
+# 或
+pnpm add @tale/client
+# 或
+yarn add @tale/client
+```
+
+## 快速开始
+
+本 SDK 采用 ESM（`type: module`）。在 TypeScript 或现代 Node.js/前端环境中可直接导入：
+
+```ts
+// 具体导出以实际 SDK 为准（后续文档将补充）
+import * as Tale from "@tale/client";
+
+// 示例：初始化客户端并调用 API（占位示例）
+// const client = Tale.createClient({ baseUrl: 'https://api.tale.example' })
+// const result = await client.health()
+// console.log(result)
+```
+
+> 提示：由于 SDK 仍在迭代中，具体 API 名称与调用方式请以后续文档或源码为准。
+
+## 开发与测试
+
+仓库采用 TypeScript 与 Jest：
+
+```bash
+pnpm install   # 或 npm install / yarn
+pnpm test      # 对应 package.json 中的 "test": "jest"
+```
+
+## 更新日志与版本
+
+遵循语义化版本（SemVer）。发布与变更说明将按迭代在仓库中维护。
+
+## TODO
+
+- [ ] 修改 User Group 等分页格式，统一为 PageResponse。
+
+## 许可证
+
+本项目基于 MIT 许可证开源，详见 `LICENSE` 文件。版权归 Turinhub 团队所有。

package/dist/acl/index.d.ts

@@ -0,0 +1,295 @@
+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.
+ *
+ * @param recordId - Record ID
+ * @param options - Optional configuration
+ * @returns Promise resolving to ACL record information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getAclRecord } from '@tale/client';
+ *
+ * try {
+ *   const record = await getAclRecord('record_id_here');
+ *   console.log('Record effect:', record.effect_type);
+ * } catch (error) {
+ *   console.error('Failed to get ACL record:', error.message);
+ * }
+ * ```
+ */
+export declare function getAclRecord(recordId: string, options?: AclOptions): Promise<AclRecord>;
+/**
+ * Lists ACL records with pagination and optional filtering.
+ *
+ * @param options - Optional parameters for pagination and filtering
+ * @returns Promise resolving to paginated ACL record list
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { listAclRecords } from '@tale/client';
+ *
+ * try {
+ *   const result = await listAclRecords({
+ *     page: 0,
+ *     size: 20,
+ *     resource_type: 'document'
+ *   });
+ *   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<PageResponse<AclRecord>>;
+/**
+ * Creates a new ACL record.
+ *
+ * @param request - ACL record creation request
+ * @param options - Optional configuration
+ * @returns Promise resolving to created ACL record
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { createAclRecord } from '@tale/client';
+ *
+ * try {
+ *   const record = await createAclRecord({
+ *     subject_type: 'user',
+ *     subject_id: 'user123',
+ *     resource_type: 'document',
+ *     resource_id: 'doc456',
+ *     effect_type: 'allow'
+ *   });
+ *   console.log('Record created:', record.record_id);
+ * } catch (error) {
+ *   console.error('Failed to create ACL record:', error.message);
+ * }
+ * ```
+ */
+export declare function createAclRecord(request: CreateAclRecordRequest, options?: AclOptions): Promise<AclRecord>;
+/**
+ * Batch creates ACL records.
+ *
+ * @param requests - Array of ACL record creation requests
+ * @param options - Optional configuration
+ * @returns Promise resolving to batch creation response with success/failure details
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { batchCreateAclRecords } from '@tale/client';
+ *
+ * try {
+ *   const result = await batchCreateAclRecords([
+ *     {
+ *       subject_type: 'user',
+ *       subject_id: 'user1',
+ *       resource_type: 'document',
+ *       effect_type: 'allow'
+ *     },
+ *     {
+ *       subject_type: 'user',
+ *       subject_id: 'user2',
+ *       resource_type: 'document',
+ *       effect_type: 'deny'
+ *     }
+ *   ]);
+ *   console.log(`Created ${result.success_count}, Failed ${result.failure_count}`);
+ * } catch (error) {
+ *   console.error('Failed to batch create ACL records:', error.message);
+ * }
+ * ```
+ */
+export declare function batchCreateAclRecords(requests: CreateAclRecordRequest[], options?: AclOptions): Promise<AclBatchCreateResponse>;
+/**
+ * Updates an existing ACL record.
+ *
+ * @param recordId - Record ID to update
+ * @param request - Update request with fields to modify
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated ACL record
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { updateAclRecord } from '@tale/client';
+ *
+ * try {
+ *   const record = await updateAclRecord('record_id_here', {
+ *     effect_type: 'deny',
+ *     priority: 100
+ *   });
+ *   console.log('Record updated:', record.record_id);
+ * } catch (error) {
+ *   console.error('Failed to update ACL record:', error.message);
+ * }
+ * ```
+ */
+export declare function updateAclRecord(recordId: string, request: UpdateAclRecordRequest, options?: AclOptions): Promise<AclRecord>;
+/**
+ * Deletes an ACL record.
+ *
+ * @param recordId - Record ID to delete
+ * @param options - Optional configuration
+ * @returns Promise that resolves when deletion is successful
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { deleteAclRecord } from '@tale/client';
+ *
+ * try {
+ *   await deleteAclRecord('record_id_here');
+ *   console.log('ACL record deleted successfully');
+ * } catch (error) {
+ *   console.error('Failed to delete ACL record:', error.message);
+ * }
+ * ```
+ */
+export declare function deleteAclRecord(recordId: string, options?: AclOptions): Promise<void>;
+/**
+ * Gets an ACL template by ID or code.
+ *
+ * @param templateId - Template ID or code
+ * @param options - Optional configuration
+ * @returns Promise resolving to ACL template information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getAclTemplate } from '@tale/client';
+ *
+ * try {
+ *   const template = await getAclTemplate('template_code_here');
+ *   console.log('Template name:', template.template_name);
+ * } catch (error) {
+ *   console.error('Failed to get ACL template:', error.message);
+ * }
+ * ```
+ */
+export declare function getAclTemplate(templateId: string, options?: AclOptions): Promise<AclTemplate>;
+/**
+ * Lists ACL templates with pagination and optional filtering.
+ *
+ * @param options - Optional parameters for pagination and filtering
+ * @returns Promise resolving to paginated ACL template list
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { listAclTemplates } from '@tale/client';
+ *
+ * try {
+ *   const result = await listAclTemplates({
+ *     page: 0,
+ *     size: 20,
+ *     resource_type: 'document'
+ *   });
+ *   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<PageResponse<AclTemplate>>;
+/**
+ * Creates a new ACL template.
+ *
+ * @param request - ACL template creation request
+ * @param options - Optional configuration
+ * @returns Promise resolving to created ACL template
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { createAclTemplate } from '@tale/client';
+ *
+ * try {
+ *   const template = await createAclTemplate({
+ *     template_name: 'Document Access',
+ *     template_code: 'doc_access',
+ *     subject_type: 'user',
+ *     resource_type: 'document',
+ *     effect_type: 'allow'
+ *   });
+ *   console.log('Template created:', template.template_id);
+ * } catch (error) {
+ *   console.error('Failed to create ACL template:', error.message);
+ * }
+ * ```
+ */
+export declare function createAclTemplate(request: CreateAclTemplateRequest, options?: AclOptions): Promise<AclTemplate>;
+/**
+ * Updates an existing ACL template.
+ *
+ * @param templateId - Template ID or code to update
+ * @param request - Update request with fields to modify
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated ACL template
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { updateAclTemplate } from '@tale/client';
+ *
+ * try {
+ *   const template = await updateAclTemplate('template_code_here', {
+ *     template_name: 'Updated Template Name',
+ *     effect_type: 'deny'
+ *   });
+ *   console.log('Template updated:', template.template_id);
+ * } catch (error) {
+ *   console.error('Failed to update ACL template:', error.message);
+ * }
+ * ```
+ */
+export declare function updateAclTemplate(templateId: string, request: UpdateAclTemplateRequest, options?: AclOptions): Promise<AclTemplate>;
+/**
+ * Deletes an ACL template.
+ *
+ * @param templateId - Template ID or code to delete
+ * @param options - Optional configuration
+ * @returns Promise that resolves when deletion is successful
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { deleteAclTemplate } from '@tale/client';
+ *
+ * try {
+ *   await deleteAclTemplate('template_code_here');
+ *   console.log('ACL template deleted successfully');
+ * } catch (error) {
+ *   console.error('Failed to delete ACL template:', error.message);
+ * }
+ * ```
+ */
+export declare function deleteAclTemplate(templateId: string, options?: AclOptions): Promise<void>;