{"_id":"@caixuan-cc/sdk","_rev":"4-b792553fccc368dc1176987c94e1fe22","name":"@caixuan-cc/sdk","dist-tags":{"latest":"0.3.1"},"versions":{"0.1.0":{"name":"@caixuan-cc/sdk","version":"0.1.0","license":"MIT","_id":"@caixuan-cc/sdk@0.1.0","maintainers":[{"name":"stonephp","email":"13740080@qq.com"}],"homepage":"https://github.com/deckflow/caixuan/tree/main/sdks/typescript#readme","bugs":{"url":"https://github.com/deckflow/caixuan/issues"},"dist":{"shasum":"8fab948ddd7bcb1602f0fe81a0639e892d1a72f0","tarball":"https://registry.npmjs.org/@caixuan-cc/sdk/-/sdk-0.1.0.tgz","fileCount":12,"integrity":"sha512-GXw/JjSZpKEv6qcHcoBQ+hSQBaaIG/SqJzImo+srlD6ycTErr0/6KI5Z4WlR51bM/Enjna5nWXykyzPCVVbfpg==","signatures":[{"sig":"MEUCIQCN09oGT1GfWIlzrREzajpY+1mRV2ZrHSMMpxKnxh8bygIgOTEaQBus4k5J17Adm3Mt3mwA46MVriOAnKUuLIWFUc0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":160533},"main":"./dist/index.js","type":"module","types":"./src/index.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./src/index.ts","import":"./dist/index.js"}},"gitHead":"9bb9071b5ee3ef8154f430ed32b217b5e4e56abe","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit"},"_npmUser":{"name":"stonephp","email":"13740080@qq.com"},"repository":{"url":"git+https://github.com/deckflow/caixuan.git","type":"git","directory":"sdks/typescript"},"_npmVersion":"11.8.0","description":"Caixuan TypeScript SDK","directories":{},"_nodeVersion":"24.13.1","dependencies":{"axios":"^1.6.0","p-limit":"^5.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.0.0","typescript":"^5.3.0","@types/node":"^20.10.0","axios-mock-adapter":"^1.22.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1788343877863_0.4602515710522648","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@caixuan-cc/sdk","version":"0.2.0","license":"MIT","_id":"@caixuan-cc/sdk@0.2.0","maintainers":[{"name":"stonephp","email":"13740080@qq.com"}],"homepage":"https://github.com/deckflow/caixuan/tree/main/sdks/typescript#readme","bugs":{"url":"https://github.com/deckflow/caixuan/issues"},"dist":{"shasum":"3c1b5bde81aa846a8814c39d477ed0e14e7914e9","tarball":"https://registry.npmjs.org/@caixuan-cc/sdk/-/sdk-0.2.0.tgz","fileCount":12,"integrity":"sha512-iJO9luo3VRy3o6EhWozaFsMQYZNiSb2XKhP3zvB68yj882HmcQxjeINouNgNc1DpxYAqUC3atL0iYk7EL3/FOA==","signatures":[{"sig":"MEQCIG1OEkOg+jlGhZlBVMRgp20z3H4fm1c9QKCAyRLOEXdxAiBGgx+TJ6mi6ylNisE4y6ijMFxjR250UadN5Rhc+F94dQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":166053},"main":"./dist/index.js","type":"module","types":"./src/index.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./src/index.ts","import":"./dist/index.js"}},"gitHead":"27c6a4131e793986b3404fd849680e53c3a86a22","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit"},"_npmUser":{"name":"stonephp","email":"13740080@qq.com"},"repository":{"url":"git+https://github.com/deckflow/caixuan.git","type":"git","directory":"sdks/typescript"},"_npmVersion":"11.8.0","description":"Caixuan TypeScript SDK","directories":{},"_nodeVersion":"24.13.1","dependencies":{"axios":"^1.6.0","p-limit":"^5.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.0.0","typescript":"^5.3.0","@types/node":"^20.10.0","axios-mock-adapter":"^1.22.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1788418921685_0.44949054529598276","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@caixuan-cc/sdk","version":"0.3.0","license":"MIT","_id":"@caixuan-cc/sdk@0.3.0","maintainers":[{"name":"stonephp","email":"13740080@qq.com"}],"homepage":"https://github.com/deckflow/caixuan/tree/main/sdks/typescript#readme","bugs":{"url":"https://github.com/deckflow/caixuan/issues"},"dist":{"shasum":"1aff49dccadb432f0e3cf78365d0d93cfd2fa034","tarball":"https://registry.npmjs.org/@caixuan-cc/sdk/-/sdk-0.3.0.tgz","fileCount":12,"integrity":"sha512-cbnp/O8euo1DgKp8YrLOwYg3j9kQzIk/kFv/ejmKuvwABhvjsOExcG63CDnIDU2AwKtajqMf3x8h+hOcyWb63A==","signatures":[{"sig":"MEQCIEquHSmeh2Txaz77Fhd281Ebw8pa/an5Xf5jCXMPPXPoAiAadufo7HpilUsX1xk7DTDdaUk5PrNCKL6a2CdTgqjpUw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":168134},"main":"./dist/index.js","type":"module","types":"./src/index.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./src/index.ts","import":"./dist/index.js"}},"gitHead":"8ee6f4451f0dfcb63a0b74030405efa7ebfaaf1a","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit"},"_npmUser":{"name":"stonephp","email":"13740080@qq.com"},"repository":{"url":"git+https://github.com/deckflow/caixuan.git","type":"git","directory":"sdks/typescript"},"_npmVersion":"11.8.0","description":"Caixuan TypeScript SDK","directories":{},"_nodeVersion":"24.13.1","dependencies":{"axios":"^1.6.0","p-limit":"^5.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.0.0","typescript":"^5.3.0","@types/node":"^20.10.0","axios-mock-adapter":"^1.22.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.3.0_1789116016718_0.842597093863706","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@caixuan-cc/sdk","version":"0.3.1","description":"Caixuan TypeScript SDK","license":"MIT","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"axios":"^1.6.0","p-limit":"^5.0.0"},"devDependencies":{"@types/node":"^20.10.0","axios-mock-adapter":"^1.22.0","tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^1.0.0"},"engines":{"node":">=18.0.0"},"repository":{"type":"git","url":"git+https://github.com/deckflow/caixuan.git","directory":"sdks/typescript"},"bugs":{"url":"https://github.com/deckflow/caixuan/issues"},"homepage":"https://github.com/deckflow/caixuan/tree/main/sdks/typescript#readme","scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit"},"_id":"@caixuan-cc/sdk@0.3.1","_integrity":"sha512-YaJpqxdS5nHKZlwPY3whZAwvxp2xTRnXL2SCOyjCD0A7LUg9eNKolDvrU60Lt4m/xqPAuIDkZpEvGpvE/1rDzA==","_resolved":"/private/var/folders/0y/70x5wdps1q9dkptpbypgdt840000gn/T/d97a63a2f5ba8673788ca98b1735b560/caixuan-cc-sdk-0.3.1.tgz","_from":"file:caixuan-cc-sdk-0.3.1.tgz","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-YaJpqxdS5nHKZlwPY3whZAwvxp2xTRnXL2SCOyjCD0A7LUg9eNKolDvrU60Lt4m/xqPAuIDkZpEvGpvE/1rDzA==","shasum":"ee944ae4d1289ca1f9ab050cceedbe50106fc75a","tarball":"https://registry.npmjs.org/@caixuan-cc/sdk/-/sdk-0.3.1.tgz","fileCount":13,"unpackedSize":169211,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDbj7+BvwK+fshVSoI+QRdrSzZWB3rrIllpU5DNxHa4twIgfKTctIcBy9+DSOlYsXL67mbn20phJwV+oqU2yuDyeQk="}]},"_npmUser":{"name":"stonephp","email":"13740080@qq.com"},"directories":{},"maintainers":[{"name":"stonephp","email":"13740080@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.3.1_1789381832226_0.375132137552173"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T10:11:17.473Z","modified":"2026-09-14T10:30:32.593Z","0.1.0":"2026-09-02T10:11:18.015Z","0.2.0":"2026-09-03T07:02:01.829Z","0.3.0":"2026-09-11T08:40:16.854Z","0.3.1":"2026-09-14T10:30:32.409Z"},"bugs":{"url":"https://github.com/deckflow/caixuan/issues"},"license":"MIT","homepage":"https://github.com/deckflow/caixuan/tree/main/sdks/typescript#readme","repository":{"type":"git","url":"git+https://github.com/deckflow/caixuan.git","directory":"sdks/typescript"},"description":"Caixuan TypeScript SDK","maintainers":[{"name":"stonephp","email":"13740080@qq.com"}],"readme":"# @caixuan-cc/sdk\n\n> [English](README.md) · **中文** · [Français](README.fr.md) · [Español](README.es.md) · [Deutsch](README.de.md) · [Русский](README.ru.md) · [日本語](README.ja.md) · [한국어](README.ko.md)\n\n[Caixuan](https://app.caixuan.cc) 平台的 TypeScript SDK，用于在 Node.js 服务、脚本或自动化流程中对接 Caixuan API。\n\n## 安装\n\n```bash\nnpm install @caixuan-cc/sdk\n```\n\n要求 Node.js >= 18。\n\n## 快速开始\n\n```typescript\nimport { createCaixuan } from '@caixuan-cc/sdk';\n\nconst client = createCaixuan({\n  token: process.env.CAIXUAN_TOKEN,\n  spaceId: process.env.CAIXUAN_SPACE_ID,\n});\n\n// 获取当前会话\nconst session = await client.session.get();\n\n// 列出空间\nconst { rows: spaces } = await client.spaces.list();\n\n// 上传文件并创建文档\nconst file = await client.files.upload('./deck.pptx');\nconst doc = await client.docs.create({\n  spaceId: spaces[0].id,\n  fileId: file.id,\n  name: file.name,\n});\n```\n\n## 初始化客户端\n\n通过 `createCaixuan()` 创建客户端实例：\n\n```typescript\nimport { createCaixuan, DEFAULT_ROOT } from '@caixuan-cc/sdk';\n\nconst client = createCaixuan({\n  root: DEFAULT_ROOT,           // API 根地址，默认 https://app.caixuan.cc/api\n  token: 'your-auth-token',     // 用户 Token（X-Auth-Token 请求头）\n  spaceId: 'space-id',          // 当前操作的空间 ID（可选，未设置时会自动解析）\n  userId: 'user-id',            // 用户 ID（可选）\n  lang: 'zh',                   // 语言，'zh' | 'en'\n  basicAuth: 'user:pass',       // nginx Basic Auth（可选）\n  onUnauthorized: async () => { // Token 过期时自动刷新（可选）\n    const newToken = await refreshToken();\n    return { token: newToken };\n  },\n});\n```\n\n客户端创建后，也可动态更新认证信息：\n\n```typescript\nclient.setToken('new-token');\nclient.setSpaceId('space-id');\nclient.setUserId('user-id');\nclient.setBasicAuth('user:pass');\n```\n\n### 获取 Token\n\n- 在 Caixuan Web 端完成 OAuth 登录后获取\n- 或使用 CLI：`caixuan login` 后通过 `caixuan config show` 查看\n\n### 空间 ID 解析\n\n多数 API 需要 `spaceId`。若初始化时未传入，SDK 会按以下顺序自动解析：\n\n1. 已显式设置的 `spaceId`\n2. 调用 `/session` 获取 `defaultSpace.id`\n\n## API 模块\n\n客户端通过命名空间访问各资源 API：\n\n| 模块 | 说明 |\n|------|------|\n| `client.session` | 会话（当前用户、登出） |\n| `client.spaces` | 空间列表、详情、切换 |\n| `client.shares` | 分享链接 CRUD 与启用/禁用 |\n| `client.docs` | 文档 CRUD |\n| `client.members` | 空间成员管理 |\n| `client.files` | 文件上传 |\n\n### Session\n\n```typescript\nconst session = await client.session.get();\n// session.id, session.defaultSpace, ...\n\nawait client.session.logout();\n```\n\n### Spaces\n\n```typescript\nconst { rows, count } = await client.spaces.list();\nconst space = await client.spaces.get();           // 当前空间\nconst current = await client.spaces.current();     // 从 session 读取\nawait client.spaces.select('space-id');            // 切换并设为默认\n```\n\n### Shares\n\n```typescript\nconst { rows } = await client.shares.list(undefined, { _startIndex: 0, _maxResults: 20 });\nconst share = await client.shares.get('share-id', ['content']);\n\nconst created = await client.shares.create({\n  spaceId: 'space-id',\n  name: '我的分享',\n  description: '可选描述',\n  content: [{ _type: 'doc', id: 'doc-id' }],\n  needPhone: 'no',\n});\n\nawait client.shares.update({ id: 'share-id', name: '新名称', password: '1234' });\nawait client.shares.changeStatus('share-id', 'enabled');\nawait client.shares.changeStatus('share-id', 'disabled');\nawait client.shares.delete('share-id');\n```\n\n### Docs\n\n```typescript\nconst { rows } = await client.docs.list(undefined, { name: 'demo', tag: 'pptx' });\nconst doc = await client.docs.get('doc-id');\n\nconst created = await client.docs.create({\n  spaceId: 'space-id',\n  fileId: 'file-id',\n  name: 'demo.pptx',\n  folderId: '',\n});\n\nawait client.docs.rename('doc-id', 'new-name.pptx');\nawait client.docs.delete('doc-id');\nawait client.docs.recover('doc-id');\n```\n\n### Members\n\n```typescript\nconst { rows } = await client.members.list();\nconst member = await client.members.get(undefined, 'user-id');\n\nawait client.members.add({\n  spaceId: 'space-id',\n  role: 'teammate',   // 'manager' | 'teammate' | 'guest'\n  email: 'user@example.com',\n  name: '张三',\n});\n\nawait client.members.updateRole(undefined, 'user-id', 'manager');\nawait client.members.rename(undefined, 'user-id', '新名字');\nawait client.members.remove(undefined, 'user-id');\n```\n\n### Files（上传）\n\n支持本地文件路径或二进制数据，自动处理单文件与分片上传：\n\n```typescript\n// 上传本地文件\nconst result = await client.files.upload('./presentation.pptx', {\n  spaceId: 'space-id',\n  onProgress: (pct) => console.log(`${Math.round(pct * 100)}%`),\n});\n// result: { id, name, bytes, hash }\n\n// 上传二进制数据（需指定 name）\nconst buffer = new Uint8Array(await fetch(url).then(r => r.arrayBuffer()));\nconst result2 = await client.files.upload(buffer, {\n  spaceId: 'space-id',\n  name: 'remote-file.pptx',\n});\n```\n\n典型工作流：先 `files.upload()` 获取 `fileId`，再 `docs.create()` 创建文档。\n\n## 分页\n\n列表接口返回 `ListResult<T>`：\n\n```typescript\ninterface ListResult<T> {\n  rows: T[];\n  count: number;\n}\n```\n\n分页参数：\n\n```typescript\nawait client.shares.list(undefined, { _startIndex: 0, _maxResults: 50 });\n```\n\n## 错误处理\n\nSDK 将 API 错误封装为 `APIError`：\n\n```typescript\nimport { APIError, isRetriableError } from '@caixuan-cc/sdk';\n\ntry {\n  await client.docs.get('invalid-id');\n} catch (err) {\n  if (err instanceof APIError) {\n    console.error(err.statusCode);    // HTTP 状态码\n    console.error(err.code);          // 业务错误码\n    console.error(err.requestId);     // 请求追踪 ID\n    console.error(err.requestUrl);    // 请求 URL\n    console.error(err.requestPayload);// 请求体\n  }\n\n  if (isRetriableError(err)) {\n    // 网络错误或 502/604，可重试\n  }\n}\n```\n\nSDK 内置对网络超时、502、604 等可重试错误的自动重试（指数退避）。\n\n401 未授权时，若配置了 `onUnauthorized` 回调，SDK 会自动刷新 Token 并重试请求。\n\n## 类型导出\n\n```typescript\nimport type {\n  CaixuanClient,\n  CreateCaixuanOptions,\n  MySpace,\n  SessionInfo,\n  ListResult,\n  CreateShareParams,\n  UpdateShareParams,\n  CreateDocParams,\n  AddMemberParams,\n  FileUploadResult,\n} from '@caixuan-cc/sdk';\n```\n\n## 许可证\n\n[MIT](../../LICENSE)\n","readmeFilename":"README.zh-CN.md"}