# @jsondrop/commerce 中文文档

规范地址：https://npmcn.com/package/%40jsondrop/commerce/

版本：0\.1\.0
npm 元数据更新时间：2026-11-01T13:49:03.792Z
中文译文更新时间：2026-11-01T14:38:15.163Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40jsondrop/commerce
原文对照：https://npmcn.com/package/%40jsondrop/commerce/?lang=original
项目主页：https://github.com/valicm/jsondrop/tree/main/packages/commerce#readme
源码仓库：https://github.com/valicm/jsondrop

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：98.6 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：0 个
- peer 依赖：@jsondrop/core ^0\.1\.0，@jsondrop/drupal ^0\.1\.0
- 首次发布：2026-11-01T13:48:07.208Z
- 最新版本发布：2026-11-01T13:49:03.577Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Drupal Commerce类型和一个用于@jsondrop/core的commerce\_api客户端（购物车、结帐、支付）。

## 安装

```sh
npm install @jsondrop/commerce
```

也可以使用：`pnpm add @jsondrop/commerce`、`yarn add @jsondrop/commerce`、`bun add @jsondrop/commerce`

## README

# @jsondrop /商务

Drupal Commerce类型和客户端 [commerce\_api](https://www.drupal.org/project/commerce_api) 模块:购物车, 优惠券，结帐，航运和付款。

```sh
npm install @jsondrop/core @jsondrop/drupal @jsondrop/commerce
```

需要 `commerce_api` （8.x-1.x）在Drupal端。

## 目录

commerce\_api重命名Commerce的资源类型： `commerce_` 前缀 go和下划线变成了连字符，路径被复数化。

| Drupal | 资源类型 | 路径 |
| --- | --- | --- |
| `commerce_product` (默认) | `product--default` | `/jsonapi/products/default` |
| `commerce_product_variation` (默认) | `product-variation--default` | `/jsonapi/product-variations/default` |
| `commerce_order` (默认) | `order--default` | `/jsonapi/orders/default` |
| `commerce_order_item` (默认) | `order-item--default` | `/jsonapi/order-items/default` |
| `commerce_store` (在线) | `store--online` | `/jsonapi/stores/online` |
| `commerce_promotion_coupon` | `promotion-coupon` | `/jsonapi/promotion-coupons` |

**JSON:API Extras覆盖重命名。** 在带有Extras的网站上，类型 保留Drupal的名称(`commerce_product_variation--default`)，除非 资源配置则相反，站点将两者混合在一起。这两种类型都接受 命名;对于路径，使用 `client.withDiscoveredPaths()`;对于类型名称 `CommerceApi` 发送, `naming: 'drupal'` (并下达命令，而不是 id，所以它们自己的类型被发送)。

`withCommerceApi(client)` 给出解析这些路径的客户端，以及 类型是按实体类型注册的，所以每个产品包都是 `Product`，每一种变化 `ProductVariation`等等。

```ts
import { JsonApiClient } from '@jsondrop/core';
import { withCommerceApi } from '@jsondrop/commerce';

const drupal = withCommerceApi(new JsonApiClient({ baseUrl: 'https://shop.example.com' }));
const products = await drupal.getCollection('product--default', { query: { include: ['variations'] } });
products[0].variations; // ProductVariation[], with resolved_price
```

## 购物车和结帐

```ts
import { CommerceApi, checkoutStatus, createCartToken } from '@jsondrop/commerce';

const commerce = new CommerceApi(drupal).withCartToken(token ?? createCartToken());

await commerce.addToCart({ type: 'product-variation--default', id: variationId, quantity: 2 });
const [cart] = await commerce.getCarts();
await commerce.applyCoupons(cart.id, 'SAVE10');

await commerce.updateCheckout(cart.id, {
  email: 'ana@example.com',
  billing_information: { address: { country_code: 'HR', locality: 'Zagreb', postal_code: '10000', address_line1: 'Ilica 1' } },
});
const { constraints, shippingRates, paymentOptions, ready } = checkoutStatus(await commerce.getCheckout(cart.id));
```

| 方法 | 端点 |
| --- | --- |
| `getCurrentStore()` | `GET /current-store` |
| `getCarts()`， `getCart(id)` | `GET /carts`， `GET /carts/{order}` |
| `addToCart(items)` | `POST /cart/add` |
| `updateCartItem(order, item, { quantity })` | `PATCH /carts/{order}/items/{item}` |
| `removeCartItems(order, items)` | `DELETE /carts/{order}/items` |
| `clearCart(order)` | `DELETE /carts/{order}` |
| `applyCoupons(order, codes)`， `removeCoupons(order)` | `PATCH` / `DELETE /carts/{order}/coupons` |
| `getCheckout(order)`， `updateCheckout(order, changes)` | `GET` / `PATCH /checkout/{order}` |
| `getShippingMethods(order)` | `GET /checkout/{order}/shipping-methods` |
| `createPayment(order, { gatewayId })` | `POST /checkout/{order}/payment` |
| `approvePayment(order, params)` | `GET /checkout/{order}/payment/approve` (离线返回) |

**订单** 可以作为ID或订单本身传递(`getCarts()` 将它们返回);对于订单，发送其类型的请求使用真实类型 （`order--regular`，而不是配置的默认值)。

**你自己的模型。** 方法是泛型的，并使用包的类型进行类型化 默认情况下。如果您将响应映射到您自己的模型，请使用未类型化的响应： `commerce.getCarts<Resource>()`.

**车令牌。** Commerce\_api从不发出一个：客户端创建一个 （`createCartToken()`)并将其发送为 `Commerce-Cart-Token`;车创建 下面的权利属于所有持有它的人。将它保存在httpOnly cookie中并调用 从服务器获取Drupal。看到 [例子6](https://npmcn.com/package/examples/06-server-cart-token.ts).

**支付。** `createPayment` 用付款支付订单的余额 仪表（现场和手动网关）和下订单。它返回 整个响应，所以一个网关模块用一个额外的步骤来响应 可以由调用方处理。场外网关重定向客户，并且 `approvePayment` 在他们返回时完成付款。

## 产品包

为 [commerce\_variation\_bundle](https://www.drupal.org/project/commerce_variation_bundle)： 带有“变体包”特征的变体类型保存着包项 （`bundle-item--{type}`)，每一个都是另一种变化的数量。

```ts
import { bundleItems, type VariationBundle } from '@jsondrop/commerce';

declare module '@jsondrop/core' {
  interface ResourceTypes {
    'product-variation--bundle': VariationBundle<'bundle'>;
  }
}

const set = await drupal.getResource('product-variation--bundle', id, {
  query: { include: ['bundle_items.variation'] },
});
set.bundle_discount; // percentage off the items
for (const { variation, quantity, unitPrice } of bundleItems(set)) {
  // enabled items, with their variation and its resolved unit price
}
```

`isVariationBundle(variation)` 从普通的变化中区分包。添加一个 像任何变化一样捆在车上；模块从它的物品中定价。

## 其他商务模块

Commerce\_api重命名每一个 `commerce_*` 实体类型，也有贡献类型。 `COMMERCE_ENTITY_TYPES` 列出了解决问题的途径(商业， commerce\_shipping commerce\_variation\_bundle);在commerce\_api中添加其他的 命名:

```ts
const drupal = withCommerceApi(client, ['license', 'wishlist-item']);
// or
const commerce = new CommerceApi(client, { entityTypes: ['license'] });
```

## 扩展

-   你的包和字段： [示例4](https://npmcn.com/package/examples/04-commerce-types.ts).
-   你的模块的端点，头和支付流：子类 `CommerceApi`， [示例5](https://npmcn.com/package/examples/05-commerce-subclass.ts).
-   其他名称: `orderType`， `couponType`， `paymentType` 和 `cartInclude` 选项。

## 常见问题

### @jsondrop/commerce 是什么？

Drupal Commerce类型和一个用于@jsondrop/core的commerce\_api客户端（购物车、结帐、支付）。

### 如何安装 @jsondrop/commerce？

在项目目录运行 npm install @jsondrop/commerce，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@jsondrop/core（^0\.1\.0）、@jsondrop/drupal（^0\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @jsondrop/commerce 支持 TypeScript 吗？

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

### @jsondrop/commerce 支持 ESM 还是 CommonJS？

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

### @jsondrop/commerce 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @jsondrop/commerce 可以商用吗？

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

### @jsondrop/commerce 还在维护吗？

最新版本 0\.1\.0 发布于 2026/11/01（1 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。