@turinhub/tale-js-sdk 1.3.0 → 2.1.0

package/README.md

@@ -1,4 +1,4 @@
-# @tale/client
+# @turinhub/tale-js-sdk
 
 官方 TypeScript SDK，用于与 Tale 后端服务集成与交互。
 
@@ -11,11 +11,11 @@
 支持 npm、pnpm、yarn 安装：
 
 ```bash
-npm install @tale/client
+npm install @turinhub/tale-js-sdk
 # 或
-pnpm add @tale/client
+pnpm add @turinhub/tale-js-sdk
 # 或
-yarn add @tale/client
+yarn add @turinhub/tale-js-sdk
 ```
 
 ## 快速开始
@@ -23,16 +23,90 @@ yarn add @tale/client
 本 SDK 采用 ESM（`type: module`）。在 TypeScript 或现代 Node.js/前端环境中可直接导入：
 
 ```ts
-// 具体导出以实际 SDK 为准（后续文档将补充）
-import * as Tale from "@tale/client";
+import {
+  getAppToken,
+  getCurrentUser,
+  listAppsByOrg,
+  listFiles,
+} from "@turinhub/tale-js-sdk";
+
+const appToken = await getAppToken({
+  baseUrl: "https://api.tale.example",
+  appKey: process.env.TALE_APP_KEY,
+  appSecret: process.env.TALE_APP_SECRET,
+});
+
+const files = await listFiles({
+  baseUrl: "https://api.tale.example",
+  appToken,
+  folderId: "folder-id",
+});
+
+const currentUser = await getCurrentUser({
+  baseUrl: "https://api.tale.example",
+  taleToken: "tale-user-token",
+});
+
+const apps = await listAppsByOrg(currentUser.app.orgId, {
+  baseUrl: "https://api.tale.example",
+  taleToken: "tale-user-token",
+});
+```
+
+## 认证与 Token
+
+SDK 中常见的鉴权选项都通过 `x-t-token` 发送到 Tale 后端：
+
+- `appToken`：应用作用域 Token，适用于 CMS、RBAC、ACL、Task、Attachment 等应用内资源 API。
+- `taleToken`：Tale 用户 Token，适用于平台级 App 管理 API，例如获取当前用户、应用列表、应用详情、App Secret，以及按 App Key 换发 App Token。
+- `baseUrl`：Tale 后端服务基础 URL；未显式传入时会读取环境变量。
+
+服务端可使用 `getAppToken()` 通过 `TALE_APP_KEY` 与 `TALE_APP_SECRET` 获取应用 Token。浏览器端的 Cookie、缓存、自动续期和多应用切换策略不由 SDK 核心管理，调用方可基于 `issueAppToken()` 自行封装。
+
+## App 与 App Token API
 
-// 示例：初始化客户端并调用 API（占位示例）
-// const client = Tale.createClient({ baseUrl: 'https://api.tale.example' })
-// const result = await client.health()
-// console.log(result)
+AppTS 模块提供平台应用相关方法：
+
+```ts
+import {
+  getCurrentUser,
+  listAppsByOrg,
+  createApp,
+  getAppDetail,
+  updateApp,
+} from "@turinhub/tale-js-sdk";
+```
+
+AppTokenTS 模块提供 App Token 相关接口封装：
+
+```ts
+import {
+  listAppTokens,
+  getAppSecret,
+  issueAppToken,
+} from "@turinhub/tale-js-sdk";
+
+const page = await listAppTokens({
+  baseUrl: "https://api.tale.example",
+  appToken: "app-token",
+  page: 0,
+  size: 20,
+  isValid: true,
+});
+
+const secret = await getAppSecret("oa_xxx", {
+  baseUrl: "https://api.tale.example",
+  taleToken: "tale-user-token",
+});
+
+const issued = await issueAppToken({
+  baseUrl: "https://api.tale.example",
+  taleToken: "tale-user-token",
+  appKey: "oa_xxx",
+});
 ```
 
-> 提示：由于 SDK 仍在迭代中，具体 API 名称与调用方式请以后续文档或源码为准。
+公开类型、入参和响应字段保持 camelCase。SDK 会处理 Java 后端可能返回的 `{ code, msg, data }` envelope 与直接 payload，但不再兼容历史 snake_case 响应字段。
 
 ## 开发与测试
 
@@ -40,7 +114,10 @@ import * as Tale from "@tale/client";
 
 ```bash
 pnpm install   # 或 npm install / yarn
-pnpm test      # 对应 package.json 中的 "test": "jest"
+pnpm run typecheck
+pnpm run build
+pnpm run test:unit
+pnpm test
 ```
 
 ## 更新日志与版本
@@ -49,7 +126,7 @@ pnpm test      # 对应 package.json 中的 "test": "jest"
 
 ## TODO
 
-- [ ] 修改 User Group 等分页格式，统一为 PageResponse。
+- [x] 修改 User Group 等分页格式，统一为 PageResponse。
 
 ## 许可证
 

package/dist/acl/index.d.ts

@@ -1,6 +1,7 @@
-import type { AclRecord, CreateAclRecordRequest, UpdateAclRecordRequest, ListAclRecordsRequest, AclBatchCreateResponse, AclTemplate, CreateAclTemplateRequest, UpdateAclTemplateRequest, ListAclTemplatesRequest, AclOptions } from "./types.js";
+import type { AclRecord, CreateAclRecordRequest, UpdateAclRecordRequest, ListAclRecordsRequest, AclBatchCreateResponse, AclBatchFailure, 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, };
+import type { Attachment } from "../attachment/types.js";
+export type { AclRecord, CreateAclRecordRequest, UpdateAclRecordRequest, ListAclRecordsRequest, AclBatchCreateResponse, AclBatchFailure, AclTemplate, CreateAclTemplateRequest, UpdateAclTemplateRequest, ListAclTemplatesRequest, AclOptions, };
 /**
  * Gets an ACL record by ID.
  *
@@ -13,11 +14,11 @@ export type { AclRecord, CreateAclRecordRequest, UpdateAclRecordRequest, ListAcl
  *
  * @example
  * ```typescript
- * import { getAclRecord } from '@tale/client';
+ * import { getAclRecord } from '@turinhub/tale-js-sdk';
  *
  * try {
- *   const record = await getAclRecord('record_id_here');
- *   console.log('Record effect:', record.effect_type);
+ *   const record = await getAclRecord('recordId_here');
+ *   console.log('Record effect:', record.effectType);
  * } catch (error) {
  *   console.error('Failed to get ACL record:', error.message);
  * }
@@ -35,13 +36,13 @@ export declare function getAclRecord(recordId: string, options?: AclOptions): Pr
  *
  * @example
  * ```typescript
- * import { listAclRecords } from '@tale/client';
+ * import { listAclRecords } from '@turinhub/tale-js-sdk';
  *
  * try {
  *   const result = await listAclRecords({
  *     page: 0,
  *     size: 20,
- *     resource_type: 'document'
+ *     resourceType: 'document'
  *   });
  *   console.log(`Found ${result.total} records`);
  * } catch (error) {
@@ -62,17 +63,17 @@ export declare function listAclRecords(options?: ListAclRecordsRequest & AclOpti
  *
  * @example
  * ```typescript
- * import { createAclRecord } from '@tale/client';
+ * import { createAclRecord } from '@turinhub/tale-js-sdk';
  *
  * try {
  *   const record = await createAclRecord({
- *     subject_type: 'user',
- *     subject_id: 'user123',
- *     resource_type: 'document',
- *     resource_id: 'doc456',
- *     effect_type: 'allow'
+ *     subjectType: 'user',
+ *     subjectId: 'user123',
+ *     resourceType: 'document',
+ *     resourceId: 'doc456',
+ *     effectType: 'allow'
  *   });
- *   console.log('Record created:', record.record_id);
+ *   console.log('Record created:', record.recordId);
  * } catch (error) {
  *   console.error('Failed to create ACL record:', error.message);
  * }
@@ -91,24 +92,24 @@ export declare function createAclRecord(request: CreateAclRecordRequest, options
  *
  * @example
  * ```typescript
- * import { batchCreateAclRecords } from '@tale/client';
+ * import { batchCreateAclRecords } from '@turinhub/tale-js-sdk';
  *
  * try {
  *   const result = await batchCreateAclRecords([
  *     {
- *       subject_type: 'user',
- *       subject_id: 'user1',
- *       resource_type: 'document',
- *       effect_type: 'allow'
+ *       subjectType: 'user',
+ *       subjectId: 'user1',
+ *       resourceType: 'document',
+ *       effectType: 'allow'
  *     },
  *     {
- *       subject_type: 'user',
- *       subject_id: 'user2',
- *       resource_type: 'document',
- *       effect_type: 'deny'
+ *       subjectType: 'user',
+ *       subjectId: 'user2',
+ *       resourceType: 'document',
+ *       effectType: 'deny'
  *     }
  *   ]);
- *   console.log(`Created ${result.success_count}, Failed ${result.failure_count}`);
+ *   console.log(`Created ${result.successCount}, Failed ${result.failureCount}`);
  * } catch (error) {
  *   console.error('Failed to batch create ACL records:', error.message);
  * }
@@ -128,14 +129,14 @@ export declare function batchCreateAclRecords(requests: CreateAclRecordRequest[]
  *
  * @example
  * ```typescript
- * import { updateAclRecord } from '@tale/client';
+ * import { updateAclRecord } from '@turinhub/tale-js-sdk';
  *
  * try {
- *   const record = await updateAclRecord('record_id_here', {
- *     effect_type: 'deny',
+ *   const record = await updateAclRecord('recordId_here', {
+ *     effectType: 'deny',
  *     priority: 100
  *   });
- *   console.log('Record updated:', record.record_id);
+ *   console.log('Record updated:', record.recordId);
  * } catch (error) {
  *   console.error('Failed to update ACL record:', error.message);
  * }
@@ -154,10 +155,10 @@ export declare function updateAclRecord(recordId: string, request: UpdateAclReco
  *
  * @example
  * ```typescript
- * import { deleteAclRecord } from '@tale/client';
+ * import { deleteAclRecord } from '@turinhub/tale-js-sdk';
  *
  * try {
- *   await deleteAclRecord('record_id_here');
+ *   await deleteAclRecord('recordId_here');
  *   console.log('ACL record deleted successfully');
  * } catch (error) {
  *   console.error('Failed to delete ACL record:', error.message);
@@ -177,11 +178,11 @@ export declare function deleteAclRecord(recordId: string, options?: AclOptions):
  *
  * @example
  * ```typescript
- * import { getAclTemplate } from '@tale/client';
+ * import { getAclTemplate } from '@turinhub/tale-js-sdk';
  *
  * try {
- *   const template = await getAclTemplate('template_code_here');
- *   console.log('Template name:', template.template_name);
+ *   const template = await getAclTemplate('templateCode_here');
+ *   console.log('Template name:', template.templateName);
  * } catch (error) {
  *   console.error('Failed to get ACL template:', error.message);
  * }
@@ -199,13 +200,13 @@ export declare function getAclTemplate(templateId: string, options?: AclOptions)
  *
  * @example
  * ```typescript
- * import { listAclTemplates } from '@tale/client';
+ * import { listAclTemplates } from '@turinhub/tale-js-sdk';
  *
  * try {
  *   const result = await listAclTemplates({
  *     page: 0,
  *     size: 20,
- *     resource_type: 'document'
+ *     resourceType: 'document'
  *   });
  *   console.log(`Found ${result.total} templates`);
  * } catch (error) {
@@ -226,17 +227,17 @@ export declare function listAclTemplates(options?: ListAclTemplatesRequest & Acl
  *
  * @example
  * ```typescript
- * import { createAclTemplate } from '@tale/client';
+ * import { createAclTemplate } from '@turinhub/tale-js-sdk';
  *
  * try {
  *   const template = await createAclTemplate({
- *     template_name: 'Document Access',
- *     template_code: 'doc_access',
- *     subject_type: 'user',
- *     resource_type: 'document',
- *     effect_type: 'allow'
+ *     templateName: 'Document Access',
+ *     templateCode: 'doc_access',
+ *     subjectType: 'user',
+ *     resourceType: 'document',
+ *     effectType: 'allow'
  *   });
- *   console.log('Template created:', template.template_id);
+ *   console.log('Template created:', template.templateId);
  * } catch (error) {
  *   console.error('Failed to create ACL template:', error.message);
  * }
@@ -256,14 +257,14 @@ export declare function createAclTemplate(request: CreateAclTemplateRequest, opt
  *
  * @example
  * ```typescript
- * import { updateAclTemplate } from '@tale/client';
+ * import { updateAclTemplate } from '@turinhub/tale-js-sdk';
  *
  * try {
- *   const template = await updateAclTemplate('template_code_here', {
- *     template_name: 'Updated Template Name',
- *     effect_type: 'deny'
+ *   const template = await updateAclTemplate('templateCode_here', {
+ *     templateName: 'Updated Template Name',
+ *     effectType: 'deny'
  *   });
- *   console.log('Template updated:', template.template_id);
+ *   console.log('Template updated:', template.templateId);
  * } catch (error) {
  *   console.error('Failed to update ACL template:', error.message);
  * }
@@ -282,10 +283,10 @@ export declare function updateAclTemplate(templateId: string, request: UpdateAcl
  *
  * @example
  * ```typescript
- * import { deleteAclTemplate } from '@tale/client';
+ * import { deleteAclTemplate } from '@turinhub/tale-js-sdk';
  *
  * try {
- *   await deleteAclTemplate('template_code_here');
+ *   await deleteAclTemplate('templateCode_here');
  *   console.log('ACL template deleted successfully');
  * } catch (error) {
  *   console.error('Failed to delete ACL template:', error.message);
@@ -293,3 +294,15 @@ export declare function updateAclTemplate(templateId: string, request: UpdateAcl
  * ```
  */
 export declare function deleteAclTemplate(templateId: string, options?: AclOptions): Promise<void>;
+/** List attachments for an ACL record */
+export declare function listAclRecordAttachments(recordId: string, options?: AclOptions & {
+    page?: number;
+    size?: number;
+    sort?: string;
+}): Promise<PageResponse<Attachment>>;
+/** Get a single attachment for an ACL record */
+export declare function getAclRecordAttachment(recordId: string, attachmentId: string, options?: AclOptions): Promise<Attachment>;
+/** Upload attachment for an ACL record */
+export declare function uploadAclRecordAttachment(recordId: string, attachmentTypeId: string, file: File | Blob, remark?: string, options?: AclOptions): Promise<Attachment>;
+/** Delete attachment from an ACL record */
+export declare function deleteAclRecordAttachment(recordId: string, attachmentId: string, options?: AclOptions): Promise<void>;