@godaddy/gd-commerce-server

中文文档
0.4.1发布于 2026/11/07MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 1.1万

GoDaddy Commerce 的意见快递服务器集成

中文使用文档
文档目录6 节
  1. 主机配置
  2. 路由器和辅助器
  3. 产品频道能见度
  4. 检查返回目的地
  5. 连接状态
  6. 错误

@godaddy/gd-commerce-服务器

GoDaddy Commercial Catalog, 推车的透视快递路由器.

import express from 'express';
import { createCommerceRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';

const app = express();
app.use(express.json());
app.use('/api/commerce', createCommerceRouter({
  configuration: createRuntimeCommerceConfiguration(),
  checkoutReturnUrls: {
    returnUrls: ['https://shop.example.com/shop'],
    successUrls: ['https://shop.example.com/checkout/success'],
  },
}));

默认配置读取这些 只使用服务器的环境变量 根据每项请求:

  • GODADDY_OAUTH_CLIENT_ID 财务报告和审定财务报表 GODADDY_OAUTH_CLIENT_SECRET
  • GODADDY_STORE_ID 财务报告和审定财务报表 GODADDY_CHANNEL_ID
  • GODADDY_CURRENCY_CODE
  • 可选 GODADDY_CHECKOUT_CONFIGURATIONJSON 有布尔语 enablePromotionCodes, (中文(简体) ), enableTaxCollection,以及 enableShipping 字段。 当该变量缺失或变异时, 全部三处默认为虚假, 因此配置发现无法阻止退出创建 。 可选 shipping 接受检出 API 的 originAddress 或者说 fulfillmentLocationId; 省略它以使用存储配置.

见 退出配置 用于临时建设时间同步流动及其最终一致性限制.

API 来源默认为 https://api.godaddy.com。软件包不装入文件、提供商或指定应用程序属性。 东道国拥有这些关切和任何准备状态检查或复议,然后才援引商务.

主机配置

对于一个可替代的 API 源,通过一个明确的服务器控制选项. 它必须是没有证书、路径、查询或片段的HTTPS来源。 主办方负责信任接收OAuth证书的目的地. 请求机构从不选择API来源或归属.

const configuration = createRuntimeCommerceConfiguration({
  apiBaseUrl: process.env.COMMERCE_API_ORIGIN, // undefined uses production
  sourceApp: process.env.COMMERCE_SOURCE_APP,
  owner: process.env.COMMERCE_ORDER_OWNER,
});

apiBaseUrl 控制目录、顺序和 OAuth 请求; 退出使用相应的 checkout.commerce. 子域名。 没有其它环境的内置列表 . sourceApp 财务报告和审定财务报表 owner 是可选主机拥有的归属值: 退出同时使用, 而订单草稿使用 owner。您的商务整合所需的供应值; 包默认省略.

拥有自己配置服务的主机可以执行 CommerceConfiguration 直接说. read() 返回时 clientId, (中文(简体) ), clientSecret, (中文(简体) ), storeId, (中文(简体) ), channelId, (中文(简体) ), currencyCode, (中文(简体) ), apiBaseUrl和可选择的归属. readCheckout() 返回取出标记和可选的运入设置。 从一个一致的绑定状态返回已验证的即时使用设置 。 这两种功能都在服务器上运行;证书决不能到达浏览器代码.

路由器和辅助器

createCommerceCatalogRouter(configuration) 安装目录、公共配置和车道. createGoDaddyPaymentsRouter(configuration, checkoutReturnUrls) 安装检出和只读命令状态路由而不需要目录 UI. createCommerceRouter({ configuration }) 默认同时安装或接受明显的特征标记.

HTTP 检出路由接受已有的 draftOrderId 或直接 skuId; 商业解决目录价格. 它拒绝 lineItemData。对于固定价格存款等非目录费用,计算服务器上的金额并拨打 createCheckoutSession(params, configuration) 直接说 从不向这个信任的助手转发浏览器提供的价格 。 服务器呼叫器也可以使用 getOrderStatus(orderId, configuration) 无需HTTP回转.

产品频道能见度

GET /products 财务报告和审定财务报表 GET /products/:id 使用服务器配置的频道,仅请求 ACTIVE 产品。 搜索,分类过滤器,以及明确的产品ID保留了该通道过滤器. 产品详细要求该频道无法提供的产品返回404。 浏览器查询参数不能选择不同的信道 。 当配置的频道活动并注册到商店时,为所有频道配置的产品仍然可用.

如果配置 GODADDY_CHANNEL_ID catalog API 返回一个空产品列表, 而产品细节请求返回 404 。 这些是来自 Catalog API 的成功空出结果,而不是配置错误 。 当预期目录为空时, 请确认频道是否活动并注册到 GODADDY_STORE_ID,然后检查产品状态和频道任务。 一个不见了 GODADDY_CHANNEL_ID 不同: 默认配置读取器以 503 拒绝它 not_configured。 。 。 .

Catalog API 解析活性存储通道 /v1/commerce/channels 评估频道过滤器时的结束点 。 这些查询目前没有被Catalog API缓存,因此频道过滤的目录请求可以添加上游调用和延迟.

这些检查控制产品浏览. GET /skus/:id,推车创建(POST /cart页:1POST /cart/:id/items转发 SKU ID 不检查其产品是否在配置的信道上可用 。 来自产品细节的404不能确定SKU的查询或推车书写会被拒绝. 需要对这些操作进行频道限制的主机在转发SKUID前必须执行;浏览过滤器不是授权边界.

检查返回目的地

配置 checkoutReturnUrls 在路由器上使用信任的部署设置。 两个列表都包含完整的绝对HTTPS URL;方案,出处,端口,路径,以及所配置的查询参数必须相匹配. 成功 URL 可能添加单个 orderId 查询参数。 额外的查询参数,片段,证书,相对URL,以及未列出的目的地被拒绝. 配置上面显示的单独的取消和成功目的地; 不从请求头或请求机构获取允许列表 .

如果没有此策略, HTTP 在创建会话前返回 503 。 无效的请求目的地返回 400 。 这适用于两个显示退出的路由器预设. 信任的流程中呼叫者 createCheckoutSession() 拥有返回的 URL,必须构建或验证其服务器侧.

从主机退票返回不是付款的证据。 订单状态路由使用支持已完成订单的已授权命令 REST API,并返回其付款状态(例如) PAID 或者说 PENDING; 导出 ORDER_STATUS_UNKNOWN, (中文(简体) ), 'unknown'(如果缺席) 只显示为显出丰富, 并且不出示未经证实的付款。 必须批准服务器 OAuth 客户端 commerce.order:read。帮助者验证返回的订单 ID、存储和通道,并返回没有客户联系数据的有限摘要。 路由返回400 一个缺失,空白,加, .,或 .. 命令 ID( 添加的ID 被拒绝, 不修饰) 或 API 命令 拒绝的其中一种错误 VALIDATION_FAILED404 当命令API报告命令缺失时(404) NOT_FOUND)或命令属于另一个商店或频道. 没有这个代码的404,例如来自错误配置的API基础URL,是一个上游失败. Token 和其他商业故障,包括不同订单ID的响应,返回 502 和不可读配置返回 503(见 错误) (中文(简体) ). 主机必须认证呼叫者,并授权访问所请求的每个命令后,才能曝光这条路线.

连接状态

主机可以执行可选同步 CommerceConfiguration.readConnectionState() 方法。 它的返回类型导出为 CommerceConnectionState (单位:千美元)unbound | connecting | ready) (中文(简体) ). 正在返回 undefined 保持现有行为。 状态未知或无法时抛出 读取。 默认环境配置不执行此方法, 所以缺少 证书从不计为 unbound。 。 。 .

GET /config 返回时 { state: 'unbound' } 或者说 { state: 'connecting' } 不读取存储 证书. ready 包括通常不透明 cartScope 财务报告和审定财务报表 currencyCode 之后 read() 成功 。 没有这种方法,成功的响应形状不变. 所有答复是 未选中; 状态不正确或无法配置返回503。 数据及取出路线, 和进程内检查和命令帮助者,拒绝除 ready 在此之前 上游电话.

主机拥有连接生命周期. 报告 ready 仅在商店连接之后 完成 。 。 配置丢失是一个错误, 绝不是 unbound在商店连接之后, 报告 unbound 只有在它被故意断开之后。 存储前端软件包拥有 此服务器从未创建样本 记录或模拟退出.

商店连接前的站点

在商店连接之前显示店面样本产品的模板需要目录路径和 明确连接状态。 给 COMMERCE_CONNECTION_STATE 是主机拥有的设置,设置为 unbound 当网站 创建并创建到 ready 由主机的连接流。 从任何记录中读取联系; 永远不要得到联系 失踪的 GODADDY_* 变量.

import express from 'express';
import { createCommerceCatalogRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';

const runtime = createRuntimeCommerceConfiguration();
const configuration = {
  ...runtime,
  readConnectionState() {
    const state = process.env.COMMERCE_CONNECTION_STATE;
    if (state === 'unbound' || state === 'connecting' || state === 'ready') return state;
    throw new Error('COMMERCE_CONNECTION_STATE must be unbound, connecting, or ready.');
  },
};

const app = express();
app.use(express.json());
// Before static files and any single-page app or SSR fallback, which would answer /api/commerce with HTML.
app.use('/api/commerce', createCommerceCatalogRouter(configuration));
app.use(express.static('dist'));

createCommerceCatalogRouter 显示没有检出路径, 因此一个站点不需要检出 checkoutReturnUrls。 。 。 . GET /api/commerce/config 应返回 {"state":"unbound"} 作为JSON。 如果它返回应用程序的 HTML 页面,则 路由器没有被挂起,或者在它之前有一个倒回路线运行.

错误

每条路线都报告失败 躯体是 { "error": "<customer-facing message>", "code": "<code>", "requestId": "<id>" } (顺序状态还包括: success: false) (中文(简体) ). 同样的ID传递给伐木工. 机构从不包含上游消息,配置细节,或证书.

状态code含义
400个invalid_request缺少或无效输入 .
404 (韩语)not_found缺少订单或产品,或写给现有推车(/cart/:id/...缺少、已过期或已完成。 继续返回 200 { "cart": null }。用 Stale 或 完成的结账 draftOrderId 尚未区分,返回502.
409个scope_mismatchX-Commerce-Scope 不再匹配已配置的商店绑定 .
502 (中文(简体) )upstream_unauthorized商务拒绝此服务器的 OAuth 客户端或请求范围( HTTP 401/403 或 OAuth 400 带有 invalid_client, (中文(简体) ), invalid_grant, (中文(简体) ), unauthorized_client,或 invalid_scope) (中文(简体) ). 它涉及服务器证书,而不是呼叫者,所以它从来没有被报道为401/403.
502 (中文(简体) )upstream_error商业失败,退回出乎意料的反应,或者无法联系到.
第503条not_configured配置缺失或无法读取, 主机会报告一个连接状态 ready,或者不配置退出返回 URL.
500个internal_error此软件包中出乎意料的错误 .

上游出错,没有特定的映射停留502;无效折扣代码等业务出错尚未区分出. 5xx 细节, 包括上游状态和 GraphQL 错误代码

createCommerceRouter({
  configuration,
  logger: { error: (message, context) => log.error(context, message) },
  // Use the host's request id when its edge sets one; unsafe or missing ids fall back to a UUID.
  getRequestId: (req) => req.get('x-request-id'),
});

createCommerceCatalogRouter 财务报告和审定财务报表 createGoDaddyPaymentsRouter 接受相同的建议 { logger, getRequestId } 作为他们最后的论点。 日志默认为 console.error。处理中帮助将导出的文件丢出 CommerceError 子类 (InvalidRequestError, (中文(简体) ), NotFoundError, (中文(简体) ), CommerceNotConfiguredError, (中文(简体) ), UpstreamError),包括当一个主机配置在被读取时抛出. 检查 error.code (例如 'not_found')而不是(a) instanceof,当一个主机有多个本套件副本时失败.

版本与发布记录

@godaddy/gd-commerce-server 共发布 6 个版本,首次发布于 2026/09/29;过去 12 个月发布了 6 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.4.1latest2026/11/0710 天前
0.4.02026/10/2225 天前
0.3.02026/10/2027 天前
0.2.02026/10/091 个月前
0.1.12026/10/021 个月前
0.1.02026/09/291 个月前

关于 @godaddy/gd-commerce-server 的常见问题

@godaddy/gd-commerce-server 是什么?

GoDaddy Commerce 的意见快递服务器集成

如何安装 @godaddy/gd-commerce-server?

在项目目录运行 npm install @godaddy/gd-commerce-server,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:express(^5.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@godaddy/gd-commerce-server 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@godaddy/gd-commerce-server 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@godaddy/gd-commerce-server 可以商用吗?

@godaddy/gd-commerce-server 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@godaddy/gd-commerce-server 的下载量有多少?

根据 npm 官方下载统计,@godaddy/gd-commerce-server 在 2026/10/17 – 2026/11/15 这 30 天内被下载 10,515 次,日均约 351 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@godaddy/gd-commerce-server 还在维护吗?

最新版本 0.4.1 发布于 2026/11/07(10 天前);至今共发布 6 个版本,其中过去 12 个月发布了 6 个;首次发布于 2026/09/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。