Corsair × BoloForms 插件接入指南以 API Key 认证实现文档列表查询与本地数据同步【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairBoloFormsBoloForms Signature是一款在线表单/电子签名平台支持调查问卷、申请表、潜在客户收集等带工作流能力的业务场景。本文以 packages/boloforms/README.md 为核心骨架结合packages/boloforms/源码与docs/plugins/boloforms/文档讲解如何在 Corsair 中接入 BoloForms 插件、完成租户 API Key 认证、调用documents.list查询工作区文档并利用同步实体在本地数据库进行检索。读完本文你将掌握从安装、配置、连接租户到真实调用与排错的完整链路。插件速览corsair-dev/boloforms是 Corsair 的 BoloForms 插件包遵循 Corsair 统一的插件模型一个插件 认证配置authConfig 本地数据库 Schemaschema 一组类型安全的端点endpoints 错误处理策略。从 packages/boloforms/index.ts 可以看到插件核心定义export type BoloformsPluginOptions { /** Authentication method. BoloForms Signature only supports API keys. */ authType?: PickAuthapi_key; /** * BoloForms API key, sent as the x-api-key header. When omitted the key * is resolved from the account key manager instead. */ key?: string; hooks?: InternalBoloformsPlugin[hooks]; errorHandlers?: CorsairErrorHandler; permissions?: PluginPermissionsConfigtypeof boloformsEndpointsNested; };当前版本提供1 个类型化 API 操作与1 个同步实体能力内容来源类型化 API 操作boloforms.api.documents.listendpoints/index.ts本地同步实体documents支持.search()/.list()schema/index.ts认证方式BoloForms 仅支持API Key认证对应 HTTP 层为x-api-key请求头。packages/boloforms/README.md中明确说明Auth: API key. Corsair prompts your tenant for credentials on first use.即 Corsair 会在租户首次调用时引导其录入凭据无需你在插件初始化阶段手动配置密钥。底层认证配置在 index.tsexport const boloformsAuthConfig { api_key: { account: [tenant_external_id] as const, }, } as const satisfies PluginAuthConfig;Webhooks当前插件不提供任何 Webhook插件对象中的webhooks: {}与pluginWebhookMatcher: undefined表明未接入推送事件参见 index.ts。许可证corsair-dev/boloforms以Apache-2.0许可证发布。安装插件使用 pnpm 安装pnpm add corsair-dev/boloforms也可以使用 npm、yarn 或 bun与 Corsair 本体一并安装npm install corsair corsair-dev/boloformsyarn add corsair corsair-dev/boloformsbun add corsair corsair-dev/boloforms插件包由 tsup 构建见 tsup.config.ts构建产物通过包的exports字段暴露可直接在 Node.js 与打包器环境中使用。在 Corsair 应用中注册插件参照 docs/plugins/boloforms/overview.mdx 的 Setup 步骤创建一个corsair.tsimport Database from better-sqlite3; import { createCorsair } from corsair; import { boloforms } from corsair-dev/boloforms; export const corsair createCorsair({ plugins: [ boloforms(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });要点说明database使用better-sqlite3创建的本地数据库文件如corsair.db插件同步的documents实体将持久化于此kekCorsair 的密钥加密密钥Key Encryption Key用于加密租户凭据务必从环境变量注入而非硬编码hubprojectApiKey与signingSecret用于连接 Corsair Hub托管连接页、投递凭据结果完整说明见 docs/quick-start.mdx多租户是默认行为通过corsair.withTenant(id)限定调用范围租户间数据与凭据相互隔离详见 docs/concepts/multi-tenancy.mdx。选择认证方式BoloForms 目前仅支持 API Key无需在初始化时做任何配置boloforms()当你作为租户发起第一次请求时Corsair 会自动提示录入 API Key。相关概念见 docs/concepts/api-key.mdx。当然如果希望由服务端统一管理密钥而非由租户各自录入也可以在插件选项中显式传入boloforms({ key: process.env.BOLOFORMS_API_KEY! })从 index.ts 的keyBuilder实现可见其优先级当调用来源为endpoint且显式传入了options.key时直接返回否则走ctx.keys?.get_api_key()从 Corsair 的账户密钥管理器读取两者都取不到时抛出AuthMissingError(boloforms, api_key)。这也印证了 README 中“Corsair prompts your tenant for credentials on first use”的行为。连接租户插件注册完成后为租户生成一个连接链接Connect Link将租户引导至 Corsair Hub 页面完成凭据录入Hub 再通过回调把结果投递回你的应用const { connectUrl } await corsair.manage.connect.createLink({ plugin: boloforms, tenantId: acme, }); // redirect the users browser to connectUrl租户连接后corsair.withTenant(acme)即可使用该租户的凭据调用 BoloForms API。连接流程的详细说明见 docs/management/connect.mdx。调用 documents.list 查询文档端点与底层映射documents.list是当前插件唯一暴露的端点其 Operation ID 为boloforms.api.documents.list风险等级为read只读操作无写副作用描述为 “Retrieve a list of documents from a Boloforms workspace, with optional filtering and pagination”。端点在 index.ts 中注册const boloformsEndpointsNested { documents: { list: Documents.list, }, } as const; export const boloformsEndpointSchemas { documents.list: { input: BoloformsEndpointInputSchemas.getDocumentsList, output: BoloformsEndpointOutputSchemas.getDocumentsList, }, } as const; const boloformsEndpointMeta { documents.list: { riskLevel: read, description: Retrieve a list of documents from a Boloforms workspace, with optional filtering and pagination, }, } as const;其底层调用的是 BoloForms Signature 的GET /signature/get-documents接口见 endpoints/documents.ts请求头同时携带x-api-key与workspaceid。调用示例const tenant corsair.withTenant(acme); await tenant.boloforms.api.documents.list({});传入查询参数时如分页await tenant.boloforms.api.documents.list({ workspaceId: ws-xxx, page: 1, limit: 10, });注意workspaceId是必填的输入字段其余参数均为可选。输入参数详解以下参数表来自 docs/plugins/boloforms/api.mdx与 endpoints/types.ts 中的 Zod Schema 完全一致名称类型必填说明workspaceIdstring是BoloForms 工作区 ID作为workspaceid请求头发送querystring否查询关键词sortOrderstring否排序方向limitstring否单页条数documentIdstring否按文档 ID 过滤dateTostring否截止日期过滤dateFromstring否起始日期过滤pagestring否页码sortBystring否排序字段filterstring否过滤器注意除workspaceId外的分页/过滤参数均为string类型符合 BoloForms OpenAPI 的 query 传参约定。输出结构documents.list的返回结构同样经 Zod 校验见 endpoints/types.ts名称类型必填说明documentsobject[]是文档列表messagestring否接口消息formCountnumber否表单数量documentsCountnumber否文档数量paginationobject否OpenAPI 分页信息documents[]中单个文档的完整类型见 schema/database.ts{ documentId: string, name?: string, documentName?: string, status?: string, signingType?: string, createdAt?: string, updatedAt?: string }[]pagination的完整类型{ currentPage?: number, totalPages?: number, totalDocuments?: number }值得注意的是响应 Schema 通过.passthrough()保留了未声明的额外字段同时源码注释表明真实GET /signature/get-documents响应中常常省略pagination块而是改用documentsCount/formCount表达数量信息——BoloformsDocumentsPagination是对官方 OpenAPI 分页结构的兼容性定义。字段细节name 与 documentNameBoloformsDocument同时声明了name与documentName两个可选字段官方 OpenAPI 的DocumentsResponse.documents[]只声明documentId, name, createdAt, status而真实接口返回中还包含documentNamesigningType则是发送签署的类型判别字段FORM_TEMPLATE或PDF_TEMPLATE。这些兼容性处理使得 Schema 既能通过官方文档校验也能接受线上真实响应。底层请求实现与错误处理HTTP 客户端所有 BoloForms 请求都经由 client.ts 的makeBoloformsRequest发出它基于corsair/http的request构建 OpenAPI 配置基础地址https://sapi.boloforms.com对应 OpenAPI Server URLhttps://sapi.boloforms.com/signature请求头Content-Type: application/json、Accept: application/json、x-api-key: apiKey、workspaceid: workspaceIdGET 请求将query参数附加到 URLPOST/PUT/PATCH 请求将body以 JSON 发送内置限流重试配置enabled: true、maxRetries: 3、initialRetryDelay: 1000毫秒、backoffMultiplier: 2指数退避、retryAfter: Retry-After响应头识别。任何ApiError都会被包装为BoloformsAPIError携带status、statusText、body、retryAfter便于上层统一识别。错误处理策略error-handlers.ts 定义了三类错误处理RATE_LIMIT_ERROR命中 429 或消息含rate_limited/429时触发最多重试5 次并优先采用服务端Retry-After头指定等待时间AUTH_ERROR命中 401/403 或消息含unauthorized/forbidden/invalid_auth时触发不重试注意BoloForms 真实接口对无效密钥返回的是 403 而非 401DEFAULT兜底策略不重试。这些内置错误处理可通过插件选项errorHandlers覆盖或扩展boloforms({ errorHandlers: { // 自定义错误处理器 }, });本地数据库同步与查询插件将documents实体同步到 Corsair 本地数据库Schema 见 schema/index.tsexport const BoloformsSchema { version: 1.0.0, entities: { documents: BoloformsDocument, }, } as const;同步后即可对本地数据执行快速查询const tenant corsair.withTenant(acme); // 搜索 await tenant.boloforms.db.documents.search({ /* 过滤条件 */ }); // 列表 await tenant.boloforms.db.documents.list({ /* 过滤条件 */ });documents实体的字段、过滤条件与操作符说明详见 docs/plugins/boloforms/database.mdx。测试验证与行为佐证插件行为由 api.test.ts 与 schema.test.ts 双重保障测试覆盖了Schema 校验BoloformsSchema.version符合 semverdocuments实体可从官方文档结构解析出documentId请求构造documents.list会以(signature/get-documents, KEY, WORKSPACE, { method: GET, query: {...} })的形式调用makeBoloformsRequest并记录事件boloforms.documents.list状态completed分页兼容响应含 OpenAPIpagination块时也能正确解析错误传播客户端错误会原样向上抛出认证解析keyBuilder在显式传入options.key时直接返回从密钥管理器读取到 API Key 时正常返回读取为空时抛出AuthMissingError。此外 docs/plugins/boloforms/api.mdx 提供了完整的参数与类型参考docs/plugins/boloforms/overview.mdx 给出了从安装到查询的端到端指引。在 Agent 中暴露插件能力插件注册后其操作可通过 MCP 适配层暴露为 MCP 工具供 Agent如 Claude、Cursor 等调用。相关接入方法见 docs/mcp-adapters/mcp-adapters.mdx 及各框架适配器文档LangChain 适配器LlamaIndex 适配器Mastra 适配器以及 docs/getting-started/set-up-with-your-agent.mdx 的 Agent 接入快速上手。小结通过 Corsair 接入 BoloForms你可以用统一、类型安全的方式完成以下工作用pnpm add corsair-dev/boloforms安装插件并在createCorsair中注册boloforms()租户首次调用时录入 API KeyCorsair 负责密钥的安全存储与管理x-api-keyworkspaceid请求头由 client.ts 自动构造调用tenant.boloforms.api.documents.list({ workspaceId, ... })查询工作区文档支持关键词、日期、分页、排序等过滤通过本地同步的documents实体执行.search()/.list()离线快速检索内置限流退避重试与认证错误处理异常情况由BoloformsAPIError统一承载。当前插件仅提供只读的文档列表能力且无 Webhook若需要写入或推送事件能力可关注后续版本或结合 docs/plugins/boloforms/api.mdx 中的操作列表评估其他端点。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
