Corsair AMcards 插件接入指南用 10 个类型安全的 API 调用打通自动化实体贺卡邮寄【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairCorsair 是一个面向多租户场景的第三方应用连接框架而corsair-dev/amcards是它官方提供的 AMcards 集成插件。AMcards 是自动化贺卡平台支持向真实地址邮寄个性化实体贺卡。本文将围绕该插件的完整接入流程展开从安装、租户授权到 10 个类型安全的amcards.api.*操作、5 个本地同步实体与检索过滤器再到底层的请求封装、限流与错误处理实现帮助你在自己的 Agent 或后端服务中快速落地替用户发送实体贺卡的能力。插件概览一个插件两套能力corsair-dev/amcards插件围绕 AMcards 官方 API v1Django REST / Tastypie 风格封装出两层能力10 个类型安全的 API 操作cards.list、categories.get/list、contacts.list、gifts.get/list、schema.getApi/getCategory、templates.get/list全部标注为read风险级别5 个本地同步实体cards、categories、contacts、gifts、templates数据同步到本地数据库后可通过.search()/.list()快速检索。在插件文档overview.mdx中它被定义为Automated greeting card platform for sending personalized physical mail campaigns自动化实体贺卡邮寄平台。安装与初始化安装依赖使用pnpm安装插件Corsair 插件采用 workspace 级 peerDependencies 设计需要corsair 0.1.0与zod ^4.1.13见 package.jsonpnpm add corsair corsair-dev/amcards仓库示例与插件本身均使用pnpm工作区pnpm-workspace.yaml若使用 npm/yarn/bun 同样支持npm install corsair corsair-dev/amcards # 或 yarn add corsair corsair-dev/amcards # 或 bun add corsair corsair-dev/amcards注册插件在创建 Corsair 实例时传入amcards()工厂函数import Database from better-sqlite3; import { createCorsair } from corsair; import { amcards } from corsair-dev/amcards; export const corsair createCorsair({ plugins: [ amcards(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });要点说明database为本地数据库实例AMcards 同步数据会持久化到其中kekKey Encryption Key与hub配置用于凭证加密与连接流程可参考 quick-start.mdx 与 multi-tenancy.mdx多租户是默认行为后续所有调用需通过corsair.withTenant(id)划定租户作用域。从源码看amcards()工厂index.ts默认将authType收敛为api_key并返回一个满足CorsairPlugin契约的插件对象包含id: amcards、authConfig、schema、10 个 endpoint、Zod 输入输出 schema、endpointMeta每个操作的风险级别与描述以及自定义的keyBuilder。认证方式API Key推荐AMcards 插件只支持API Key即 AMcards 的 API Access Token这一种认证方式不支持 OAuth。首次以某个租户身份发起请求时Corsair 会提示为该租户录入 API Key见 api-key.mdx凭证由租户维度的密钥管理器托管调用时无需在业务代码中显式携带 Token。底层认证实现keyBuilderindex.ts的逻辑是仅接受source endpoint的调用场景否则抛出AuthMissingError(amcards, api_key)若插件选项里显式传入了key直接使用否则从ctx.keys.get_api_key()解析租户的 API Key取不到同样抛出AuthMissingError。认证配置amcardsAuthConfigindex.ts将api_key的账户作用域声明为[tenant_external_id]即密钥按租户外部 ID 隔离存储。Token 的发送方式底层 HTTP 层client.ts使用 Django REST 风格的 TokenAuthenticationAuthorization: Token api_access_token源码注释明确说明OpenAPIConfig.TOKEN有意保持未设置以避免共享传输层自动发出Authorization: Bearer头。每次请求还会固定携带Accept: application/json与Content-Type: application/json。全部端点一览插件 READMEREADME.md给出了 10 个端点的官方总览全部为read风险级别操作操作 ID风险描述cards.listamcards.api.cards.listread列出当前账户的贺卡categories.getamcards.api.categories.getread按 id 获取卡片模板分类categories.listamcards.api.categories.listread按优先级顺序列出卡片模板分类contacts.listamcards.api.contacts.listread列出联系人可按姓名或邮箱过滤gifts.getamcards.api.gifts.getread按 id 获取礼物gifts.listamcards.api.gifts.listread列出可用礼物schema.getApiamcards.api.schema.getApiread获取 AMcards API v1 schema资源映射schema.getCategoryamcards.api.schema.getCategoryread获取只读的 Category 资源 schematemplates.getamcards.api.templates.getread按 id 获取公开卡片模板templates.listamcards.api.templates.listread列出公开卡片模板这 10 个端点与 index.ts 中的amcardsEndpointsNested一一对应在运行时以嵌套命名空间暴露为tenant.amcards.api.resource.action()。端点详解与调用示例以下所有调用均基于const tenant corsair.withTenant(acme)获取的租户作用域对象。每个操作的输入输出 Schema 定义在 endpoints/types.ts底层 HTTP 映射在 endpoints/handlers.ts。cards.list — 列出账户贺卡await tenant.amcards.api.cards.list({});输入参数均可选名称类型描述skipnumber跳过的行数对应 Tastypie/DRF 的offsetlimitnumber每页大小输出{ id: number | string }数组或带count/next/previous/results/meta/objects的分页包装结构。categories.get / categories.list — 模板分类按 id 获取单个分类await tenant.amcards.api.categories.get({ category_id: 9 });category_id为必填的正整数。分类字段包括id、title、priority1 为最高优先级、parent、hierarchy。列出分类支持多级筛选await tenant.amcards.api.categories.list({ parent__id: 3, // 按父分类 id 筛子分类 title__icontains: birthday, // 标题大小写不敏感搜索 parent__title__icontains: holiday, // 父标题大小写不敏感搜索 });contacts.list — 联系人列表await tenant.amcards.api.contacts.list({ email: adaexample.com, first_name: Ada, last_name: Lovelace, skip: 0, limit: 50, });联系人字段id、first_name、last_name、email、created_at、updated_at。handler 会把这些参数原样映射为 AMcards 的email、first_name、last_name查询参数见 handlers.ts。gifts.get / gifts.list — 礼物无需认证即可访问的公开资源。handler 通过auth: false省略 Token 头handlers.ts。await tenant.amcards.api.gifts.get({ id: 3 }); await tenant.amcards.api.gifts.list({});礼物字段id、name、description、price、shipping_cost、available、availability其中price/shipping_cost兼容字符串或数字两种返回形式。templates.get / templates.list — 公开卡片模板同为公开资源auth: false可按分类或名称模糊搜索await tenant.amcards.api.templates.get({ id: 4 }); await tenant.amcards.api.templates.list({ category__id: 9, // 按分类 id 过滤 name__icontains: thanks, // 模板名大小写不敏感搜索 });模板字段id、name、category、configuration、panels、metadata后四者为任意结构。schema.getApi / schema.getCategory — 获取 API schema两个 schema 端点返回的是描述性元数据常用于动态发现 API 结构await tenant.amcards.api.schema.getApi({}); // API v1 资源映射 await tenant.amcards.api.schema.getCategory({}); // Category 资源 schemagetApi对应GET /api/v1/DRF/Tastypie API rootgetCategory对应GET /api/v1/categories/schema/。租户连接流程插件 README 明确标注Auth: API key. Corsair prompts your tenant for credentials on first use具体落地为业务后端调用corsair.manage.connect.createLink生成连接链接参考 connect.mdxconst { connectUrl } await corsair.manage.connect.createLink({ plugin: amcards, tenantId: acme, }); // 将用户浏览器重定向到 connectUrl用户在 Corsair Hub 托管的页面上录入 AMcards API Access TokenHub 将结果投递回你的应用此后该租户的所有amcards.*调用自动携带凭证无需再次录入。Webhooks当前无支持插件 README 明确说明No webhooks。源码层面也印证了这一点index.ts 中webhooks: {}为空对象、webhookHooks: undefined、pluginWebhookMatcher: undefined。因此该插件目前是纯拉取模型API 调用 本地同步不提供任何入站事件推送。本地同步数据与检索插件将cards、categories、contacts、gifts、templates五个实体同步到本地数据库实体字段定义在 schema/database.ts字段命名遵循 AMcards API v1 的 snake_case 约定并使用.loose()保留响应中的额外键。每个实体都支持tenant.amcards.db.entity.search()与.list()完整过滤器见 database.mdxconst rows await tenant.amcards.db.contacts.search({ data: { first_name: { equals: Ada } }, limit: 100, offset: 0, });各实体的可检索字段与操作符汇总实体可检索字段支持操作符cardsentity_idequals, contains, startsWith, endsWith, incategoriesentity_id,title,priority字符串类equals, contains, startsWith, endsWith, inprioritynumberequals, gt, gte, lt, lte, incontactsentity_id,first_name,last_name,email,created_at,updated_atequals, contains, startsWith, endsWith, ingiftsentity_id,name,description,available字符串类同上availablebooleanequalstemplatesentity_id,nameequals, contains, startsWith, endsWith, in所有.search()均支持limit与offset分页.list()与.search()位于同一路径省略.search后缀用于直接列举。这些本地检索能力让 Agent 可以在不频繁打 AMcards 远程 API 的情况下快速完成查找联系人 / 匹配模板 / 选礼物等决策逻辑。底层实现请求封装、限流与错误处理请求封装与分页兼容makeAmcardsRequestclient.ts统一处理GET/POST/PUT/PATCH/DELETE 方法分发写请求自动携带 JSON mediaTypecompactQuery剔除值为undefined的查询参数避免发出?fooundefined路径 ID 通过encodeAmcardsPathId做 URI 编码client.ts。值得注意的分页兼容设计AMcards 的列表响应可能是 Django REST 的results结构、Tastypie 的objects结构甚至裸数组。listResponseendpoints/types.ts用z.union同时接受这三种形态保证任何历史版本的响应都不会导致解析失败。内置限流client.ts 为共享传输层配置了限流策略const AMCARDS_RATE_LIMIT_CONFIG: RateLimitConfig { enabled: true, maxRetries: 3, initialRetryDelay: 1000, backoffMultiplier: 2, headerNames: { retryAfter: Retry-After }, };即最多重试 3 次、初始退避 1 秒、退避倍数 2并读取Retry-After响应头。错误类型与错误处理器所有请求失败都会被包装为AmcardsAPIErrorclient.ts并透传status、statusText、body、retryAfter、rateLimitReset、rateLimitRemaining、rateLimitLimit等字段。error-handlers.ts 定义了六类错误匹配与重试策略分类匹配依据状态码优先重试策略RATE_LIMIT_ERROR429不重试AUTH_ERROR401/403不重试NOT_FOUND_ERROR404不重试VALIDATION_ERROR400/422不重试SERVER_ERROR 500最多重试 2 次指数退避DEFAULT兜底不重试注释明确指出AMcards 是 Django REST APIHTTP 状态码本身就是契约消息启发式匹配如 message 中包含 rate limit、invalid token 等只在拿不到状态码时兜底使用。测试覆盖插件自带完整测试handlers.test.ts 通过 mockmakeAmcardsRequest验证 10 个 handler 的请求参数映射与输出 Schema 解析例如联系人first_name/last_name/email/created_at/updated_at、分类title/priority、礼物price/shipping_cost/available、模板name/panels等典型负载均被覆盖另有 client.test.ts 与 schema.test.ts 分别覆盖请求封装与 Schema 校验。与 Agent / MCP 集成插件能力可以通过 Corsair 的 MCP 适配层暴露为 MCP 工具使 Claude、Cursor 等编码 Agent 直接调用 AMcards 的 10 个操作参考 mcp-adapters.mdx。由于全部操作均为read风险级别将其暴露给 Agent 时权限模型相对简单清晰同时借助本地同步实体的.search()Agent 可以先在本地完成联系人匹配与模板选择再按需调用远程 API降低延迟与限流压力。版本与许可插件包名为corsair-dev/amcardspeerDependencies 要求corsair 0.1.0、zod ^4.1.13见 package.json许可协议为Apache-2.0README 与 package.json 一致插件类型定义amcards、AmcardsPluginOptions、AmcardsContext、AmcardsEndpoints等均从 index.ts 导出输入输出类型与 Schema 从 endpoints/types.ts 导出。小结corsair-dev/amcards插件把 AMcards 的 Django REST / Tastypie 风格 API 收敛为 10 个类型安全的只读操作配合本地 5 实体同步、内置限流与按状态码分类的错误处理为替用户发送个性化实体贺卡的 Agent 场景提供了开箱即用的连接能力。核心使用路径可概括为安装插件 → 注册到 Corsair → 通过 connect link 引导租户录入 API Key →withTenant(id)作用域内调用amcards.api.*或检索amcards.db.*。更完整的输入输出类型可继续查阅 api.mdx 与 database.mdx。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考