Corsair Beaconstac 插件实战用 21 个端点把 Uniqode QR 码能力接入你的 Agent【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair导读corsair-dev/beaconstac是 Corsair 生态中面向 Beaconstac现 Uniqode官方 REST Reporting API 的即插即用插件让 Agent 应用能够以统一的插件协议管理组织、用户、QR 码、模板、标签、地点与批量 QR 集合并拉取产品级分析数据。读完本文你将掌握该插件的安装方式、API Key 认证机制、21 个端点的完整能力地图、底层请求映射与限流/鉴权错误处理策略并知道如何通过仓库源码与测试用例验证其行为。插件定位Corsair 与 Beaconstac 之间的桥梁Corsair 的目标是Connect your users to their apps而 packages/beaconstac 正是这一目标的典型落地把 BeaconstacUniqode这套面向企业级 QR 码管理、批量生成与扫码分析的 API包装成 Corsair 插件协议下的标准形态。插件包在 package.json 中以corsair-dev/beaconstac发布声明corsair 0.1.0与zod ^4.1.13为 peer 依赖版本号为 0.1.1采用 Apache-2.0 许可。从目录结构看该插件由四层组成职责清晰index.ts插件入口负责组装 auth 配置、端点注册表、schema、错误处理器与 keyBuilderclient.ts底层 HTTP 客户端封装 Uniqode 主机、Token 认证头与统一错误类型endpoints按资源域划分的 21 个 handler 及对应的 zod 输入/输出 schemaschema7 类核心实体的数据库模型zod 定义error-handlers.ts限流与鉴权错误的匹配与重试策略。安装与接入pnpm add corsair-dev/beaconstac安装后在你的 Corsair 应用中通过工厂函数创建插件实例import { beaconstac } from corsair-dev/beaconstac; const plugin beaconstac();插件工厂接收可选的BeaconstacPluginOptions见 index.ts包括authType认证类型默认且目前唯一支持api_keykey显式注入的 API Key跳过凭据存储查询hooks生命周期钩子errorHandlers自定义错误处理器会与内置处理器合并permissions端点级权限配置。认证机制API Key 优先首次使用时提示租户README 明确说明该插件使用API key认证Corsair prompts your tenant for credentials on first use即首次调用时 Corsair 会引导终端用户录入凭据。从源码看认证的完整链路如下index.tsexport const beaconstacAuthConfig { api_key: { account: [organization_id], }, } as const;account字段声明该插件的账号维度是organization_id这意味着多租户场景下每个组织organization可以绑定独立的 API Key。这与 api.test.ts 中的断言一致插件注册了api_key认证、21 个端点 schema且不包含oauth_2配置。keyBuilder 的取钥逻辑index.ts遵循三级回退若显式传入options.key直接返回该 Key跳过存储查询否则从ctx.keys.get_api_key()读取租户已保存的凭据均取不到时抛出AuthMissingError(beaconstac, api_key)提示用户补录凭据。21 个端点全览插件将 Beaconstac 的能力收敛为 21 个操作按资源域组织为places、qrTemplates、tags、users、qrcodes、bulkQrcodes、organizations、analytics八个分组端点嵌套注册表见 index.ts。下表完整继承 README 的端点清单并补充了每个操作映射到的 Uniqode HTTP 路径依据 endpoints/handlers.ts 与 api.test.tsOperationOperation IDRiskDescriptionHTTP 映射analytics.periodOverviewbeaconstac.api.analytics.periodOverviewread按产品类型查询周期概览分析POST /reporting/2.0/methodProducts.getPeriodOverviewanalytics.productOverviewbeaconstac.api.analytics.productOverviewread按时间区间查询产品概览分析POST /reporting/2.0/methodProducts.getOverviewbulkQrcodes.listbeaconstac.api.bulkQrcodes.listread列出批量 QR 码集合GET /api/2.0/bulkqrcodes/organizations.listbeaconstac.api.organizations.listread列出当前账号可访问的组织GET /api/2.0/organizations/places.createbeaconstac.api.places.createwrite为基于位置的内容创建地点POST /api/2.0/places/places.listbeaconstac.api.places.listread支持过滤、搜索与分页地列出地点GET /api/2.0/places/places.updatebeaconstac.api.places.updatewrite更新地点名称、地址或坐标PUT /api/2.0/places/{place_id}/qrcodes.deletebeaconstac.api.qrcodes.deletedestructive按 ID 删除 QR 码【破坏性】DELETE /api/2.0/qrcodes/{id}/qrcodes.getbeaconstac.api.qrcodes.getread按 ID 获取 QR 码GET /api/2.0/qrcodes/{id}/qrcodes.updatebeaconstac.api.qrcodes.updatewrite更新 QR 码名称、设计、标签或内容PUT /api/2.0/qrcodes/{qrcode_id}/qrTemplates.createbeaconstac.api.qrTemplates.createwrite创建可复用的 QR 码设计模板POST /api/2.0/qrtemplates/qrTemplates.deletebeaconstac.api.qrTemplates.deletedestructive按 ID 删除 QR 码模板【破坏性】DELETE /api/2.0/qrtemplates/{id}/qrTemplates.listbeaconstac.api.qrTemplates.listread列出某组织的 QR 码模板GET /api/2.0/qrtemplates/tags.createbeaconstac.api.tags.createwrite创建用于整理 QR 码的标签POST /api/2.0/tags/tags.deletebeaconstac.api.tags.deletedestructive按 ID 删除标签【破坏性】DELETE /api/2.0/tags/{tag_id}/tags.listbeaconstac.api.tags.listread支持过滤与分页地列出标签GET /api/2.0/tags/tags.updatebeaconstac.api.tags.updatewrite更新标签名称或颜色PUT /api/2.0/tags/{tag_id}/users.createbeaconstac.api.users.createwrite在组织下创建用户Reseller 套餐POST /api/2.0/users/add/users.getbeaconstac.api.users.getread按 ID 获取用户GET /api/2.0/users/{id}/users.listbeaconstac.api.users.listread支持过滤、搜索与分页地列出用户GET /api/2.0/users/users.updatebeaconstac.api.users.updatewrite更新用户资料或所属组织PUT /api/2.0/users/{user_id}/风险等级上read类操作用于安全查询write类用于创建与更新destructive类qrcodes.delete、qrTemplates.delete、tags.delete为不可逆操作在权限模型中应给予更高关注。Webhooks当前不提供README 明确声明No webhooks源码中beaconstacWebhooksNested为空对象、pluginWebhookMatcher恒定返回false见 index.ts。因此该插件目前仅支持主动拉取polling模式尚无事件推送能力。资源域详解与输入参数每个端点的输入参数均由 zod schema 校验见 endpoints/types.ts下面按资源域说明关键字段。Places地点places.create必填name、address、latitude、longitude、organization可选place_id、business_color、business_icon_url、business_cover_url。经纬度使用z.coerce.number()自动做字符串转数字。places.list支持page整数 ≥1、page_size1–100、name、search、ordering、name__icontains。places.update以place_id定位资源请求体通过withoutKeys剔除place_id后再 PUT见 handlers.ts。QrTemplatesQR 码模板qrTemplates.create必填name、organization可选设计字段非常丰富margin、dotScale、colorDark、colorLight、gradientType、eyeBallShape、eyeFrameShape、logoImage、logoScale、frameStyle、frameText、frameColor、dataPattern、backgroundColor、backgroundImage等覆盖 Uniqode 模板的视觉定制能力。qrTemplates.list必填organization支持name__icontains与分页。qrTemplates.delete仅需id。Tags标签tags.create必填name最长 128 字符与organization可选color。tags.list支持ordering、name__icontains与分页。tags.update以tag_id定位可改name或color。Users用户users.create必填username、organization可选email、password、first_name、last_name、billing_email、customer_plan、profile_picture、user_groupREADME 注明该操作面向Reseller 套餐。users.list过滤条件非常细search、ordering、email__exact、email__icontains、username__exact、username__icontains、first_name__exact、last_name__exact含 icontains 变体、date_joined__gt/lt/gte/lte、customer_plan、subscription_state、organization。users.get按id查询users.update按user_id定位可改姓名、组织与头像。QrcodesQR 码qrcodes.get/qrcodes.delete按id操作。qrcodes.update以qrcode_id定位可更新name、tags整数 ID 数组、place、qr_type、campaign、attributes、fields_data、meta、organization等。数据模型中qr_type为 1 表示静态码、2 表示动态码见 schema/database.ts。BulkQrcodes 与 OrganizationsbulkQrcodes.list支持search、ordering、qr_data_type、name__icontains与分页用于批量 QR 集合的检索。organizations.list仅分页参数返回count/next/previous/results结构paged()辅助 schema见 endpoints/types.ts。Analytics分析两个分析端点都走独立的 Reporting 主机路径POST /reporting/2.0/输入结构相同organization、product_type枚举beacon/nfc/qr/geofence、from_timestamp、to_timestampUnix 时间戳。底层将时间戳转为字符串放入 bodyfrom/to并通过 query 参数method区分Products.getPeriodOverview与Products.getOverview见 handlers.ts。底层调用链Token 认证与请求封装所有端点最终汇聚到 client.ts 的makeBeaconstacRequest。其关键实现主机固定为BEACONSTAC_API_BASE https://api.uniqode.comAPI 版本2.0.0认证头为Authorization: Token ${apiKey}Uniqode 的 Token 风格鉴权而非 BearerGET 请求只带 queryPOST/PUT/PATCH 请求携带application/json; charsetutf-8的 bodyquery 参数经compactQuery剔除undefined值避免发送空参数DELETE 请求若返回空响应会合成{ deleted: true }结果仅 DELETE 如此GET/PUT 的空响应保持undefined防止误判。这一点在 api.test.ts 中有针对性验证空 GET、空 PUT 不会伪造deleted: true只有空 DELETE 才会合成而空 GET 在qrcodesGet这类检索端点会直接抛出BeaconstacAPIError。错误处理与重试策略error-handlers.ts 内置了三类错误处理器RATE_LIMIT_ERROR命中BeaconstacRateLimitError、状态码 429或消息包含too many requests/rate_limited/rate limit时触发handler 返回{ maxRetries: 5, headersRetryAfterMs }即最多重试 5 次并透传服务端Retry-After头指定的等待时长。测试用例api.test.ts验证了 429 响应会携带retryAfterMs: 1500并正确匹配。AUTH_ERROR命中BeaconstacAPIError状态码 401或消息含unauthorized/invalid_auth/invalid token/401时触发handler 返回{ maxRetries: 0 }即凭据错误不重试避免无效请求反复打向服务端。DEFAULT兜底匹配所有错误同样不重试。此外client.ts 的errorMessage会依次从响应体中的detail、message、error字段提取可读错误信息供上层排查。你还可以通过插件工厂的errorHandlers选项与内置处理器合并扩展自定义错误分支。数据模型7 类核心实体插件以 schema/database.ts 定义数据库模型并在 schema/index.ts 中聚合成版本号为1.0.0的BeaconstacSchema包含 7 个实体实体关键字段BeaconstacOrganizationid、name、parent、reseller_access、whitelabel_access、custom_domain、cname、ga_code、fb_pixel_id等BeaconstacUserid、first_name、last_name、username、user_group、customer_plan、subscription_state、is_active、stripe_id、timezone、organizationBeaconstacQrCodeid、name、qr_type、url、state、organization、place、tags、template、view_limit、location_enabled、passwordBeaconstacQrTemplateid、name、default、organization、margin、dotScale、dataPattern、colorDark、colorLight、eyeBallShape、frameStyle、logoImage等BeaconstacTagid、name、color、organization、maintainerBeaconstacPlaceid、name、organization、latitude、longitude、address、beacon_count、default_placeBeaconstacBulkQrCodeid、name、qr_type、qr_data_type、organization、storage_url、media所有模型均以.loose()结尾允许未知字段透传以兼容 Uniqode API 的扩展字段同时通过 zod 约束已知字段类型。这为 Agent 侧的缓存、多租户数据隔离与类型安全的请求/响应提供了统一基础。如何验证测试即文档插件自带两套测试见 package.json 的 scriptspnpm test运行 api.test.ts覆盖认证注册、keyBuilder 取钥、Token 头格式、429/401 错误包装、21 个端点的 HTTP 路径/方法/参数映射以及分页参数校验pnpm test:live运行 integration.test.ts 的真实联调需要有效的 Uniqode API Key。其中official Uniqode request mapping测试组api.test.ts以表格驱动方式逐一断言每个端点的方法、URL、query 与 body是理解该插件与 Uniqode API 对应关系最直接的参考。小结corsair-dev/beaconstac用 21 个端点完整覆盖了 Uniqode 的 QR 码管理主链路——从组织、用户、地点等基础资源到模板、标签、批量集合等运营能力再到扫码分析报表。其 API Key 认证、organization_id账号维度、内置限流重试与鉴权错误处理使其可以开箱即用地接入 Corsair 多租户应用。仓库内的 index.ts、endpoints/handlers.ts、client.ts 与 api.test.ts 是深入研读实现细节的首选入口官方文档与完整类型示例可参见 docs/plugins/beaconstac 相关资源。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
