使用 spree/admin-sdk 集成 Spree Commerce Admin API安装、认证与资源客户端实战指南【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spreespree/admin-sdk是 Spree Commerce 官方提供的 TypeScript SDK面向 Admin API管理端 API用于从服务端到服务端的集成场景或管理工具中管理商品、订单、客户、履约、支付与店铺配置。本文以 packages/admin-sdk/README.md 为主线结合仓库内 src/client.ts、src/admin-client.ts、examples 与 tests 目录中的实现细节完整讲解安装方式、createAdminClient的每一个配置项、两种认证模式Secret Key 与 JWT、多店铺路由、查询分页与错误处理以及如何通过client.request()调用自定义扩展端点。读完本文你可以从零搭建一个类型安全的 Spree 管理端集成脚本或后台服务。一、SDK 定位与版本注意事项spree/admin-sdk是 Spree Admin API 的官方 TypeScript 客户端。README 明确说明当前 Admin API 处于Developer Preview开发者预览阶段API 仍在活跃开发中可能在 minor 版本之间发生变化。因此生产环境使用时应当将spree/admin-sdk固定pin到具体版本升级前查阅 CHANGELOG.md 中的破坏性变更说明。从仓库 package.json 可以看到当前 SDK 版本为0.8.1作者为 Vendo Connect Inc.采用 MIT 许可证。该 SDK 的构建与工程化信息如下项目值说明模块格式type: module同时输出dist/index.cjs与dist/index.js同时支持 ESMimport与 CommonJSrequire见 package.jsonexports字段运行时要求node 18.0.0使用全局fetch作为默认请求实现类型系统typescript 4.7.0可选 peer 依赖类型声明文件随包发布构建工具tsup见 tsup.config.ts测试框架Vitest MSWMock Service Worker见 vitest.config.ts 与 tests 目录SDK 位于 Spree 仓库monorepo的packages/admin-sdk目录下类型声明由仓库内的 serializer → types → Zod 生成管线产出README Contributing 一节对此有说明。二、安装在任意 Node.js 18 项目中执行npm install spree/admin-sdk若使用 pnpm 或 yarnpnpm add spree/admin-sdk # 或 yarn add spree/admin-sdk安装完成后SDK 通过主入口导出createAdminClient、AdminClient类、全部参数类型*Params与实体类型Product、Order、Customer等并再导出请求基础设施SpreeError、RequestOptions、RetryConfig等类型。详见 src/index.ts// 主客户端 export { createAdminClient } from ./client export type { AdminClientConfig, Client } from ./client // 高级用法 / 子类化 export { AdminClient } from ./admin-client // 错误对象与请求基础设施 export { SpreeError } from spree/sdk-core // 参数类型与实体类型 export type * from ./params export * from ./types三、快速开始README 给出的最小示例即可完成「认证 → 查询已完成订单 → 创建客户」三个动作import { createAdminClient } from spree/admin-sdk const client createAdminClient({ baseUrl: https://store.example.com, secretKey: sk_xxx, // 服务端到服务端集成管理端 UI 场景请使用 JWT }) const { data: orders } await client.orders.list({ status_eq: complete, sort: -completed_at, limit: 25, }) const customer await client.customers.create({ email: janeexample.com, first_name: Jane, last_name: Doe, tags: [wholesale], })几点关键信息client.orders.list()返回PaginatedResponseOrder解构data拿到当前页的订单数组meta中携带分页信息。status_eq是 Ransack 风格的过滤谓词Rails 生态的标准查询语法sort: -completed_at表示按完成时间降序排序-前缀即降序limit控制单页条数。仓库 examples/customers/create.ts 提供了更完整的客户创建示例额外展示了phone、accepts_email_marketing等字段import { createAdminClient } from spree/admin-sdk const client createAdminClient({ baseUrl: https://your-store.com, secretKey: sk_xxx, }) const customer await client.customers.create({ email: janeexample.com, first_name: Jane, last_name: Doe, phone: 1 212 555 1234, tags: [wholesale], accepts_email_marketing: true, })在examples/目录下几乎每个资源都有一组独立的可运行示例create.ts/list.ts/get.ts/update.ts/delete.ts/ 批量操作等例如examples/orders/、examples/products/、examples/customers/、examples/order-fulfillments/等 60 余个目录是学习每个资源客户端用法的第一手材料。四、createAdminClient配置项全解createAdminClient(config: AdminClientConfig)是 SDK 的入口工厂函数。所有配置项定义在 src/client.ts 中配置项类型是否必填说明baseUrlstring必填Spree API 的基地址例如https://api.mystore.com。传可使用相对 URL适用于 Vite 开发代理场景。构造时末尾的/会被自动去除secretKeystring可选服务端到服务端集成使用的密钥与jwtToken互斥jwtTokenstring可选管理端 SPA 会话的 JWT与secretKey互斥storeIdstring可选多店铺路由用的店铺 ID 头例如store_k5nR8xLqfetchtypeof fetch可选自定义 fetch 实现默认使用全局fetchNode 18 自带retryRetryConfig \| false可选重试配置默认开启传false可关闭credentialsRequestCredentials可选跨域请求的凭据模式默认include以便管理端 refresh-token Cookie 能随/api/v3/admin/auth/*请求发送在不应携带 Cookie 的嵌入环境中请覆盖此值在createAdminClient内部src/client.ts实现做了这几件事规整baseUrl解析重试配置与默认凭据固定所有请求的基础路径为/api/v3/admin维护内部状态currentToken与currentStoreId并提供setToken、setStore运行时更新入口对每个请求注入认证头与多店铺路由头详见下文认证与多店铺章节。五、两种认证模式Secret Key 与 Admin JWTREADME 强调「scoped secret keys vs. admin JWT」是认证的核心区分。从 src/client.ts 的实现可以看出两种模式的传输方式截然不同const makeRequest () { // Secret keys go in X-Spree-Api-Key (server-to-server integrations). // JWT tokens go in Authorization: Bearer (admin SPA sessions). const auth config.secretKey ? { headerName: X-Spree-Api-Key, headerValue: config.secretKey } : { headerName: Authorization, headerValue: currentToken ? Bearer ${currentToken} : } const requestFn createRequestFn(requestConfig, basePath, auth) return requestFnT(method, path, mergedOptions) }场景使用方式请求头发送方式服务端到服务端集成脚本、后台任务、3PL 对接secretKey: sk_xxx请求头X-Spree-Api-Key: sk_xxx管理端 SPA 会话浏览器jwtToken或运行时setToken(token)请求头Authorization: Bearer token5.1 JWT 会话管理Client接口src/client.ts为管理端 UI 场景提供了三个运行时方法setStore(storeId: string)切换后续请求的目标店铺多店铺路由setToken(token: string)更新 JWT用于登录/刷新后注入新 tokenonUnauthorized(handler)注册 401 回调。回调返回true时SDK 会在你通过setToken刷新 token 后自动重放原请求一次返回false则让错误继续向外抛出。对应的 401 重试逻辑位于 src/client.ts只有error instanceof SpreeError且status 401、且已注册 handler、且当前请求路径不包含/auth/认证端点自身不参与重试防止死循环时才会触发一次重试。5.2 认证相关的资源端点client.auth命名空间src/admin-client.ts封装了完整的认证流程方法HTTP路径说明auth.login(credentials)POST/api/v3/admin/auth/login用凭据换访问令牌refresh token 通过 HttpOnly Cookie作用于/api/v3/admin/auth下发不会出现在响应体auth.refresh()POST/auth/refresh轮换 refresh Cookie 并获取新访问令牌由 SDK 自动携带X-CSRF-Token头auth.logout()POST/auth/logout服务端吊销 refresh token 并清除认证 Cookie幂等auth.providers()GET/auth/providers列出店铺接受的认证提供商密码表单 / SSO 跳转登录页据此决定渲染auth.lookupInvitation(id, token)GET/auth/invitations/:id/lookup公开查询待处理邀请的上下文店铺、角色、邀请人、受邀者是否已存在auth.acceptInvitation(id, token, params)POST/auth/invitations/:id/accept公开接受邀请成功后签发 JWT refresh Cookieauth.setupStatus()GET/auth/setup首启设置可用性检查仅当尚无管理员时返回 trueauth.setupCountries()GET/auth/setup/countries首启可设置的国家列表含货币与官方语言auth.completeSetup(params)POST/auth/setup首启设置创建第一个管理员并命名店铺auth.requestPasswordReset(params)POST/auth/password_resets请求密码重置邮件无论邮箱是否存在都返回 202防枚举auth.resetPassword(token, params)PATCH/auth/password_resets/:token消费一次性重置令牌设置新密码并登录5.3 当前管理员与权限client.me提供get()读取当前管理员资料与序列化权限和update(params)自改selected_locale、first_name、last_name见 src/admin-client.ts。MeResponse中的permissions是一组PermissionRuleallow/actions/subjects/has_conditionspermission_keys是扁平展开的权限键如read_orders、write_productswrite_x总伴随read_x与 API Key scope 词汇一致。六、多店铺路由Multi-storeSpree 支持单实例多店铺。SDK 通过X-Spree-Store-Id请求头实现路由配置时传storeId或运行时调用client.setStore(storeId)从实现看src/client.ts认证类路径/auth/开头不会携带该头——登录、刷新、设置、邀请接受等动作发生在选择店铺之前残留的旧店铺 ID 不应影响这些端点的可用性// 认证端点 store-agnosticlogin/refresh/setup/邀请接受 if (currentStoreId !path.startsWith(/auth/)) { extraHeaders[X-Spree-Store-Id] currentStoreId }这一设计对多租户 / 多品牌运营非常实用一个服务进程可以通过setStore在多个店铺间切换而无需重建客户端。七、资源客户端全景管理端能力地图AdminClient类src/admin-client.ts为每个 REST 资源暴露一个命名空间客户端统一遵循list / get / create / update / delete的 CRUD 约定并在其上叠加领域级动作。README 将其概括为「manage products, orders, customers, fulfillments, payments, and store configuration」。从源码5796 行的admin-client.ts与 examples 目录可以确认如下资源地图核心交易域productsCRUD clone复制返回状态draft、名称带 COPY OF 前缀、approve/reject卖家商品审核、bulkStatusUpdate、bulkAddToCategories、bulkAddToCollections、bulkAddToChannels、bulkAddTags、bulkDestroy等批量操作嵌套media媒体库、digitalAssets数字资产含providers发现、variants含 variant 级media、customFields、translationsordersCRUD complete/cancel/approve/resendConfirmation/resendDigitalLinks嵌套items行项目、fulfillments履约含fulfill、markDelivered、split、labels、deliveries、returns含labels、exchanges、claims、paymentscapture/void、refunds、taxLines、discounts手工折扣、discountCodes、fees、giftCards、storeCredits、customFieldscustomers与customerGroups客户管理、分组、批量打标签、批量入组/移组见 examples/customersoptionTypes选项类型 CRUD customFieldstranslations。履约与配送deliveryMethods配送方式含calculators、fulfillmentProviders、rateProviders、rules、ruleTypes等发现端点deliveryProfiles配送画像含kinds、originGroupsdeliveryZones配送区域expand: [members]才能编辑成员packageTypes包裹类型设置default会降级原默认项trackingCarriers注册的追踪承运商列表stockLocations/stockLevels/stockMovements/stockTransfers/stockReceipts库存运营。价格与商品目录priceLists价格表批发/区域/量级定价update一次 PATCH 可同时提交成员、规则与逐行价格覆盖prices、markets、catalogs目录与目录分配、最低订购额collections/categories/channels渠道含orderRoutingRules订单路由规则productTypes、customFieldDefinitions自定义字段定义含resourceTypes发现端点。客户关系与财务companies/companyTaxIdentifiers/companyMemberships/companyInvitationsgiftCards/giftCardBatches/couponCodes/customerStoreCreditssellers/suppliers/commissionRates/commissionLinespurchaseOrders/policies/taxCategories/taxRates/taxExemptionCertificates。平台与基础设施auth、me、reporting语义报表query/schema/savedReports、dashboardcounters看板计数store店铺设置含dataSources定价/库存引擎发现、locales、translatableResources、translations批量原子翻译写入imports/exports异步 CSV 导入导出见 CHANGELOG 0.6.0、directUploads直传 blobintegrations集成凭据含types与test连接检测apiKeys支持channel_id渠道绑定见 CHANGELOG 0.7.0、roles、permissions、invitations、adminUsers、allowedOriginswebhookEndpoints、paymentMethods、refundReasons、returnReasons、orderCancellationReasons等配置字典。说明上表中的资源清单来自 src/admin-client.ts截至 0.8.1 已覆盖 60 资源与 examples 目录结构未逐一列出全部嵌套方法每个命名空间的具体签名请以源码与配套类型为准。7.1 嵌套资源的统一协议源码中有三个值得关注的「统一协议」模式父级作用域自定义字段parentScopedCustomFieldssrc/admin-client.ts商品、订单、客户、分类、集合、选项类型等资源都挂载customFields.list/get/create/update/delete写法统一为client.products.customFields.list(productId)产品成员关系productMembershipsrc/admin-client.ts分类、集合、目录、价格表都以相同协议维护成员批量添加/移除已存在的 ID 不报错、非成员移除被忽略并返回实际变更计数added_count/removed_count分类与集合额外支持reposition0-based 拖拽排序翻译读侧通过各资源的translations.get(id)取完整「区域 × 字段」矩阵写侧统一走client.translations.batch(entries)一次原子提交跨多记录如一个选项类型连同其所有选项值的翻译。7.2 泛型逃生舱client.request()对于扩展 gem 新增、尚未内置客户端的自定义端点AdminClient暴露了底层request方法src/admin-client.ts。它复用与内置资源完全相同的认证头、重试逻辑与 base URL路径相对于/api/v3/adminimport { createAdminClient } from spree/admin-sdk import type { PaginatedResponse } from spree/admin-sdk interface Brand { id: string; name: string; slug: string } const client createAdminClient({ baseUrl: https://api.shop.com, secretKey: sk_xxx }) const brands await client.requestPaginatedResponseBrand(GET, /brands) const brand await client.requestBrand(GET, /brands/brand_2X9aQf7kEw)这一设计意味着即使 Spree 端由插件注册了新端点集成方也可以零等待获得类型安全通过泛型的调用能力。八、查询、过滤、排序与分页所有list方法接受ListParams Recordstring, unknown由spree/sdk-core的transformListParams处理。核心约定过滤Ransack 谓词如status_eq: complete、price_list_id_eq: ...、currency_eq: ...。谓词会被包装进q[...]查询参数交给服务端排序sort: field升序sort: -field降序分页page与limit配合meta中的分页元数据PaginatedResponse同时返回data与meta展开get(id, { expand: [...] })用expand拉取嵌套关系例如customers.get(id, { expand: [newsletter_subscriber] })CHANGELOG 0.6.1 新增的订阅展开。一个细节陷阱源码有专门注释translations.coverage(resourceType, params)中resource_type与search是普通参数若经过transformListParams会被包装成q[resource_type]导致服务端读不到因此实现里特意将其拆出直接传参src/admin-client.ts。这提醒集成方并非所有参数都走 Ransack 包装个别端点以服务端签名为准。九、错误处理SpreeErrorSDK 从spree/sdk-core再导出SpreeError见 src/index.ts。它是所有请求失败的标准错误类型携带status字段可通过instanceof判断后按状态码分流处理import { createAdminClient, SpreeError } from spree/admin-sdk try { await client.orders.complete(orderId) } catch (error) { if (error instanceof SpreeError) { if (error.status 401) { // 未认证走 refresh 流程或提示登录 } else if (error.status 403) { // 权限不足服务端规则可能按记录级拒绝见 PermissionRule.has_conditions } else if (error.status 422) { // 校验失败如对促销来源的折扣行执行编辑会返回 discount_not_editable } } throw error }配套的重试机制默认开启可通过retry: false关闭服务端 4xx/5xx 与网络错误会按RetryConfig进行退避重试。十、进阶模式与最佳实践综合 README、源码与 CHANGELOG以下模式值得在生产集成中采用版本固定由于 Admin API 处于 Developer Preview建议在package.json中固定精确版本或使用 lockfile升级前通读 CHANGELOG.md。例如 0.8.1 将导入导出的type从 Ruby 类名Spree::Imports::Products改为 API 简写products属于破坏性变更认证选型纯服务端任务用secretKeyX-Spree-Api-Key头管理端 UI 用 JWT onUnauthorized自动刷新 401 重试不要让 secret key 出现在浏览器端多店铺切换多租户服务用setStore动态切换X-Spree-Store-Id避免为每个店铺重建客户端优先使用内置批量端点批量打标签、批量分类/集合/渠道关联、批量状态更新都是一次请求完成且返回实际变更计数比循环调用单条接口更高效、更一致利用发现端点驱动 UIreporting.schema()、deliveryMethods.calculators()、paymentMethods.types()、integrations.types()、customFieldDefinitions.resourceTypes()等返回注册表信息适合驱动下拉框、表单 schema 与 Agent 工具定义插件新增的能力无需升级 SDK 即可呈现参考仓库测试tests/目录如 customers.test.ts、orders.test.ts、products.test.ts使用 Vitest MSW 对每个资源客户端做契约测试是理解请求/响应形状的最佳示例。十一、本地开发与贡献README 指出 SDK 位于 spree/spree 仓库即本仓库的packages/admin-sdk下。本地开发相关脚本见 package.json# 构建tsup npm run build # 类型检查含 examples npm run typecheck # 运行测试 npm test # 代码规范 npm run lint客户端代码由scripts/generate-admin-client.ts基于服务端契约生成npm run generate:admin-client新版本发版前npm run prepublishOnly会自动构建。十二、许可证与资源索引spree/admin-sdk以 MIT 许可证发布见 packages/admin-sdk/LICENSE。本文涉及的关键仓库资源汇总如下便于继续深入主文档packages/admin-sdk/README.md客户端工厂与配置项packages/admin-sdk/src/client.ts资源客户端实现packages/admin-sdk/src/admin-client.ts包入口与导出packages/admin-sdk/src/index.ts参数类型packages/admin-sdk/src/params.ts可运行示例packages/admin-sdk/examples契约测试packages/admin-sdk/tests版本变更记录packages/admin-sdk/CHANGELOG.md工程配置packages/admin-sdk/package.json从安装、双认证模式、多店铺路由到覆盖 60 资源的客户端地图与自定义端点扩展spree/admin-sdk为 Spree 管理端集成提供了完整的类型安全解决方案。将本文的配置表与源码路径结合使用你可以在数分钟内搭建出首个可运行的管理端集成并在此基础上安全地支撑生产级业务。【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 22:55:28 · 阅读 1.2k 使用 @spree/admin-sdk 集成 Spree Commerce Admin API：安装、认证与资源客户端实战指南
使用 spree/admin-sdk 集成 Spree Commerce Admin API安装、认证与资源客户端实战指南【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spreespree/admin-sdk是 Spree Commerce 官方提供的 TypeScript SDK面向 Admin API管理端 API用于从服务端到服务端的集成场景或管理工具中管理商品、订单、客户、履约、支付与店铺配置。本文以 packages/admin-sdk/README.md 为主线结合仓库内 src/client.ts、src/admin-client.ts、examples 与 tests 目录中的实现细节完整讲解安装方式、createAdminClient的每一个配置项、两种认证模式Secret Key 与 JWT、多店铺路由、查询分页与错误处理以及如何通过client.request()调用自定义扩展端点。读完本文你可以从零搭建一个类型安全的 Spree 管理端集成脚本或后台服务。一、SDK 定位与版本注意事项spree/admin-sdk是 Spree Admin API 的官方 TypeScript 客户端。README 明确说明当前 Admin API 处于Developer Preview开发者预览阶段API 仍在活跃开发中可能在 minor 版本之间发生变化。因此生产环境使用时应当将spree/admin-sdk固定pin到具体版本升级前查阅 CHANGELOG.md 中的破坏性变更说明。从仓库 package.json 可以看到当前 SDK 版本为0.8.1作者为 Vendo Connect Inc.采用 MIT 许可证。该 SDK 的构建与工程化信息如下项目值说明模块格式type: module同时输出dist/index.cjs与dist/index.js同时支持 ESMimport与 CommonJSrequire见 package.jsonexports字段运行时要求node 18.0.0使用全局fetch作为默认请求实现类型系统typescript 4.7.0可选 peer 依赖类型声明文件随包发布构建工具tsup见 tsup.config.ts测试框架Vitest MSWMock Service Worker见 vitest.config.ts 与 tests 目录SDK 位于 Spree 仓库monorepo的packages/admin-sdk目录下类型声明由仓库内的 serializer → types → Zod 生成管线产出README Contributing 一节对此有说明。二、安装在任意 Node.js 18 项目中执行npm install spree/admin-sdk若使用 pnpm 或 yarnpnpm add spree/admin-sdk # 或 yarn add spree/admin-sdk安装完成后SDK 通过主入口导出createAdminClient、AdminClient类、全部参数类型*Params与实体类型Product、Order、Customer等并再导出请求基础设施SpreeError、RequestOptions、RetryConfig等类型。详见 src/index.ts// 主客户端 export { createAdminClient } from ./client export type { AdminClientConfig, Client } from ./client // 高级用法 / 子类化 export { AdminClient } from ./admin-client // 错误对象与请求基础设施 export { SpreeError } from spree/sdk-core // 参数类型与实体类型 export type * from ./params export * from ./types三、快速开始README 给出的最小示例即可完成「认证 → 查询已完成订单 → 创建客户」三个动作import { createAdminClient } from spree/admin-sdk const client createAdminClient({ baseUrl: https://store.example.com, secretKey: sk_xxx, // 服务端到服务端集成管理端 UI 场景请使用 JWT }) const { data: orders } await client.orders.list({ status_eq: complete, sort: -completed_at, limit: 25, }) const customer await client.customers.create({ email: janeexample.com, first_name: Jane, last_name: Doe, tags: [wholesale], })几点关键信息client.orders.list()返回PaginatedResponseOrder解构data拿到当前页的订单数组meta中携带分页信息。status_eq是 Ransack 风格的过滤谓词Rails 生态的标准查询语法sort: -completed_at表示按完成时间降序排序-前缀即降序limit控制单页条数。仓库 examples/customers/create.ts 提供了更完整的客户创建示例额外展示了phone、accepts_email_marketing等字段import { createAdminClient } from spree/admin-sdk const client createAdminClient({ baseUrl: https://your-store.com, secretKey: sk_xxx, }) const customer await client.customers.create({ email: janeexample.com, first_name: Jane, last_name: Doe, phone: 1 212 555 1234, tags: [wholesale], accepts_email_marketing: true, })在examples/目录下几乎每个资源都有一组独立的可运行示例create.ts/list.ts/get.ts/update.ts/delete.ts/ 批量操作等例如examples/orders/、examples/products/、examples/customers/、examples/order-fulfillments/等 60 余个目录是学习每个资源客户端用法的第一手材料。四、createAdminClient配置项全解createAdminClient(config: AdminClientConfig)是 SDK 的入口工厂函数。所有配置项定义在 src/client.ts 中配置项类型是否必填说明baseUrlstring必填Spree API 的基地址例如https://api.mystore.com。传可使用相对 URL适用于 Vite 开发代理场景。构造时末尾的/会被自动去除secretKeystring可选服务端到服务端集成使用的密钥与jwtToken互斥jwtTokenstring可选管理端 SPA 会话的 JWT与secretKey互斥storeIdstring可选多店铺路由用的店铺 ID 头例如store_k5nR8xLqfetchtypeof fetch可选自定义 fetch 实现默认使用全局fetchNode 18 自带retryRetryConfig \| false可选重试配置默认开启传false可关闭credentialsRequestCredentials可选跨域请求的凭据模式默认include以便管理端 refresh-token Cookie 能随/api/v3/admin/auth/*请求发送在不应携带 Cookie 的嵌入环境中请覆盖此值在createAdminClient内部src/client.ts实现做了这几件事规整baseUrl解析重试配置与默认凭据固定所有请求的基础路径为/api/v3/admin维护内部状态currentToken与currentStoreId并提供setToken、setStore运行时更新入口对每个请求注入认证头与多店铺路由头详见下文认证与多店铺章节。五、两种认证模式Secret Key 与 Admin JWTREADME 强调「scoped secret keys vs. admin JWT」是认证的核心区分。从 src/client.ts 的实现可以看出两种模式的传输方式截然不同const makeRequest () { // Secret keys go in X-Spree-Api-Key (server-to-server integrations). // JWT tokens go in Authorization: Bearer (admin SPA sessions). const auth config.secretKey ? { headerName: X-Spree-Api-Key, headerValue: config.secretKey } : { headerName: Authorization, headerValue: currentToken ? Bearer ${currentToken} : } const requestFn createRequestFn(requestConfig, basePath, auth) return requestFnT(method, path, mergedOptions) }场景使用方式请求头发送方式服务端到服务端集成脚本、后台任务、3PL 对接secretKey: sk_xxx请求头X-Spree-Api-Key: sk_xxx管理端 SPA 会话浏览器jwtToken或运行时setToken(token)请求头Authorization: Bearer token5.1 JWT 会话管理Client接口src/client.ts为管理端 UI 场景提供了三个运行时方法setStore(storeId: string)切换后续请求的目标店铺多店铺路由setToken(token: string)更新 JWT用于登录/刷新后注入新 tokenonUnauthorized(handler)注册 401 回调。回调返回true时SDK 会在你通过setToken刷新 token 后自动重放原请求一次返回false则让错误继续向外抛出。对应的 401 重试逻辑位于 src/client.ts只有error instanceof SpreeError且status 401、且已注册 handler、且当前请求路径不包含/auth/认证端点自身不参与重试防止死循环时才会触发一次重试。5.2 认证相关的资源端点client.auth命名空间src/admin-client.ts封装了完整的认证流程方法HTTP路径说明auth.login(credentials)POST/api/v3/admin/auth/login用凭据换访问令牌refresh token 通过 HttpOnly Cookie作用于/api/v3/admin/auth下发不会出现在响应体auth.refresh()POST/auth/refresh轮换 refresh Cookie 并获取新访问令牌由 SDK 自动携带X-CSRF-Token头auth.logout()POST/auth/logout服务端吊销 refresh token 并清除认证 Cookie幂等auth.providers()GET/auth/providers列出店铺接受的认证提供商密码表单 / SSO 跳转登录页据此决定渲染auth.lookupInvitation(id, token)GET/auth/invitations/:id/lookup公开查询待处理邀请的上下文店铺、角色、邀请人、受邀者是否已存在auth.acceptInvitation(id, token, params)POST/auth/invitations/:id/accept公开接受邀请成功后签发 JWT refresh Cookieauth.setupStatus()GET/auth/setup首启设置可用性检查仅当尚无管理员时返回 trueauth.setupCountries()GET/auth/setup/countries首启可设置的国家列表含货币与官方语言auth.completeSetup(params)POST/auth/setup首启设置创建第一个管理员并命名店铺auth.requestPasswordReset(params)POST/auth/password_resets请求密码重置邮件无论邮箱是否存在都返回 202防枚举auth.resetPassword(token, params)PATCH/auth/password_resets/:token消费一次性重置令牌设置新密码并登录5.3 当前管理员与权限client.me提供get()读取当前管理员资料与序列化权限和update(params)自改selected_locale、first_name、last_name见 src/admin-client.ts。MeResponse中的permissions是一组PermissionRuleallow/actions/subjects/has_conditionspermission_keys是扁平展开的权限键如read_orders、write_productswrite_x总伴随read_x与 API Key scope 词汇一致。六、多店铺路由Multi-storeSpree 支持单实例多店铺。SDK 通过X-Spree-Store-Id请求头实现路由配置时传storeId或运行时调用client.setStore(storeId)从实现看src/client.ts认证类路径/auth/开头不会携带该头——登录、刷新、设置、邀请接受等动作发生在选择店铺之前残留的旧店铺 ID 不应影响这些端点的可用性// 认证端点 store-agnosticlogin/refresh/setup/邀请接受 if (currentStoreId !path.startsWith(/auth/)) { extraHeaders[X-Spree-Store-Id] currentStoreId }这一设计对多租户 / 多品牌运营非常实用一个服务进程可以通过setStore在多个店铺间切换而无需重建客户端。七、资源客户端全景管理端能力地图AdminClient类src/admin-client.ts为每个 REST 资源暴露一个命名空间客户端统一遵循list / get / create / update / delete的 CRUD 约定并在其上叠加领域级动作。README 将其概括为「manage products, orders, customers, fulfillments, payments, and store configuration」。从源码5796 行的admin-client.ts与 examples 目录可以确认如下资源地图核心交易域productsCRUD clone复制返回状态draft、名称带 COPY OF 前缀、approve/reject卖家商品审核、bulkStatusUpdate、bulkAddToCategories、bulkAddToCollections、bulkAddToChannels、bulkAddTags、bulkDestroy等批量操作嵌套media媒体库、digitalAssets数字资产含providers发现、variants含 variant 级media、customFields、translationsordersCRUD complete/cancel/approve/resendConfirmation/resendDigitalLinks嵌套items行项目、fulfillments履约含fulfill、markDelivered、split、labels、deliveries、returns含labels、exchanges、claims、paymentscapture/void、refunds、taxLines、discounts手工折扣、discountCodes、fees、giftCards、storeCredits、customFieldscustomers与customerGroups客户管理、分组、批量打标签、批量入组/移组见 examples/customersoptionTypes选项类型 CRUD customFieldstranslations。履约与配送deliveryMethods配送方式含calculators、fulfillmentProviders、rateProviders、rules、ruleTypes等发现端点deliveryProfiles配送画像含kinds、originGroupsdeliveryZones配送区域expand: [members]才能编辑成员packageTypes包裹类型设置default会降级原默认项trackingCarriers注册的追踪承运商列表stockLocations/stockLevels/stockMovements/stockTransfers/stockReceipts库存运营。价格与商品目录priceLists价格表批发/区域/量级定价update一次 PATCH 可同时提交成员、规则与逐行价格覆盖prices、markets、catalogs目录与目录分配、最低订购额collections/categories/channels渠道含orderRoutingRules订单路由规则productTypes、customFieldDefinitions自定义字段定义含resourceTypes发现端点。客户关系与财务companies/companyTaxIdentifiers/companyMemberships/companyInvitationsgiftCards/giftCardBatches/couponCodes/customerStoreCreditssellers/suppliers/commissionRates/commissionLinespurchaseOrders/policies/taxCategories/taxRates/taxExemptionCertificates。平台与基础设施auth、me、reporting语义报表query/schema/savedReports、dashboardcounters看板计数store店铺设置含dataSources定价/库存引擎发现、locales、translatableResources、translations批量原子翻译写入imports/exports异步 CSV 导入导出见 CHANGELOG 0.6.0、directUploads直传 blobintegrations集成凭据含types与test连接检测apiKeys支持channel_id渠道绑定见 CHANGELOG 0.7.0、roles、permissions、invitations、adminUsers、allowedOriginswebhookEndpoints、paymentMethods、refundReasons、returnReasons、orderCancellationReasons等配置字典。说明上表中的资源清单来自 src/admin-client.ts截至 0.8.1 已覆盖 60 资源与 examples 目录结构未逐一列出全部嵌套方法每个命名空间的具体签名请以源码与配套类型为准。7.1 嵌套资源的统一协议源码中有三个值得关注的「统一协议」模式父级作用域自定义字段parentScopedCustomFieldssrc/admin-client.ts商品、订单、客户、分类、集合、选项类型等资源都挂载customFields.list/get/create/update/delete写法统一为client.products.customFields.list(productId)产品成员关系productMembershipsrc/admin-client.ts分类、集合、目录、价格表都以相同协议维护成员批量添加/移除已存在的 ID 不报错、非成员移除被忽略并返回实际变更计数added_count/removed_count分类与集合额外支持reposition0-based 拖拽排序翻译读侧通过各资源的translations.get(id)取完整「区域 × 字段」矩阵写侧统一走client.translations.batch(entries)一次原子提交跨多记录如一个选项类型连同其所有选项值的翻译。7.2 泛型逃生舱client.request()对于扩展 gem 新增、尚未内置客户端的自定义端点AdminClient暴露了底层request方法src/admin-client.ts。它复用与内置资源完全相同的认证头、重试逻辑与 base URL路径相对于/api/v3/adminimport { createAdminClient } from spree/admin-sdk import type { PaginatedResponse } from spree/admin-sdk interface Brand { id: string; name: string; slug: string } const client createAdminClient({ baseUrl: https://api.shop.com, secretKey: sk_xxx }) const brands await client.requestPaginatedResponseBrand(GET, /brands) const brand await client.requestBrand(GET, /brands/brand_2X9aQf7kEw)这一设计意味着即使 Spree 端由插件注册了新端点集成方也可以零等待获得类型安全通过泛型的调用能力。八、查询、过滤、排序与分页所有list方法接受ListParams Recordstring, unknown由spree/sdk-core的transformListParams处理。核心约定过滤Ransack 谓词如status_eq: complete、price_list_id_eq: ...、currency_eq: ...。谓词会被包装进q[...]查询参数交给服务端排序sort: field升序sort: -field降序分页page与limit配合meta中的分页元数据PaginatedResponse同时返回data与meta展开get(id, { expand: [...] })用expand拉取嵌套关系例如customers.get(id, { expand: [newsletter_subscriber] })CHANGELOG 0.6.1 新增的订阅展开。一个细节陷阱源码有专门注释translations.coverage(resourceType, params)中resource_type与search是普通参数若经过transformListParams会被包装成q[resource_type]导致服务端读不到因此实现里特意将其拆出直接传参src/admin-client.ts。这提醒集成方并非所有参数都走 Ransack 包装个别端点以服务端签名为准。九、错误处理SpreeErrorSDK 从spree/sdk-core再导出SpreeError见 src/index.ts。它是所有请求失败的标准错误类型携带status字段可通过instanceof判断后按状态码分流处理import { createAdminClient, SpreeError } from spree/admin-sdk try { await client.orders.complete(orderId) } catch (error) { if (error instanceof SpreeError) { if (error.status 401) { // 未认证走 refresh 流程或提示登录 } else if (error.status 403) { // 权限不足服务端规则可能按记录级拒绝见 PermissionRule.has_conditions } else if (error.status 422) { // 校验失败如对促销来源的折扣行执行编辑会返回 discount_not_editable } } throw error }配套的重试机制默认开启可通过retry: false关闭服务端 4xx/5xx 与网络错误会按RetryConfig进行退避重试。十、进阶模式与最佳实践综合 README、源码与 CHANGELOG以下模式值得在生产集成中采用版本固定由于 Admin API 处于 Developer Preview建议在package.json中固定精确版本或使用 lockfile升级前通读 CHANGELOG.md。例如 0.8.1 将导入导出的type从 Ruby 类名Spree::Imports::Products改为 API 简写products属于破坏性变更认证选型纯服务端任务用secretKeyX-Spree-Api-Key头管理端 UI 用 JWT onUnauthorized自动刷新 401 重试不要让 secret key 出现在浏览器端多店铺切换多租户服务用setStore动态切换X-Spree-Store-Id避免为每个店铺重建客户端优先使用内置批量端点批量打标签、批量分类/集合/渠道关联、批量状态更新都是一次请求完成且返回实际变更计数比循环调用单条接口更高效、更一致利用发现端点驱动 UIreporting.schema()、deliveryMethods.calculators()、paymentMethods.types()、integrations.types()、customFieldDefinitions.resourceTypes()等返回注册表信息适合驱动下拉框、表单 schema 与 Agent 工具定义插件新增的能力无需升级 SDK 即可呈现参考仓库测试tests/目录如 customers.test.ts、orders.test.ts、products.test.ts使用 Vitest MSW 对每个资源客户端做契约测试是理解请求/响应形状的最佳示例。十一、本地开发与贡献README 指出 SDK 位于 spree/spree 仓库即本仓库的packages/admin-sdk下。本地开发相关脚本见 package.json# 构建tsup npm run build # 类型检查含 examples npm run typecheck # 运行测试 npm test # 代码规范 npm run lint客户端代码由scripts/generate-admin-client.ts基于服务端契约生成npm run generate:admin-client新版本发版前npm run prepublishOnly会自动构建。十二、许可证与资源索引spree/admin-sdk以 MIT 许可证发布见 packages/admin-sdk/LICENSE。本文涉及的关键仓库资源汇总如下便于继续深入主文档packages/admin-sdk/README.md客户端工厂与配置项packages/admin-sdk/src/client.ts资源客户端实现packages/admin-sdk/src/admin-client.ts包入口与导出packages/admin-sdk/src/index.ts参数类型packages/admin-sdk/src/params.ts可运行示例packages/admin-sdk/examples契约测试packages/admin-sdk/tests版本变更记录packages/admin-sdk/CHANGELOG.md工程配置packages/admin-sdk/package.json从安装、双认证模式、多店铺路由到覆盖 60 资源的客户端地图与自定义端点扩展spree/admin-sdk为 Spree 管理端集成提供了完整的类型安全解决方案。将本文的配置表与源码路径结合使用你可以在数分钟内搭建出首个可运行的管理端集成并在此基础上安全地支撑生产级业务。【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考