使用 @corsair-dev/brandfetch：在 Corsair 中集成 Brandfetch 品牌数据插件

使用 corsair-dev/brandfetch在 Corsair 中集成 Brandfetch 品牌数据插件【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsaircorsair-dev/brandfetch是 Corsair 生态中用于对接 Brandfetch 与源码实现系统讲解其安装方式、9 个端点操作、API Key/Client ID 认证模型、无入站 Webhook 的设计取舍、内置错误重试策略与本地缓存 schema帮助你直接在 Corsair 应用中快速接入 Logo、配色、字体等品牌视觉资产数据。安装与包结构该插件与核心运行时corsair解耦发布通过 pnpm 安装pnpm add corsair-dev/brandfetch安装后即可从包入口导入插件工厂函数brandfetch它返回一个符合 CorsairCorsairPlugin契约的插件对象插件 id 为brandfetch。从 index.ts 的导出可以看到包同时对外提供插件工厂brandfetch(options)与brandfetchAuthConfig端点类型BrandfetchEndpoints、BrandfetchBoundEndpoints及全部输入/输出类型上下文类型BrandfetchContext、BrandfetchKeyBuilderContext运行时 schema 与配置brandfetchEndpointSchemas、brandfetchEndpointMeta插件的 peer 依赖为corsair 0.1.0与zod ^4.1.13见 package.json所有端点出入参均由 zod schema 在运行时校验保证传输数据的类型安全。端点总览9 个操作、全部为 read 风险README 中给出了插件的完整端点清单全部操作的风险等级均为read只读不会产生写入副作用OperationOperation IDRiskDescriptionbrands.getbrandfetch.api.brands.getreadGet brand logos, colors, fonts, and company details by domain, ticker, ISIN, crypto symbol, or Brand IDbrands.getCompanybrandfetch.api.brands.getCompanyreadGet firmographic company data for a brand identifierbrands.searchbrandfetch.api.brands.searchreadSearch brands by name for autocomplete (requires client ID)graphql.getVersionbrandfetch.api.graphql.getVersionreadGet the Brandfetch GraphQL API versionlogos.getbrandfetch.api.logos.getreadBuild a Brandfetch Logo CDN URL (requires client ID)taxonomy.getbrandfetch.api.taxonomy.getreadGet Brandfetch industries, countries, and geographic regionstransactions.getbrandfetch.api.transactions.getreadMatch a payment descriptor to merchant brand datawebhooks.listbrandfetch.api.webhooks.listreadList registered Brandfetch webhookswebhooks.listEventsbrandfetch.api.webhooks.listEventsreadList webhook event types that can be subscribed to这些操作在源码中被组织为按资源分组的嵌套端点对象再由插件统一扁平化为brandfetch.api.*的 Operation ID。从 endpoints/index.ts 可以清晰看到分组结构brandsget / search / getCompany、logosget、transactionsget、taxonomyget、graphqlgetVersion、webhookslist / listEvents对应的CorsairEndpoint实现分别位于 endpoints/rest.tsREST 类与 endpoints/graphql.tsGraphQL 类。值得注意的设计细节是虽然插件的 Operation ID 里带webhooks但按 index.ts 中的注释webhooks.list与webhooks.listEvents本质是GraphQL 只读查询用于枚举用户在 Brandfetch 平台配置的 webhook 与可订阅事件类型并非 Corsair 侧的入站 webhook 投递。认证模型API Key 为主Client ID 为辅README 明确指出本插件的认证方式是API key并且「Corsair prompts your tenant for credentials on first use」——即多租户场景下租户首次使用时 Corsair 会引导其录入凭据。源码 index.ts 中的认证配置进一步说明export const brandfetchAuthConfig { api_key: { account: [client_id] as const, }, } as const satisfies PluginAuthConfig;即插件的账号维度凭据包含api_keyAPI Key与client_idClient ID两类。实际运行时的取值优先级由keyBuilder决定index.ts插件选项中的key租户已存储的 API Key通过ctx.keys?.get_api_key()获取封装在 client.ts 的tryGetStoredKey中该函数会吞掉「no dek found」这类密钥未解密的错误并返回空值若仍为空则返回空字符串交由端点层抛出AuthMissingError见 rest.ts 的requireApiKey。Client ID 的解析顺序则相反resolveClientId见 client.ts请求入参 插件选项clientId 存储的client_id三者皆无时抛出BrandfetchAPIError提示「Brandfetch clientId is required for Brand Search and Logo CDN」。这意味着brands.search与logos.get两个操作必须提供 Client ID其余操作仅需 API Key。插件配置选项BrandfetchPluginOptionsindex.ts支持以下字段authType固定为api_key默认值即api_keykey直接注入 API Key跳过租户凭据存储clientId为 Brand Search 与 Logo CDN 提供 Client ID对应 URL 上的?c参数hooksCorsair 生命周期钩子errorHandlers自定义错误处理会与内置errorHandlers浅合并自定义项覆盖同名项permissions基于嵌套端点对象的权限配置。端点详解入参、底层调用与缓存落库brands.get按标识符获取品牌完整档案这是插件的核心操作底层请求为GET https://api.brandfetch.io/v2/brands/{type}/{identifier}BRANDFETCH_API_BASE定义在 client.ts。标识符支持domain、ticker、isin、crypto四种显式类型IdentifierTypeSchema见 endpoints/types.ts省略identifierType时按domain → ticker → ISIN → crypto的顺序自动探测。入参还包括可选的allowNsfw为true时返回 NSFW 品牌为false时 NSFW 品牌返回 404缺省时采用 Brandfetch 默认行为。响应GetBrandInfoResponseSchema包含id、name、domain、claimed、description、longDescription、links、logos、colors、fonts、images、qualityScore、company、isNsfw、urn等字段其中 logo 对象携带themedark/light、formatssvg/webp/png/jpeg与typeicon/logo/symbol/other颜色对象携带hex与typeaccent/dark/light/brand字体对象携带name、typetitle/body与origingoogle/custom/system。这些结构在 types.ts 中均有对应 zod schema任何字段缺失或类型不符都会在校验阶段被拒绝测试output schemas reject malformed payloads验证了这一点。调用成功后getBrandInfo还会尝试将品牌核心字段upsertByEntityId写入本地缓存表ctx.db.brandsbest-effort写入失败不影响返回并记录事件日志brandfetch.brands.get。brands.getCompany工商信息firmographic数据复用brands.get的请求链路但只返回响应中的company对象CompanySchema可为null。CompanySchema包含employees员工数分桶、financialIdentifiersisin/ticker 数组、foundedYear、industries、kind组织形式与locationcity/country/countryCode/region/state/subregion。成功后同样 best-effort 写入ctx.db.companies。brands.search品牌名自动补全搜索底层请求为GET https://api.brandfetch.io/v2/search/{name}?c{clientId}不使用 Bearer 认证bearer: false见 rest.ts而是靠 URL 上的c参数传递 Client ID。入参name必填最少 1 字符clientId可选缺省时按 选项 存储 的顺序回退。返回结果为品牌候选数组每项含icon、name、domain、claimed与brandId适合做搜索下拉框的自动补全数据源。logos.get构建 Logo CDN URL该操作不直接请求 CDN 下载图片而是返回一个可直接用于img标签的 Logo CDN URL。URL 由buildCdnLogoUrlrest.ts拼接格式为https://cdn.brandfetch.io/{type}/{identifier}[/w/{w}][/h/{h}][/theme/{theme}][/fallback/{fallback}][/type/{logoType}]?c{clientId}w/h正整数指定像素宽高themelight或darkfallbackbrandfetch|transparent|lettermark|404指定缺图时的兜底行为logoTypeicon|logo|symbol默认icon。ops.test.ts 中的断言给出了两个典型输出https://cdn.brandfetch.io/domain/nike.com/w/400/h/400/theme/dark/fallback/lettermark/type/icon?ctest-client-id https://cdn.brandfetch.io/nike.com?cabc # 省略 identifierType 时走自动探测transactions.get支付描述符 → 商户品牌匹配底层为POST https://api.brandfetch.io/v2/brands/transaction请求体携带transactionLabel信用卡账单上的原始交易文本必填与countryCodeISO 3166-1 alpha-2 国家码必填。countryCode在 schema 层做了.trim().toUpperCase()规范化并用正则/^[A-Z]{2}$/校验——测试用例验证了us会被自动转为US而USA会被直接拒绝见 ops.test.ts。返回结构等同于品牌完整档案可用于把STARBUCKS 1523 OMAHA NE这类账单文本映射为结构化商户品牌数据。taxonomy.get / graphql.getVersion / webhooks.*GraphQL 只读查询这四个操作统一经由makeBrandfetchGraphqlRequestclient.ts发往https://graphql.brandfetch.io以 POST JSON body{ query, variables }的形式执行固定查询并对errors数组与空data做显式错误抛出taxonomy.get一次性拉取taxonomy { industries, countries, geographicRegions }返回带层级parent/children/depth、emoji 与坐标的行业、国家、地理区域分类数据可作为品牌筛选器或行业目录的数据源graphql.getVersion查询{ version }返回 Brandfetch GraphQL API 版本号webhooks.listEvents查询subscribableEvents列出可订阅的事件类型如测试中的brand.updated含namespace、name、description、subscriptionScopewebhooks.list分页查询webhooks(first, after)入参first1–100GraphQL 默认 10与after上一页pageInfo.endCursor游标返回nodes与pageInfo { hasNextPage, endCursor }并 best-effort 将 webhook 节点写入ctx.db.webhooks。错误处理与重试策略所有上游请求都统一由makeBrandfetchRequest包装任何ApiError都会转换为带status、statusText、body、retryAfter的BrandfetchAPIError。内置的错误处理策略定义在 error-handlers.ts错误类型匹配条件重试策略RATE_LIMIT_ERRORHTTP 429或消息含too many requests/quota exceeded指数退避最多 5 次命中quota配额耗尽则不重试支持Retry-After头AUTH_ERRORHTTP 401/403或消息含unauthorized/forbidden不重试NOT_FOUND_ERRORHTTP 404或消息含not found不重试BAD_REQUEST_ERRORHTTP 400或消息含failed to enrich transaction不重试SERVER_ERRORHTTP ≥ 500或消息含internal server error指数退避最多 2 次DEFAULT兜底不重试此外makeBrandfetchRequest在发送前会拒绝路径中包含{/}的请求防止 Corsair HTTP 层占位符正则的潜在 ReDoS 风险并自动压缩掉undefined的查询参数compactQuery。Webhooks无入站投递README 明确「No webhooks」。从源码看brandfetchWebhooksNested被定义为空对象index.tswebhookHooks为undefined且pluginWebhookMatcher恒定返回false即插件主动拒绝一切 Brandfetch 入站投递0 个 trigger。前面提到的webhooks.list/webhooks.listEvents只是用于读取 Brandfetch 平台上已配置的 webhook 及事件类型帮助你在 Corsair 外部如 Brandfetch 控制台编排投递逻辑。本地缓存brands / companies / webhooks 三张表插件声明了版本号为1.0.0的数据库 schemaschema/index.ts包含三个实体详见 schema/database.tsBrandfetchBrand品牌档案的扁平化字段id、name、domain、claimed、description、longDescription、qualityScore、isNsfw、urn加checkedAt时间戳BrandfetchCompany工商信息行employees采用官方分桶1/2/11/51/201/501/1001/5001/10001kind取值包括EDUCATIONAL、GOVERNMENT_AGENCY、NON_PROFIT、PARTNERSHIP、PRIVATELY_HELD、PUBLIC_COMPANY、SELF_EMPLOYED、SELF_OWNED外加总部location各维度BrandfetchWebhookwebhook 端点记录urn、url、description、enabled、events刻意不存储 secret。设计取舍在注释中有明确说明嵌套的 logo/image 数组体积大且 CDN URL 会过期因此不做镜像本地只保留用于检索的工商与品牌行记录。所有写入均为 best-effort失败被捕获且不影响主流程。验证与测试插件的核心行为有完整的 Jest 测试保障endpoints/ops.test.ts配套 jest.config.cjs覆盖brands.get/getCompanyInfo的请求路径含 identifierType 前缀与响应 schema 解析buildCdnLogoUrl的完整 URL 拼装与自动探测分支transactions.get的请求体与国家码规范化/校验GraphQL 四个操作taxonomy、version、subscribableEvents、webhooks 分页的查询与响应映射输出 schema 对畸形负载的拒绝行为。运行时可通过pnpm testJest与pnpm typechecktsc --noEmit在包内自行验证pnpm build则通过 tsc tsup 产出 dist 产物见 package.json。小结corsair-dev/brandfetch以「9 个 read 端点 API Key/Client ID 双凭据 内置限流重试 本地实体缓存」的完整形态把 Brandfetch 的品牌资产能力无缝纳入 Corsair 的权限、日志、错误处理与数据库抽象体系。无论是做品牌 Logo 展示、账单文本归类、工商信息查询还是构建品牌选择器都可以用这一插件快速落地且无需自己维护 Brandfetch 的 HTTP 细节与凭据生命周期。插件遵循 Apache-2.0 协议发布可放心在商业化项目中集成使用。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考