Corsair Abstract 插件接入指南邮箱、IBAN 与 VAT 校验 API 的统一封装与本地同步【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairCorsair 的corsair-dev/abstract插件把 Abstract API 的 4 个只读校验操作邮箱信誉、邮箱验证、IBAN 验证、VAT 税率分类封装为类型安全的abstract.api.*调用并把每次查询结果自动同步到本地数据库可通过abstract.db.*.search()离线检索。本文以 packages/abstract/README.md 为核心结合 packages/abstract 的源码实现与 docs/plugins/abstract 的官方文档讲解安装、配置、四个端点的调用方式、API Key 鉴权机制、错误处理策略以及本地数据同步的使用方法。插件概览Abstract 是一家提供开发者校验 API 的服务商其产品按业务域拆分为多个独立的子域名每个域名拥有独立的 API Key。Corsair 插件把以下 4 个操作统一收编进tenant.abstract.api命名空间全部为只读操作风险级别read操作Operation ID风险说明email.reputationabstract.api.email.reputationread评估邮箱的可投递性与质量格式、一次性/免费/角色邮箱检测、MX 与 SMTP 校验email.validateabstract.api.email.validateread验证邮箱地址是否真实、格式正确且可投递iban.validateabstract.api.iban.validateread验证 IBAN 号的格式与国家代码vat.getCategoriesabstract.api.vat.getCategoriesread获取某国的 VAT 税率分类标准、减免、特殊每个端点都对应一份 Zod 输入/输出 Schema定义于 packages/abstract/endpoints/types.ts调用时拥有完整的 TypeScript 类型提示同时运行时还会做二次校验确保来自 Abstract 的响应结构与声明一致见 packages/abstract/endpoints/email-reputation.ts 的EmailReputationResponseSchema.parse(rawResponse)。安装在已有 Corsair 项目的根目录安装插件pnpm add corsair-dev/abstract使用 npm / yarn / bun 同样可以安装详见 docs/plugins/abstract/overview.mdxnpm install corsair corsair-dev/abstract # 或 yarn add corsair corsair-dev/abstract # 或 bun add corsair corsair-dev/abstract从 packages/abstract/package.json 可以看到该插件的声明依赖peerDependenciescorsair 0.1.0插件运行在 Corsair 核心之上zod ^4.1.13输入/输出 Schema 与数据库 Schema 均由 zod 定义。注意包名中的corsair-dev/abstract是独立包需与核心包corsair一起安装。快速接入把插件挂到 Corsair 实例上参照 docs/plugins/abstract/overview.mdx 的 Setup 章节最小化配置如下// corsair.ts import Database from better-sqlite3; import { createCorsair } from corsair; import { abstract } from corsair-dev/abstract; export const corsair createCorsair({ plugins: [abstract()], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, // 用于加密租户凭证的 Key Encryption Key hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });几个关键点databaseCorsair 需要本地数据库来持久化凭证与同步数据kek租户的 API Key 以加密形式存储解密需要 KEK参见 docs/concepts/api-key.mdx多租户Corsair 默认开启多租户通过corsair.withTenant(id)拿到租户作用域实例后再调用 API租户之间数据与凭证互相隔离参见 docs/concepts/multi-tenancy.mdx插件工厂abstract()定义于 packages/abstract/index.tsauthType默认值为api_key。让租户连接 Abstract 账号Abstract 使用 API Key 鉴权无需 OAuth。调用manage.connect.createLink生成一个连接链接把租户引导到该页面由 Hub 托管连接页并把结果回传给应用参见 docs/management/connect.mdxconst { connectUrl } await corsair.manage.connect.createLink({ plugin: abstract, tenantId: acme, }); // 将用户的浏览器重定向到 connectUrl当租户首次发起请求时如果尚未配置凭证Corsair 会提示其输入 API Key。四个端点详解调用方式统一为corsair.withTenant(acme).abstract.api.group.operation({ ... })以下是各端点的输入输出与完整类型。email.reputation —— 邮箱信誉与可投递性评估对应 Operation IDabstract.api.email.reputation风险read。返回 Abstract Email Reputation APIemailreputation.abstractapi.com/v1的完整评估结果包括投递状态、质量评分、发件人/域名信息、风险等级与泄露记录。const tenant corsair.withTenant(acme); const result await tenant.abstract.api.email.reputation({ email: supportabstractapi.com, });输入参数字段类型必填说明emailstring是要检查信誉的邮箱地址输出结构字段细节以 packages/abstract/endpoints/types.ts 为准{ email_address: string, suggested_correction?: string | null, email_deliverability: { status: string, // 可投递性结论 status_detail: string, is_format_valid: boolean, is_smtp_valid: boolean, is_mx_valid: boolean, mx_records?: string[] | null }, email_quality: { score: number, // 0.0–1.0 质量评分 is_free_email: boolean, is_username_suspicious: boolean, is_disposable: boolean, // 一次性邮箱 is_catchall: boolean, is_subaddress: boolean, is_role?: boolean, // 角色邮箱如 info、support is_dmarc_enforced?: boolean, is_spf_strict?: boolean, minimum_age?: number | null }, email_sender: { first_name?, last_name?, email_provider_name?, organization_name?, organization_type? }, email_domain: { domain?, domain_age?, is_live_site?, registrar?, registrar_url?, date_registered?, date_last_renewed?, date_expires?, is_risky_tld? }, email_risk: { address_risk_status?: string | null, domain_risk_status?: string | null }, email_breaches?: { total_breaches?: number | null, date_first_breached?: string | null, date_last_breached?: string | null, breached_domains?: { domain: string, breach_date?: string | null }[] } }对于无效邮箱地址Abstract 返回的email_domain、email_risk、email_breaches中相关字段为nullSchema 中这些字段声明为nullable且在测试中专门覆盖了该场景见 packages/abstract/api.test.ts 中get returns correct type for an invalid address用例。email.validate —— 邮箱真实性验证对应 Operation IDabstract.api.email.validate风险read。用于在收集到邮箱后、正式发信前确认地址是否真实、格式正确且可投递。const result await tenant.abstract.api.email.validate({ email: someonegmail.com, });输入参数email: string必填。输出一个扁平化的验证结果字段类型说明emailstring被验证的邮箱autocorrectstringAbstract 检测到疑似拼写错误时的修正建议无则空字符串deliverabilitystring投递结论如deliverable/undeliverable/risky/unknownquality_scorenumber0.0–1.0 置信度评分is_valid_formatboolean格式是否合法is_free_emailboolean是否免费邮箱如 gmail.comis_disposable_emailboolean是否一次性邮箱is_role_emailboolean是否角色邮箱is_catchall_emailboolean是否 catch-all 域名is_mx_foundboolean是否找到 MX 记录is_smtp_validbooleanSMTP 是否验证通过实现细节Abstract 的独立 Email Validation 产品在插件所针对的账号/套餐上不可用因此该端点实际调用的是 Email Reputation API再通过mapEmailReputationToValidation见 packages/abstract/endpoints/email-validation.ts把信誉响应的可投递性/质量字段映射为扁平的验证结果。这意味着email.validate与email.reputation使用同一个 API Key。iban.validate —— IBAN 格式校验对应 Operation IDabstract.api.iban.validate风险read。验证 IBAN 的格式与国家代码用于收款场景中收集 IBAN 后即时校验。const result await tenant.abstract.api.iban.validate({ iban: DE89370400440532013000, });输入参数iban: string必填可带空格底层实现会先去除空格再做脱敏处理。输出字段类型说明ibanstring规范化后的 IBANis_validboolean格式与国家代码是否有效该端点调用ibanvalidation.abstractapi.com/v1见 packages/abstract/client.ts 中ABSTRACT_API_HOSTS。vat.getCategories —— VAT 税率分类查询对应 Operation IDabstract.api.vat.getCategories风险read。返回指定国家的标准/减免/特殊 VAT 税率分类用于需要按国家计算适用税率的产品与服务定价场景。const result await tenant.abstract.api.vat.getCategories({ countryCode: DE, // ISO 3166-1 alpha-2 大写国家代码 });输入参数countryCode: string必填正则校验^[A-Z]{2}$必须是两位大写 ISO 3166-1 alpha-2 代码。输出为对象数组{ country_code: string, // 如 DE rate: string, // 十进制字符串如 0.070 表示 7% category: string, // 分类standard / reduced / special 等 description: string }[]该端点调用vat.abstractapi.com/v1/categories见 packages/abstract/endpoints/vat.ts。与另外三个端点不同它的响应是一个数组落库时按country_code:category作为实体主键逐条写入见 packages/abstract/endpoints/vat.ts。鉴权机制API Key 与按产品拆分的多 Key 策略Abstract 插件仅支持api_key一种鉴权方式AbstractPluginOptions.authType类型被限定为PickAuthapi_key见 packages/abstract/index.ts。关键背景Abstract 的 API Key 是在控制台按产品分别签发的——一个能解锁 Email Reputation 的 Key 不一定能解锁 VAT 或 IBAN Validation。因此插件支持三级 Key 解析优先级从高到低专用 Key推荐通过插件选项emailReputationApiKey/vatApiKey/ibanApiKey显式配置或通过密钥管理器存储的账户级字段ctx.keys.get_email_reputation_api_key()、ctx.keys.get_vat_api_key()、ctx.keys.get_iban_api_key()读取共享兜底 Key插件选项key或密钥管理器中的基础api_key字段均未配置时抛出AuthMissingError(abstract, api_key)。以email.validate为例其 Key 解析顺序见 packages/abstract/endpoints/email-validation.tsconst apiKey ctx.options.emailReputationApiKey ?? (await tryGetStoredKey(() ctx.keys?.get_email_reputation_api_key())) ?? ctx.key;对应的插件配置写法abstract({ key: SHARED_FALLBACK_KEY, // 可选共享兜底 Key emailReputationApiKey: EMAIL_KEY, // 可选每个产品各自的 Key vatApiKey: VAT_KEY, ibanApiKey: IBAN_KEY, })账户级字段email_reputation_api_key、vat_api_key、iban_api_key由abstractAuthConfig声明见 packages/abstract/index.tsCorsair 会在租户首次使用时提示填写。tryGetStoredKey处理账户没有 DEK的边界情况tryGetStoredKey见 packages/abstract/client.ts是这套解析机制里的关键兜底当账户完全没有配置 DEKData Encryption Key即只通过插件选项配置专用 Key、从未使用过密钥管理器的账户时ctx.keys.get_*()会抛错而非返回null。该函数只匹配 Corsair 密钥管理器中未找到 DEK这条特定错误消息/no dek found/i将其视为未配置存储 Key返回undefined而真正的解密失败、数据库故障等运维问题会原样向上抛出避免把真实故障静默掩盖成没配 Key进而错误地回退到共享 Key 造成凭据串用。另外只有当同时配置了数据库与 KEK 时Corsair 核心才会在上下文中挂载ctx.keys相关逻辑位于 packages/corsair/core/client/index.ts因此插件代码中对ctx.keys使用了可选链?.访问保证无数据库/无 KEK 的纯选项式配置也能正常工作。传输方式Abstract 不接受 Bearer Token 或鉴权头只接受以查询参数形式传递的api_key且当前 4 个端点全部为 GET 请求。makeAbstractRequest见 packages/abstract/client.ts统一拼接GET https://emailreputation.abstractapi.com/v1?api_keyxxxemail... GET https://vat.abstractapi.com/v1/categories?api_keyxxxcountry_codeDE GET https://ibanvalidation.abstractapi.com/v1?api_keyxxxiban...事件日志中的数据脱敏出于隐私考虑插件在写入事件日志前会对敏感数据做脱敏见 packages/abstract/client.tsredactEmail保留邮箱首字符与域名如s***abstractapi.comredactIban保留国家代码与前 4 位…实际是保留前 2 位与国家代码、后 4 位中间用*掩码。由于 IBAN 直接标识具体银行账户脱敏比邮箱更彻底。错误处理与重试策略插件内置了一套按 HTTP 状态码区分的错误处理器见 packages/abstract/error-handlers.ts可通过abstract({ errorHandlers: {...} })与默认处理器合并覆盖处理器匹配条件策略RATE_LIMIT_ERRORHTTP 429 或消息含429/rate limit最多重试 3 次指数退避尊重Retry-After响应头AUTH_ERRORHTTP 401 或消息含invalid api key/unauthorized/401不重试提示检查 Key 是否针对当前产品签发QUOTA_ERRORHTTP 422 且错误体含quota/exceeded/limit reached不重试提示套餐配额耗尽注意它在VALIDATION_ERROR之前匹配VALIDATION_ERRORHTTP 422通用或消息含422/unprocessable不重试提示参数缺失或格式错误SERVER_ERRORHTTP 5xx最多重试 2 次指数退避DEFAULT兜底不重试有两个值得注意的实现细节422 的双重含义在 Email Reputation 产品上Abstract 在配额耗尽时返回的是 422而非 429因此QUOTA_ERROR被排在VALIDATION_ERROR之前匹配并专门从错误体的error.message/error.code中提取文本关键词判断getErrorBodyText。没有配额措辞的 422 才会落入通用的VALIDATION_ERROR。错误体提取由于 Corsair 请求层在构造错误消息时取的是body?.message || body?.error || ...而 Abstract 把信息嵌套在error对象下error.message可能变成整个对象而非字符串。因此getErrorBodyText直接从AbstractAPIError.body中提取error.message与error.code拼接成可搜索文本。所有 API 错误都会被包装成AbstractAPIError见 packages/abstract/client.ts它透传ApiError的status、statusText、body、retryAfter以及rateLimit*系列字段供上层错误处理器检查无需instanceof ApiError判断。本地数据同步4 个可检索实体每次成功的 API 调用插件都会把结果 upsert 进本地数据库数据表 Schema 定义于 packages/abstract/schema/database.ts由 packages/abstract/schema/index.ts 汇总为AbstractSchema。写入失败只打印警告不会让 API 调用本身失败各端点实现中均有try { ... } catch { console.warn(...) }。同步出的 4 个实体见 docs/plugins/abstract/database.mdx实体路径对应端点主要字段abstract.db.emailReputationsemail.reputationemailAddress、deliverabilityStatus、qualityScore、isFreeEmail、isDisposable、isCatchall、addressRiskStatus、domainRiskStatusabstract.db.emailValidationsemail.validateemail、autocorrect、deliverability、qualityScore、isValidFormat、isFreeEmail、isDisposableEmail、isRoleEmail、isCatchallEmail、isMxFound、isSmtpValidabstract.db.ibanValidationsiban.validateiban、isValidabstract.db.vatCategoriesvat.getCategoriescountryCode、category、description、rate检索示例所有实体均支持search()与list()// 找出所有投递状态为 deliverable 的邮箱记录 const rows await corsair.abstract.db.emailReputations.search({ data: { deliverabilityStatus: { equals: deliverable } }, limit: 100, offset: 0, }); // 列出最近 24 小时内的 IBAN 验证记录 const recent await corsair.abstract.db.ibanValidations.search({ data: { checkedAt: { after: new Date(Date.now() - 24 * 60 * 60 * 1000) } }, });各实体可用的搜索操作符字符串字段支持equals/contains/startsWith/endsWith/in数字字段支持equals/gt/gte/lt/lte/in布尔字段仅equals日期字段支持equals/before/after/between。每个实体都可按entity_id即邮箱地址、IBAN 或country_code:category组合直接查询天然去重——同一实体重复校验只会覆盖更新。分页通过limit/offset控制。更完整的操作符说明参见 docs/concepts/database.mdx。Webhooks无纯拉取型 APIAbstract 插件不提供任何 Webhook。README 明确标注 No webhooks源码中abstractWebhooksNested为空对象、pluginWebhookMatcher为undefined、webhookHooks为undefined见 packages/abstract/index.ts。Abstract 是纯拉取pull-basedAPI——数据变化需要主动调用端点获取Corsair 不会向你的应用推送事件。如果你的业务流程需要邮箱被标记为风险时立即告警需要通过定时任务调用email.reputation并检索本地同步结果来实现。插件源码结构一览如果希望深入阅读实现可关注以下文件packages/abstract/index.ts — 插件工厂abstract()、插件选项类型、端点树email.validate/email.reputation/vat.getCategories/iban.validate、鉴权配置与风险元数据packages/abstract/client.ts — Abstract 各产品域名常量、makeAbstractRequest请求封装、AbstractAPIError、脱敏函数与tryGetStoredKeypackages/abstract/endpoints/types.ts — 四个端点的 Zod 输入/输出 Schema 与 TypeScript 类型packages/abstract/endpoints/ — 每个端点的具体实现含落库与事件日志packages/abstract/schema/database.ts — 本地同步实体的存储 Schemapackages/abstract/error-handlers.ts — 默认错误处理器packages/abstract/api.test.ts — 针对真实 Abstract API 的集成类型测试需环境变量ABSTRACT_EMAIL_REPUTATION_API_KEY/ABSTRACT_VAT_API_KEY/ABSTRACT_IBAN_VALIDATION_API_KEY也支持共享的ABSTRACT_API_KEY兜底。测试用例验证了几个关键行为免费邮箱gmail.com的is_free_email为true无效邮箱的email_domain.domain、email_risk.address_risk_status为null重度泄露地址testtest.com的total_breaches大于 0VAT 分类对DE返回非空数组。这些测试也印证了上文提到的 Schema 可空字段设计与按产品拆分 Key 的约定packages/abstract/api.test.ts。许可证与参考插件以Apache-2.0许可证发布见 packages/abstract/package.json更多用法与类型参考见 docs/plugins/abstract/api.mdx完整 API 参考与 docs/plugins/abstract/database.mdx数据库检索参考若需把插件操作暴露为 MCP 工具给 Agent 使用可参考 docs/mcp-adapters/mcp-adapters.mdx。总体而言corsair-dev/abstract是一个典型的薄封装 厚本地化的 Corsair 插件对外提供 4 个类型安全的只读校验操作对内通过三级 Key 解析、精细的错误分类与重试策略、以及自动的本地数据同步让业务方可以专注于用校验结果做决策而把凭证管理、API 调用细节与数据沉淀全部交给 Corsair。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Corsair Abstract 插件接入指南邮箱、IBAN 与 VAT 校验 API 的统一封装与本地同步【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairCorsair 的corsair-dev/abstract插件把 Abstract API 的 4 个只读校验操作邮箱信誉、邮箱验证、IBAN 验证、VAT 税率分类封装为类型安全的abstract.api.*调用并把每次查询结果自动同步到本地数据库可通过abstract.db.*.search()离线检索。本文以 packages/abstract/README.md 为核心结合 packages/abstract 的源码实现与 docs/plugins/abstract 的官方文档讲解安装、配置、四个端点的调用方式、API Key 鉴权机制、错误处理策略以及本地数据同步的使用方法。插件概览Abstract 是一家提供开发者校验 API 的服务商其产品按业务域拆分为多个独立的子域名每个域名拥有独立的 API Key。Corsair 插件把以下 4 个操作统一收编进tenant.abstract.api命名空间全部为只读操作风险级别read操作Operation ID风险说明email.reputationabstract.api.email.reputationread评估邮箱的可投递性与质量格式、一次性/免费/角色邮箱检测、MX 与 SMTP 校验email.validateabstract.api.email.validateread验证邮箱地址是否真实、格式正确且可投递iban.validateabstract.api.iban.validateread验证 IBAN 号的格式与国家代码vat.getCategoriesabstract.api.vat.getCategoriesread获取某国的 VAT 税率分类标准、减免、特殊每个端点都对应一份 Zod 输入/输出 Schema定义于 packages/abstract/endpoints/types.ts调用时拥有完整的 TypeScript 类型提示同时运行时还会做二次校验确保来自 Abstract 的响应结构与声明一致见 packages/abstract/endpoints/email-reputation.ts 的EmailReputationResponseSchema.parse(rawResponse)。安装在已有 Corsair 项目的根目录安装插件pnpm add corsair-dev/abstract使用 npm / yarn / bun 同样可以安装详见 docs/plugins/abstract/overview.mdxnpm install corsair corsair-dev/abstract # 或 yarn add corsair corsair-dev/abstract # 或 bun add corsair corsair-dev/abstract从 packages/abstract/package.json 可以看到该插件的声明依赖peerDependenciescorsair 0.1.0插件运行在 Corsair 核心之上zod ^4.1.13输入/输出 Schema 与数据库 Schema 均由 zod 定义。注意包名中的corsair-dev/abstract是独立包需与核心包corsair一起安装。快速接入把插件挂到 Corsair 实例上参照 docs/plugins/abstract/overview.mdx 的 Setup 章节最小化配置如下// corsair.ts import Database from better-sqlite3; import { createCorsair } from corsair; import { abstract } from corsair-dev/abstract; export const corsair createCorsair({ plugins: [abstract()], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, // 用于加密租户凭证的 Key Encryption Key hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });几个关键点databaseCorsair 需要本地数据库来持久化凭证与同步数据kek租户的 API Key 以加密形式存储解密需要 KEK参见 docs/concepts/api-key.mdx多租户Corsair 默认开启多租户通过corsair.withTenant(id)拿到租户作用域实例后再调用 API租户之间数据与凭证互相隔离参见 docs/concepts/multi-tenancy.mdx插件工厂abstract()定义于 packages/abstract/index.tsauthType默认值为api_key。让租户连接 Abstract 账号Abstract 使用 API Key 鉴权无需 OAuth。调用manage.connect.createLink生成一个连接链接把租户引导到该页面由 Hub 托管连接页并把结果回传给应用参见 docs/management/connect.mdxconst { connectUrl } await corsair.manage.connect.createLink({ plugin: abstract, tenantId: acme, }); // 将用户的浏览器重定向到 connectUrl当租户首次发起请求时如果尚未配置凭证Corsair 会提示其输入 API Key。四个端点详解调用方式统一为corsair.withTenant(acme).abstract.api.group.operation({ ... })以下是各端点的输入输出与完整类型。email.reputation —— 邮箱信誉与可投递性评估对应 Operation IDabstract.api.email.reputation风险read。返回 Abstract Email Reputation APIemailreputation.abstractapi.com/v1的完整评估结果包括投递状态、质量评分、发件人/域名信息、风险等级与泄露记录。const tenant corsair.withTenant(acme); const result await tenant.abstract.api.email.reputation({ email: supportabstractapi.com, });输入参数字段类型必填说明emailstring是要检查信誉的邮箱地址输出结构字段细节以 packages/abstract/endpoints/types.ts 为准{ email_address: string, suggested_correction?: string | null, email_deliverability: { status: string, // 可投递性结论 status_detail: string, is_format_valid: boolean, is_smtp_valid: boolean, is_mx_valid: boolean, mx_records?: string[] | null }, email_quality: { score: number, // 0.0–1.0 质量评分 is_free_email: boolean, is_username_suspicious: boolean, is_disposable: boolean, // 一次性邮箱 is_catchall: boolean, is_subaddress: boolean, is_role?: boolean, // 角色邮箱如 info、support is_dmarc_enforced?: boolean, is_spf_strict?: boolean, minimum_age?: number | null }, email_sender: { first_name?, last_name?, email_provider_name?, organization_name?, organization_type? }, email_domain: { domain?, domain_age?, is_live_site?, registrar?, registrar_url?, date_registered?, date_last_renewed?, date_expires?, is_risky_tld? }, email_risk: { address_risk_status?: string | null, domain_risk_status?: string | null }, email_breaches?: { total_breaches?: number | null, date_first_breached?: string | null, date_last_breached?: string | null, breached_domains?: { domain: string, breach_date?: string | null }[] } }对于无效邮箱地址Abstract 返回的email_domain、email_risk、email_breaches中相关字段为nullSchema 中这些字段声明为nullable且在测试中专门覆盖了该场景见 packages/abstract/api.test.ts 中get returns correct type for an invalid address用例。email.validate —— 邮箱真实性验证对应 Operation IDabstract.api.email.validate风险read。用于在收集到邮箱后、正式发信前确认地址是否真实、格式正确且可投递。const result await tenant.abstract.api.email.validate({ email: someonegmail.com, });输入参数email: string必填。输出一个扁平化的验证结果字段类型说明emailstring被验证的邮箱autocorrectstringAbstract 检测到疑似拼写错误时的修正建议无则空字符串deliverabilitystring投递结论如deliverable/undeliverable/risky/unknownquality_scorenumber0.0–1.0 置信度评分is_valid_formatboolean格式是否合法is_free_emailboolean是否免费邮箱如 gmail.comis_disposable_emailboolean是否一次性邮箱is_role_emailboolean是否角色邮箱is_catchall_emailboolean是否 catch-all 域名is_mx_foundboolean是否找到 MX 记录is_smtp_validbooleanSMTP 是否验证通过实现细节Abstract 的独立 Email Validation 产品在插件所针对的账号/套餐上不可用因此该端点实际调用的是 Email Reputation API再通过mapEmailReputationToValidation见 packages/abstract/endpoints/email-validation.ts把信誉响应的可投递性/质量字段映射为扁平的验证结果。这意味着email.validate与email.reputation使用同一个 API Key。iban.validate —— IBAN 格式校验对应 Operation IDabstract.api.iban.validate风险read。验证 IBAN 的格式与国家代码用于收款场景中收集 IBAN 后即时校验。const result await tenant.abstract.api.iban.validate({ iban: DE89370400440532013000, });输入参数iban: string必填可带空格底层实现会先去除空格再做脱敏处理。输出字段类型说明ibanstring规范化后的 IBANis_validboolean格式与国家代码是否有效该端点调用ibanvalidation.abstractapi.com/v1见 packages/abstract/client.ts 中ABSTRACT_API_HOSTS。vat.getCategories —— VAT 税率分类查询对应 Operation IDabstract.api.vat.getCategories风险read。返回指定国家的标准/减免/特殊 VAT 税率分类用于需要按国家计算适用税率的产品与服务定价场景。const result await tenant.abstract.api.vat.getCategories({ countryCode: DE, // ISO 3166-1 alpha-2 大写国家代码 });输入参数countryCode: string必填正则校验^[A-Z]{2}$必须是两位大写 ISO 3166-1 alpha-2 代码。输出为对象数组{ country_code: string, // 如 DE rate: string, // 十进制字符串如 0.070 表示 7% category: string, // 分类standard / reduced / special 等 description: string }[]该端点调用vat.abstractapi.com/v1/categories见 packages/abstract/endpoints/vat.ts。与另外三个端点不同它的响应是一个数组落库时按country_code:category作为实体主键逐条写入见 packages/abstract/endpoints/vat.ts。鉴权机制API Key 与按产品拆分的多 Key 策略Abstract 插件仅支持api_key一种鉴权方式AbstractPluginOptions.authType类型被限定为PickAuthapi_key见 packages/abstract/index.ts。关键背景Abstract 的 API Key 是在控制台按产品分别签发的——一个能解锁 Email Reputation 的 Key 不一定能解锁 VAT 或 IBAN Validation。因此插件支持三级 Key 解析优先级从高到低专用 Key推荐通过插件选项emailReputationApiKey/vatApiKey/ibanApiKey显式配置或通过密钥管理器存储的账户级字段ctx.keys.get_email_reputation_api_key()、ctx.keys.get_vat_api_key()、ctx.keys.get_iban_api_key()读取共享兜底 Key插件选项key或密钥管理器中的基础api_key字段均未配置时抛出AuthMissingError(abstract, api_key)。以email.validate为例其 Key 解析顺序见 packages/abstract/endpoints/email-validation.tsconst apiKey ctx.options.emailReputationApiKey ?? (await tryGetStoredKey(() ctx.keys?.get_email_reputation_api_key())) ?? ctx.key;对应的插件配置写法abstract({ key: SHARED_FALLBACK_KEY, // 可选共享兜底 Key emailReputationApiKey: EMAIL_KEY, // 可选每个产品各自的 Key vatApiKey: VAT_KEY, ibanApiKey: IBAN_KEY, })账户级字段email_reputation_api_key、vat_api_key、iban_api_key由abstractAuthConfig声明见 packages/abstract/index.tsCorsair 会在租户首次使用时提示填写。tryGetStoredKey处理账户没有 DEK的边界情况tryGetStoredKey见 packages/abstract/client.ts是这套解析机制里的关键兜底当账户完全没有配置 DEKData Encryption Key即只通过插件选项配置专用 Key、从未使用过密钥管理器的账户时ctx.keys.get_*()会抛错而非返回null。该函数只匹配 Corsair 密钥管理器中未找到 DEK这条特定错误消息/no dek found/i将其视为未配置存储 Key返回undefined而真正的解密失败、数据库故障等运维问题会原样向上抛出避免把真实故障静默掩盖成没配 Key进而错误地回退到共享 Key 造成凭据串用。另外只有当同时配置了数据库与 KEK 时Corsair 核心才会在上下文中挂载ctx.keys相关逻辑位于 packages/corsair/core/client/index.ts因此插件代码中对ctx.keys使用了可选链?.访问保证无数据库/无 KEK 的纯选项式配置也能正常工作。传输方式Abstract 不接受 Bearer Token 或鉴权头只接受以查询参数形式传递的api_key且当前 4 个端点全部为 GET 请求。makeAbstractRequest见 packages/abstract/client.ts统一拼接GET https://emailreputation.abstractapi.com/v1?api_keyxxxemail... GET https://vat.abstractapi.com/v1/categories?api_keyxxxcountry_codeDE GET https://ibanvalidation.abstractapi.com/v1?api_keyxxxiban...事件日志中的数据脱敏出于隐私考虑插件在写入事件日志前会对敏感数据做脱敏见 packages/abstract/client.tsredactEmail保留邮箱首字符与域名如s***abstractapi.comredactIban保留国家代码与前 4 位…实际是保留前 2 位与国家代码、后 4 位中间用*掩码。由于 IBAN 直接标识具体银行账户脱敏比邮箱更彻底。错误处理与重试策略插件内置了一套按 HTTP 状态码区分的错误处理器见 packages/abstract/error-handlers.ts可通过abstract({ errorHandlers: {...} })与默认处理器合并覆盖处理器匹配条件策略RATE_LIMIT_ERRORHTTP 429 或消息含429/rate limit最多重试 3 次指数退避尊重Retry-After响应头AUTH_ERRORHTTP 401 或消息含invalid api key/unauthorized/401不重试提示检查 Key 是否针对当前产品签发QUOTA_ERRORHTTP 422 且错误体含quota/exceeded/limit reached不重试提示套餐配额耗尽注意它在VALIDATION_ERROR之前匹配VALIDATION_ERRORHTTP 422通用或消息含422/unprocessable不重试提示参数缺失或格式错误SERVER_ERRORHTTP 5xx最多重试 2 次指数退避DEFAULT兜底不重试有两个值得注意的实现细节422 的双重含义在 Email Reputation 产品上Abstract 在配额耗尽时返回的是 422而非 429因此QUOTA_ERROR被排在VALIDATION_ERROR之前匹配并专门从错误体的error.message/error.code中提取文本关键词判断getErrorBodyText。没有配额措辞的 422 才会落入通用的VALIDATION_ERROR。错误体提取由于 Corsair 请求层在构造错误消息时取的是body?.message || body?.error || ...而 Abstract 把信息嵌套在error对象下error.message可能变成整个对象而非字符串。因此getErrorBodyText直接从AbstractAPIError.body中提取error.message与error.code拼接成可搜索文本。所有 API 错误都会被包装成AbstractAPIError见 packages/abstract/client.ts它透传ApiError的status、statusText、body、retryAfter以及rateLimit*系列字段供上层错误处理器检查无需instanceof ApiError判断。本地数据同步4 个可检索实体每次成功的 API 调用插件都会把结果 upsert 进本地数据库数据表 Schema 定义于 packages/abstract/schema/database.ts由 packages/abstract/schema/index.ts 汇总为AbstractSchema。写入失败只打印警告不会让 API 调用本身失败各端点实现中均有try { ... } catch { console.warn(...) }。同步出的 4 个实体见 docs/plugins/abstract/database.mdx实体路径对应端点主要字段abstract.db.emailReputationsemail.reputationemailAddress、deliverabilityStatus、qualityScore、isFreeEmail、isDisposable、isCatchall、addressRiskStatus、domainRiskStatusabstract.db.emailValidationsemail.validateemail、autocorrect、deliverability、qualityScore、isValidFormat、isFreeEmail、isDisposableEmail、isRoleEmail、isCatchallEmail、isMxFound、isSmtpValidabstract.db.ibanValidationsiban.validateiban、isValidabstract.db.vatCategoriesvat.getCategoriescountryCode、category、description、rate检索示例所有实体均支持search()与list()// 找出所有投递状态为 deliverable 的邮箱记录 const rows await corsair.abstract.db.emailReputations.search({ data: { deliverabilityStatus: { equals: deliverable } }, limit: 100, offset: 0, }); // 列出最近 24 小时内的 IBAN 验证记录 const recent await corsair.abstract.db.ibanValidations.search({ data: { checkedAt: { after: new Date(Date.now() - 24 * 60 * 60 * 1000) } }, });各实体可用的搜索操作符字符串字段支持equals/contains/startsWith/endsWith/in数字字段支持equals/gt/gte/lt/lte/in布尔字段仅equals日期字段支持equals/before/after/between。每个实体都可按entity_id即邮箱地址、IBAN 或country_code:category组合直接查询天然去重——同一实体重复校验只会覆盖更新。分页通过limit/offset控制。更完整的操作符说明参见 docs/concepts/database.mdx。Webhooks无纯拉取型 APIAbstract 插件不提供任何 Webhook。README 明确标注 No webhooks源码中abstractWebhooksNested为空对象、pluginWebhookMatcher为undefined、webhookHooks为undefined见 packages/abstract/index.ts。Abstract 是纯拉取pull-basedAPI——数据变化需要主动调用端点获取Corsair 不会向你的应用推送事件。如果你的业务流程需要邮箱被标记为风险时立即告警需要通过定时任务调用email.reputation并检索本地同步结果来实现。插件源码结构一览如果希望深入阅读实现可关注以下文件packages/abstract/index.ts — 插件工厂abstract()、插件选项类型、端点树email.validate/email.reputation/vat.getCategories/iban.validate、鉴权配置与风险元数据packages/abstract/client.ts — Abstract 各产品域名常量、makeAbstractRequest请求封装、AbstractAPIError、脱敏函数与tryGetStoredKeypackages/abstract/endpoints/types.ts — 四个端点的 Zod 输入/输出 Schema 与 TypeScript 类型packages/abstract/endpoints/ — 每个端点的具体实现含落库与事件日志packages/abstract/schema/database.ts — 本地同步实体的存储 Schemapackages/abstract/error-handlers.ts — 默认错误处理器packages/abstract/api.test.ts — 针对真实 Abstract API 的集成类型测试需环境变量ABSTRACT_EMAIL_REPUTATION_API_KEY/ABSTRACT_VAT_API_KEY/ABSTRACT_IBAN_VALIDATION_API_KEY也支持共享的ABSTRACT_API_KEY兜底。测试用例验证了几个关键行为免费邮箱gmail.com的is_free_email为true无效邮箱的email_domain.domain、email_risk.address_risk_status为null重度泄露地址testtest.com的total_breaches大于 0VAT 分类对DE返回非空数组。这些测试也印证了上文提到的 Schema 可空字段设计与按产品拆分 Key 的约定packages/abstract/api.test.ts。许可证与参考插件以Apache-2.0许可证发布见 packages/abstract/package.json更多用法与类型参考见 docs/plugins/abstract/api.mdx完整 API 参考与 docs/plugins/abstract/database.mdx数据库检索参考若需把插件操作暴露为 MCP 工具给 Agent 使用可参考 docs/mcp-adapters/mcp-adapters.mdx。总体而言corsair-dev/abstract是一个典型的薄封装 厚本地化的 Corsair 插件对外提供 4 个类型安全的只读校验操作对内通过三级 Key 解析、精细的错误分类与重试策略、以及自动的本地数据同步让业务方可以专注于用校验结果做决策而把凭证管理、API 调用细节与数据沉淀全部交给 Corsair。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
