Truto Link SDK 用于在前端应用中嵌入 Truto 连接 UI，让终端用户连接自己的第三方账号。适用场景是需要把第三方账号连接流程集成进网页应用的前端开发者。
主要能力
@truto/truto-link-sdk 是一个浏览器端 JavaScript 库，用于打开 Truto 连接 UI。它可在任意前端框架中使用（React、Vue、Svelte、原生 JS），因为它是一个普通 ES 模块，不依赖特定框架。
它提供三项能力：
- authenticate —— 打开连接流程，让终端用户关联第三方账号。
- rapidForm —— 在连接完成后打开后置配置表单。
- showFilePicker —— 打开原生云端文件选择器（Google Drive、SharePoint、OneDrive、Box、Dropbox）。
安装
npm install @truto/truto-link-sdk
前置条件
在前端使用 SDK 之前，后端必须生成 link token。Truto API token 是机密信息，绝不能暴露给浏览器。后端路由示例以 fetch 调用 https://api.truto.one/link-token，并在 Authorization 头中携带 Bearer 形式的 TRUTO_API_TOKEN，请求体包含 tenant_id，响应中取出 link_token 返回给前端。
tenant_id 用于标识租户，即该账号所属的客户/工作区。任何 URL 路径安全的字符串都可以（如 user_1a2b3c、acme-corp 等）。账号连接时 Truto 会自动创建租户，也可以在连接前通过 POST /tenant 预创建租户，以便附加元数据。
使用方式
前端从后端接口获取 linkToken 后调用 authenticate(linkToken)，成功时返回包含 integrated_account_id 和 integration 的对象；失败时若值为字符串 "closed" 表示用户关闭了对话框，其他错误则输出错误信息。
authenticate(linkToken, options?) 打开 Truto Link UI，供终端用户选择集成并进行认证。返回 Promise<{ integrated_account_id: string; integration: string }>；若 sameWindow 为 true 则不返回 Promise。
选项包括：integration（预选特定集成，跳过选择器）、integrations（仅将选择器限制为这些集成）、iframe（默认 true，使用全屏 iframe 覆盖层；设为 false 则使用弹窗）、sameWindow（默认 false，导航当前页面而非 iframe/弹窗，需配合 link token 上的 redirect_uri 使用，不返回 Promise）、noBack（默认 false，隐藏集成认证界面上的返回按钮）、authFormat（强制指定认证流程：api_key、oauth2、oauth2_client_credentials、keka_oauth）、skipRapidForm（默认 false，即使配置了 RapidForm 也跳过连接后表单）、baseUrl（默认 https://app.truto.one，可覆盖 Truto 应用 URL）、width（弹窗宽度，默认 700，仅当 iframe: false）、height（弹窗高度，默认 800，仅当 iframe: false）。
展示模式
Iframe（默认）：iframe: true，在 document.body 上显示全屏覆盖层，用户内联完成连接。 弹窗：iframe: false，打开新浏览器窗口，适用于 iframe 受限制的情况。 同窗口：sameWindow: true，导航当前页面，不返回 Promise，需在 link token 上设置 redirect_uri。
错误处理
拒绝值类型与含义："closed"（字符串，用户关闭对话框而未连接）、"blocked"（字符串，浏览器拦截了弹窗）、带 error_type 的 Error（来自 Truto 的连接错误）。error_type 取值包括：invalid_token、invalid_integration、connection_error、post_install_error、validation_error。Error 对象上还有附加属性：err.integration（集成名称）、err.integrated_account_id（若错误发生前账号已创建）。
预选集成
可通过 authenticate(linkToken, { integration: "hubspot" }) 跳过选择器直接进入指定集成认证；也可通过 integrations: ["hubspot", "salesforce", "pipedrive"] 将选择器限制为特定集成。
框架集成
SDK 是普通 ES 模块，以下仅为轻量封装而非独立包：React 可使用 useTrutoLink hook，内部管理 pending 与 error 状态，调用后端获取 linkToken 后执行 authenticate；Vue 3 提供对应 composable；Svelte 提供 action，通过 trutoConnected 和 trutoError 自定义事件回传结果。上述前端方案均调用同一个后端路由，Express、Next.js Route Handlers 及 Hono / Cloudflare Workers 的该路由变体可参阅 Truto skill 的 Getting Started 第 5 步。
适用场景与限制
适用于需要在浏览器前端嵌入第三方账号连接流程的应用，支持通过预选或限制集成来控制用户可选范围，并支持 iframe、弹窗、同窗口三种展示方式。限制方面：库为仅浏览器端使用；必须由后端生成 link token，API token 不得暴露给浏览器；sameWindow 模式不返回 Promise，需配合 redirect_uri 使用。