Corsair Timelink 插件使用指南接入预约排期平台实现类型安全的 deletePerson 操作【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair导读Timelink 是一个面向服务型企业的日程预约与排期平台。corsair-dev/timelink是 Corsair 生态中专门连接 Timelink 的官方插件包它把 Timelink 的 API 封装为一个类型安全的timelink.api.*调用入口并自动接入 Corsair 的多租户鉴权、凭据管理与错误处理体系。读完本文你将掌握该插件的安装方式、认证模型、唯一端点deletePerson.delete的完整用法以及插件底层请求封装、限流策略、Schema 校验与错误分类的实现原理。插件概览一个端点、一种鉴权、零 Webhook从 packages/timelink/README.md 可以看出这个插件的功能边界非常聚焦当前版本只暴露一个操作使用 API Key 鉴权并且不提供任何 Webhook。其核心信息整理如下操作操作 ID风险级别说明deletePerson.deletetimelink.api.deletePerson.deletedestructive按唯一标识删除一条人员记录风险级别destructive意味着该操作会真实删除远端数据调用前应谨慎确认参数。插件当前不注册任何 Webhook源码中webhooks: {}亦印证了这一点见 index.ts。在 Corsair 中插件的「操作」统一组织为资源.动作的嵌套结构。Timelink 插件将deletePerson视为资源、delete视为动作注册后的完整调用链为timelink.api.deletePerson.delete。安装与接入安装包使用 pnpm与仓库一致安装pnpm add corsair-dev/timelink也可以使用 npm / yarn / bun 安装corsair与corsair-dev/timelink两个包。根据 package.jsoncorsair-dev/timelink的 peerDependencies 要求corsair 0.1.0与zod ^4.1.13即运行时依赖 Corsair 核心与 Zod 校验库Zod 用于端点输入输出 Schema。注册插件在创建 Corsair 实例时传入插件工厂函数timelink()import Database from better-sqlite3; import { createCorsair } from corsair; import { timelink } from corsair-dev/timelink; export const corsair createCorsair({ plugins: [ timelink(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });上述示例来自 docs/plugins/timelink/overview.mdx其中kek与 Hub 相关密钥的获取方式见仓库 docs/quick-start.mdx租户隔离机制见 docs/concepts/multi-tenancy.mdx。连接租户Connect 流程Corsair 的多租户是默认行为。每个租户首次调用前需要完成连接通过corsair.manage.connect.createLink生成连接链接将租户浏览器引导到该页面完成凭据录入Hub 再把结果回传给你的应用const { connectUrl } await corsair.manage.connect.createLink({ plugin: timelink, tenantId: acme, }); // redirect the users browser to connectUrl连接流程的完整说明见 docs/management/connect.mdx。认证模型API Key 与首次使用提示Timelink 插件采用 API Key 鉴权README 中明确说明Corsair 会在租户首次使用时提示录入凭据API Key。从源码层面看这一行为由 index.ts 中的两处配置共同决定默认认证类型const defaultAuthType: AuthTypes api_key as const;插件工厂timelink()未显式传authType时默认使用api_key。认证配置timelinkAuthConfig将 API Key 关联到租户维度export const timelinkAuthConfig { api_key: { account: [tenant_external_id] as const, }, } as const satisfies PluginAuthConfig;这意味着 API Key 按「租户」粒度存储与取用不同租户可以各自绑定独立的 Timelink API Key实现账号隔离详见 docs/concepts/multi-tenancy.mdx 与 docs/concepts/api-key.mdx。KeyBuilder凭据的获取顺序插件工厂中内置了keyBuilder决定请求时如何取得 API KeykeyBuilder: async (ctx: TimelinkKeyBuilderContext, source) { if (source endpoint options.key) { return options.key; } if (source endpoint ctx.authType api_key) { const res await ctx.keys.get_api_key(); if (!res) { throw new AuthMissingError(timelink, api_key); } return res; } throw new AuthMissingError(timelink, api_key); },获取顺序为优先使用插件选项中的显式key→ 其次读取租户已保存的 API Key → 都没有则抛出AuthMissingError此时便会触发「首次使用提示租户录入凭据」的交互。AuthMissingError来自corsair/core是 Corsair 统一凭据缺失错误类型。插件选项timelink()工厂函数接受的可选参数如下类型定义见 index.ts 的TimelinkPluginOptions选项类型说明authTypePickAuthapi_key认证类型默认api_keykeystring显式指定 API Key优先于租户存储的 Keyhooks插件钩子透传给 Corsair 的插件生命周期钩子errorHandlersCorsairErrorHandler自定义错误处理器会与内置错误处理器合并permissionsPluginPermissionsConfig端点权限配置核心操作deletePerson.delete调用方式以acme租户为例删除一条人员记录const tenant corsair.withTenant(acme); await tenant.timelink.api.deletePerson.delete({ id: client-1 });输入与输出类型输入输出 Schema 由 Zod 定义见 endpoints/types.ts输入名称类型必填约束idstring是长度 ≥ 1必须是单个 URL 路径段const DeletePersonInputSchema z.object({ id: z .string() .min(1) .refine((id) !/[/?#]/.test(id) !/^\.{1,2}$/.test(id), { message: id must be a single URL path segment without delimiters or dot segments, }), });该校验禁止id中包含路径分隔符/、查询符?、#以及.、..等点段从入口处杜绝了 URL 路径穿越类风险。输出const DeletePersonResponseSchema z.object({ success: z.boolean(), data: z.object({ id: z.string(), }), });即返回{ success: boolean, data: { id: string } }形式的删除结果信封。端点实现会在返回前对响应做 Zod 解析TimelinkEndpointOutputSchemas.deletePerson.parse(response)响应结构不符合预期时会抛出校验错误防止异常数据结构向上游渗透。底层请求链路deletePerson.delete的实现位于 endpoints/delete-person.tsconst parsed TimelinkEndpointInputSchemas.deletePerson.parse(input); const response await makeTimelinkRequest( clients/${encodeURIComponent(parsed.id)}, ctx.key, { method: DELETE }, ); await logEventFromContext(ctx, timelink.delete.person, parsed, completed); return TimelinkEndpointOutputSchemas.deletePerson.parse(response);请求发送到 Timelink REST API 的clients/{id}路径id经encodeURIComponent编码为单个 URL 段随后通过logEventFromContext记录一条timelink.delete.person的 completed 审计事件。makeTimelinkRequest位于 client.ts其关键常量与行为如下Base URLhttps://api.timelink.io/api/v1TIMELINK_API_BASE。认证方式API Key 以TOKEN形式注入请求配置由corsair/http的request统一处理。请求头固定携带Content-Type: application/json。请求体规则仅POST/PUT/PATCH附带 JSON bodyDELETE不携带 bodyGET才透传 query 参数。错误包装所有失败统一包装为TimelinkAPIError保留status、retryAfter、body等字段status在非ApiError场景下为undefined。限流与错误处理为破坏性操作量身定制限流配置client.ts 中定义了专门的限流配置const TIMELINK_RATE_LIMIT_CONFIG: RateLimitConfig { enabled: true, maxRetries: 0, initialRetryDelay: 1000, backoffMultiplier: 2, headerNames: { retryAfter: Retry-After, }, };值得注意的设计细节deletePerson是非幂等的 DELETE 请求若在传输层对 429 响应做自动重试可能造成「服务端已处理、客户端又重放一次」的双重删除。因此该插件把maxRetries设为 0禁用嵌套重试改为由错误处理器error-handlers.ts负责对限流响应进行分类处理。错误分类内置错误处理器实现了三类匹配分类匹配条件处理策略RATE_LIMIT_ERRORHTTP 429或消息含rate_limited/429返回maxRetries: 0并透传Retry-After若有AUTH_ERRORHTTP 401或消息含unauthorized/invalid_auth返回maxRetries: 0DEFAULT兜底匹配所有错误返回maxRetries: 0同时插件工厂会把用户传入的自定义errorHandlers与内置处理器合并...errorHandlers, ...options.errorHandlers允许按需覆盖默认行为。关于 Corsair 错误处理机制的通用说明可参考 docs/concepts/error-handling.mdx。数据模型当前无持久化实体插件的 Schema 定义在 schema/index.tsexport const TimelinkSchema { version: 1.0.0, entities: {}, } as const;schema/database.ts 中的注释也明确指出当前这个仅包含 deletePerson 操作的插件还没有需要持久化的数据库实体。这意味着插件不依赖数据库表结构Corsair 仅需存储租户的 API Key 凭据即可运行。测试覆盖行为即文档仓库为该插件提供了三组 Jest 测试可以作为理解其行为的补充依据client.test.ts验证makeTimelinkRequest的 Base URL 与 Bearer Token 注入、GET 默认行为与 query 透传、仅写方法携带 body、DELETE 不携带 body、成功时返回解析结果以及ApiError→TimelinkAPIError的错误包装保留 status。endpoints.test.ts验证deletePerson发送DELETE clients/{id}并携带认证头、id含空格时被编码为client%201、../accounts/.././123?targetother/123#fragment/ 空串等非法id会被 Schema 拒绝且不会发出请求、响应结构不符合删除信封时抛出异常同时断言logEventFromContext会以timelink.delete.person事件名记录完成日志。schema.test.ts覆盖 Schema 本身。许可证与更多资源corsair-dev/timelink采用 Apache-2.0 许可证见 package.json。插件的展示名称与描述在 plugin-docs.yaml 中维护Timelink 被定位为「面向服务型企业的日程预约与排期平台以及日历协调工具」。本插件对应的完整文档还包括docs/plugins/timelink/overview.mdx安装、插件注册、租户连接与示例调用docs/plugins/timelink/api.mdxtimelink.api.*全部操作的输入输出类型参考docs/plugins/timelink/database.mdx数据库相关说明通用概念docs/concepts/auth.mdx、docs/concepts/api.mdx、docs/concepts/api-key.mdx若需将该插件的操作暴露为 MCP 工具供 Agent 调用可参考 docs/mcp-adapters/mcp-adapters.mdx。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Corsair Timelink 插件使用指南接入预约排期平台实现类型安全的 deletePerson 操作【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair导读Timelink 是一个面向服务型企业的日程预约与排期平台。corsair-dev/timelink是 Corsair 生态中专门连接 Timelink 的官方插件包它把 Timelink 的 API 封装为一个类型安全的timelink.api.*调用入口并自动接入 Corsair 的多租户鉴权、凭据管理与错误处理体系。读完本文你将掌握该插件的安装方式、认证模型、唯一端点deletePerson.delete的完整用法以及插件底层请求封装、限流策略、Schema 校验与错误分类的实现原理。插件概览一个端点、一种鉴权、零 Webhook从 packages/timelink/README.md 可以看出这个插件的功能边界非常聚焦当前版本只暴露一个操作使用 API Key 鉴权并且不提供任何 Webhook。其核心信息整理如下操作操作 ID风险级别说明deletePerson.deletetimelink.api.deletePerson.deletedestructive按唯一标识删除一条人员记录风险级别destructive意味着该操作会真实删除远端数据调用前应谨慎确认参数。插件当前不注册任何 Webhook源码中webhooks: {}亦印证了这一点见 index.ts。在 Corsair 中插件的「操作」统一组织为资源.动作的嵌套结构。Timelink 插件将deletePerson视为资源、delete视为动作注册后的完整调用链为timelink.api.deletePerson.delete。安装与接入安装包使用 pnpm与仓库一致安装pnpm add corsair-dev/timelink也可以使用 npm / yarn / bun 安装corsair与corsair-dev/timelink两个包。根据 package.jsoncorsair-dev/timelink的 peerDependencies 要求corsair 0.1.0与zod ^4.1.13即运行时依赖 Corsair 核心与 Zod 校验库Zod 用于端点输入输出 Schema。注册插件在创建 Corsair 实例时传入插件工厂函数timelink()import Database from better-sqlite3; import { createCorsair } from corsair; import { timelink } from corsair-dev/timelink; export const corsair createCorsair({ plugins: [ timelink(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });上述示例来自 docs/plugins/timelink/overview.mdx其中kek与 Hub 相关密钥的获取方式见仓库 docs/quick-start.mdx租户隔离机制见 docs/concepts/multi-tenancy.mdx。连接租户Connect 流程Corsair 的多租户是默认行为。每个租户首次调用前需要完成连接通过corsair.manage.connect.createLink生成连接链接将租户浏览器引导到该页面完成凭据录入Hub 再把结果回传给你的应用const { connectUrl } await corsair.manage.connect.createLink({ plugin: timelink, tenantId: acme, }); // redirect the users browser to connectUrl连接流程的完整说明见 docs/management/connect.mdx。认证模型API Key 与首次使用提示Timelink 插件采用 API Key 鉴权README 中明确说明Corsair 会在租户首次使用时提示录入凭据API Key。从源码层面看这一行为由 index.ts 中的两处配置共同决定默认认证类型const defaultAuthType: AuthTypes api_key as const;插件工厂timelink()未显式传authType时默认使用api_key。认证配置timelinkAuthConfig将 API Key 关联到租户维度export const timelinkAuthConfig { api_key: { account: [tenant_external_id] as const, }, } as const satisfies PluginAuthConfig;这意味着 API Key 按「租户」粒度存储与取用不同租户可以各自绑定独立的 Timelink API Key实现账号隔离详见 docs/concepts/multi-tenancy.mdx 与 docs/concepts/api-key.mdx。KeyBuilder凭据的获取顺序插件工厂中内置了keyBuilder决定请求时如何取得 API KeykeyBuilder: async (ctx: TimelinkKeyBuilderContext, source) { if (source endpoint options.key) { return options.key; } if (source endpoint ctx.authType api_key) { const res await ctx.keys.get_api_key(); if (!res) { throw new AuthMissingError(timelink, api_key); } return res; } throw new AuthMissingError(timelink, api_key); },获取顺序为优先使用插件选项中的显式key→ 其次读取租户已保存的 API Key → 都没有则抛出AuthMissingError此时便会触发「首次使用提示租户录入凭据」的交互。AuthMissingError来自corsair/core是 Corsair 统一凭据缺失错误类型。插件选项timelink()工厂函数接受的可选参数如下类型定义见 index.ts 的TimelinkPluginOptions选项类型说明authTypePickAuthapi_key认证类型默认api_keykeystring显式指定 API Key优先于租户存储的 Keyhooks插件钩子透传给 Corsair 的插件生命周期钩子errorHandlersCorsairErrorHandler自定义错误处理器会与内置错误处理器合并permissionsPluginPermissionsConfig端点权限配置核心操作deletePerson.delete调用方式以acme租户为例删除一条人员记录const tenant corsair.withTenant(acme); await tenant.timelink.api.deletePerson.delete({ id: client-1 });输入与输出类型输入输出 Schema 由 Zod 定义见 endpoints/types.ts输入名称类型必填约束idstring是长度 ≥ 1必须是单个 URL 路径段const DeletePersonInputSchema z.object({ id: z .string() .min(1) .refine((id) !/[/?#]/.test(id) !/^\.{1,2}$/.test(id), { message: id must be a single URL path segment without delimiters or dot segments, }), });该校验禁止id中包含路径分隔符/、查询符?、#以及.、..等点段从入口处杜绝了 URL 路径穿越类风险。输出const DeletePersonResponseSchema z.object({ success: z.boolean(), data: z.object({ id: z.string(), }), });即返回{ success: boolean, data: { id: string } }形式的删除结果信封。端点实现会在返回前对响应做 Zod 解析TimelinkEndpointOutputSchemas.deletePerson.parse(response)响应结构不符合预期时会抛出校验错误防止异常数据结构向上游渗透。底层请求链路deletePerson.delete的实现位于 endpoints/delete-person.tsconst parsed TimelinkEndpointInputSchemas.deletePerson.parse(input); const response await makeTimelinkRequest( clients/${encodeURIComponent(parsed.id)}, ctx.key, { method: DELETE }, ); await logEventFromContext(ctx, timelink.delete.person, parsed, completed); return TimelinkEndpointOutputSchemas.deletePerson.parse(response);请求发送到 Timelink REST API 的clients/{id}路径id经encodeURIComponent编码为单个 URL 段随后通过logEventFromContext记录一条timelink.delete.person的 completed 审计事件。makeTimelinkRequest位于 client.ts其关键常量与行为如下Base URLhttps://api.timelink.io/api/v1TIMELINK_API_BASE。认证方式API Key 以TOKEN形式注入请求配置由corsair/http的request统一处理。请求头固定携带Content-Type: application/json。请求体规则仅POST/PUT/PATCH附带 JSON bodyDELETE不携带 bodyGET才透传 query 参数。错误包装所有失败统一包装为TimelinkAPIError保留status、retryAfter、body等字段status在非ApiError场景下为undefined。限流与错误处理为破坏性操作量身定制限流配置client.ts 中定义了专门的限流配置const TIMELINK_RATE_LIMIT_CONFIG: RateLimitConfig { enabled: true, maxRetries: 0, initialRetryDelay: 1000, backoffMultiplier: 2, headerNames: { retryAfter: Retry-After, }, };值得注意的设计细节deletePerson是非幂等的 DELETE 请求若在传输层对 429 响应做自动重试可能造成「服务端已处理、客户端又重放一次」的双重删除。因此该插件把maxRetries设为 0禁用嵌套重试改为由错误处理器error-handlers.ts负责对限流响应进行分类处理。错误分类内置错误处理器实现了三类匹配分类匹配条件处理策略RATE_LIMIT_ERRORHTTP 429或消息含rate_limited/429返回maxRetries: 0并透传Retry-After若有AUTH_ERRORHTTP 401或消息含unauthorized/invalid_auth返回maxRetries: 0DEFAULT兜底匹配所有错误返回maxRetries: 0同时插件工厂会把用户传入的自定义errorHandlers与内置处理器合并...errorHandlers, ...options.errorHandlers允许按需覆盖默认行为。关于 Corsair 错误处理机制的通用说明可参考 docs/concepts/error-handling.mdx。数据模型当前无持久化实体插件的 Schema 定义在 schema/index.tsexport const TimelinkSchema { version: 1.0.0, entities: {}, } as const;schema/database.ts 中的注释也明确指出当前这个仅包含 deletePerson 操作的插件还没有需要持久化的数据库实体。这意味着插件不依赖数据库表结构Corsair 仅需存储租户的 API Key 凭据即可运行。测试覆盖行为即文档仓库为该插件提供了三组 Jest 测试可以作为理解其行为的补充依据client.test.ts验证makeTimelinkRequest的 Base URL 与 Bearer Token 注入、GET 默认行为与 query 透传、仅写方法携带 body、DELETE 不携带 body、成功时返回解析结果以及ApiError→TimelinkAPIError的错误包装保留 status。endpoints.test.ts验证deletePerson发送DELETE clients/{id}并携带认证头、id含空格时被编码为client%201、../accounts/.././123?targetother/123#fragment/ 空串等非法id会被 Schema 拒绝且不会发出请求、响应结构不符合删除信封时抛出异常同时断言logEventFromContext会以timelink.delete.person事件名记录完成日志。schema.test.ts覆盖 Schema 本身。许可证与更多资源corsair-dev/timelink采用 Apache-2.0 许可证见 package.json。插件的展示名称与描述在 plugin-docs.yaml 中维护Timelink 被定位为「面向服务型企业的日程预约与排期平台以及日历协调工具」。本插件对应的完整文档还包括docs/plugins/timelink/overview.mdx安装、插件注册、租户连接与示例调用docs/plugins/timelink/api.mdxtimelink.api.*全部操作的输入输出类型参考docs/plugins/timelink/database.mdx数据库相关说明通用概念docs/concepts/auth.mdx、docs/concepts/api.mdx、docs/concepts/api-key.mdx若需将该插件的操作暴露为 MCP 工具供 Agent 调用可参考 docs/mcp-adapters/mcp-adapters.mdx。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
