# @epcc-sdk/sdks-shopper 中文文档

规范地址：https://npmcn.com/package/%40epcc-sdk/sdks-shopper/

版本：0\.15\.0
npm 元数据更新时间：2026-11-09T17:52:58.106Z
中文译文更新时间：2026-11-13T19:27:34.536Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40epcc-sdk/sdks-shopper
原文对照：https://npmcn.com/package/%40epcc-sdk/sdks-shopper/?lang=original

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

- 包体积（解压后）：14 MB，209 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：zod ^4\.0\.0，@tanstack/react-query ^5\.69\.0
- 首次发布：2025-01-13T12:11:39.168Z
- 最新版本发布：2026-11-09T17:52:57.905Z
- 近 30 天下载量：3731（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 21 个）

## 中文简介

一个用于Elastic Path可编译商务商店前端的TypeScript客户端. 它包含一个商店头通常调用的API,在一个软件包中,并在浏览器中管理shopper令牌. 函数、类型和 Zod 计划由 OpenA 生成

## 安装

```sh
npm install @epcc-sdk/sdks-shopper
```

也可以使用：`pnpm add @epcc-sdk/sdks-shopper`、`yarn add @epcc-sdk/sdks-shopper`、`bun add @epcc-sdk/sdks-shopper`

## README

# @ epcc- sdk/ sdks- shopper

一个用于Elastic Path可编译商务商店前端的TypeScript客户端. 它包含一个商店头通常调用的API,在一个软件包中,并在浏览器中管理shopper令牌. 函数,类型和Zod schemas由API的OpenAPI specs生成.

## 安装

```bash
npm install @epcc-sdk/sdks-shopper
```

## 快开始

```ts
import {
  configureClient,
  getByContextAllProducts,
} from "@epcc-sdk/sdks-shopper"

configureClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: "your-client-id" },
)

const { data, error } = await getByContextAllProducts()
```

`configureClient` 设置 `client` 包输出。 所有操作都使用该客户端 当你不给他们一个.

客户端得到与客户端ID的隐含符号,所以没有秘密进入浏览器. 它在每个请求中都添加了符号,并在符号到期前获得一个新的符号. 在401回信后,它得到一个新的信使并再次发出请求. 408或429回复后,或5xx回复安全再次发送的请求后,会等待并再次发送请求.

失败的请求不会丢出 。 操作返回错误 `error`。 。 。 .

## 基础 URL

设定 `baseUrl` 到您所在区域的 API 主机, 没有路径 。 每个操作都增加了自己的路径.

## 认证选项

第二项论点是: `configureClient` 采用这些选项:

| 选项 | 它会做什么 |
| --- | --- |
| `clientId` | 你店里的客户身份 这是必要的. |
| `storage` | 当客户端保存了该符号时: `"localStorage"` (默认), `"cookie"`,或者你自己的 `StorageAdapter`。 。 。 . |
| `cookie` | 例如饼干选项 `sameSite`, (中文(简体) ), `secure` 财务报告和审定财务报表 `maxAge`,当 `storage` 实值 `"cookie"`。 。 。 . |
| `tokenProvider` | 你自己的职能是获得一个象征, 代替隐性赠款. |
| `retry` | 备选方案 `createRetryFetch`设置它 `false` 以停止复试。 客户端仍然得到新的代币. |
| `wrapUserFetch` | 如果你给一个 `fetch` 在第一个参数中,客户端添加认证和重试. 默认是 `true`。 。 。 . |

与 `"localStorage"`,所有浏览器标签都使用相同的符号。 与 `"cookie"`,饼干可由JavaScript读取.

## 单独的客户端

`createShopperClient` 使用相同的参数并返回一个新的客户端。 用于多个商店, 或者当您不想更改导出时 `client`。将此客户端交给每个操作.

```ts
import {
  createShopperClient,
  getByContextAllProducts,
} from "@epcc-sdk/sdks-shopper"

const { client, auth } = createShopperClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: "your-client-id" },
)

const { data } = await getByContextAllProducts({ client })
```

两个函数返回 `{ client, auth }`启用 `auth` 控制符号 :

```ts
const token = await auth.getValidAccessToken()
const current = auth.getSnapshot()
await auth.refresh()
auth.clear()
```

`getValidAccessToken` 返回符号,并在必要时获得一个新的符号. `getSnapshot` 返回存储的符号,不发送请求. `refresh` 换个新标志. `clear` 删除已存储的令牌.

## 访客身份证和分析

`createShopperClient` 以两个选项进行第三个参数。 没有他们,客户不会发出访客或分析头条.

| 选项 | 它会做什么 |
| --- | --- |
| `visitor` | A 类 `Visitor`,或每个请求返回一个函数。 客户端发送 `EP-Visitor-Id` 财务报告和审定财务报表 `EP-Visitor-Consent`。 。 。 . |
| `analyticsOff` | 何时 `true`,客户端发送 `EP-Analytics: off` 每一个请求,无论访客。 用于员工,测试和机器人交通. |

`resolveVisitor` 阅读请求,调用您的同意功能,并返回访客和 `Set-Cookie` 用于响应的数值。 这个软件包 输出它, 其他一切从 `@epcc-sdk/visitor`,所以您只安装此软件包。 这个 `@epcc-sdk/visitor` README描述了饼干,信头,访客状态和同意功能.

```ts
import {
  createShopperClient,
  getByContextAllProducts,
  resolveVisitor,
} from "@epcc-sdk/sdks-shopper"

const { visitor, setCookies } = await resolveVisitor(request, { consent })

const { client } = createShopperClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: "your-client-id" },
  { visitor },
)

const { data } = await getByContextAllProducts({ client })
```

当一个客户端在服务器上为许多顾客服务时, 给 `visitor` 函数返回当前请求的访问者.

对于一个客户 你与 `createClient`,添加 `createVisitorInterceptor(visitor)` 财务报告和审定财务报表 `createAnalyticsOffInterceptor()` 作为请求截取器. `configureClient` 没有选择.

### 没有服务器的单页应用程序

单页的应用程序会从浏览器中发送信头. `createBrowserVisitor` 返回您给出的函数 `visitor` 选项。 它也来自这个软件包,所以你只安装这个软件包.

```ts
import {
  createBrowserVisitor,
  createShopperClient,
  hasBrowserGlobalPrivacyControl,
} from "@epcc-sdk/sdks-shopper"

const visitor = createBrowserVisitor({
  consent: () => {
    if (hasBrowserGlobalPrivacyControl()) return { state: "objected" }
    return myCmp.hasAcceptedAll()
      ? { state: "granted", purposes: ["analytics", "personalization"] }
      : { state: "none" }
  },
})

const { client } = createShopperClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: "your-client-id" },
  { visitor },
)
```

您的同意功能在浏览器中读取您的同意管理平台,并运行在每一个请求上. 未经同意,ID只活在记忆中. 它保持不变,直到页面再次加载。 是随即寄来的 `EP-Visitor-Consent: none`,函数则不设置饼干。 经同意后,该功能写道: `ep_vid` 配有JavaScript的饼干. 反对已澄清 `ep_vid` 并且不发送访客信封。 Safari将JavaScript所写的饼干限制在了7天之内,所以在Safari中一个持久的id最多持续了7天. 这个 `@epcc-sdk/visitor` README,"只浏览器商店"一栏,有细节.

允许弹性路径 `EP-Visitor-Id`, (中文(简体) ), `EP-Visitor-Consent` 财务报告和审定财务报表 `EP-Analytics` 在它的 CORS 飞行前响应中,所以浏览器可以发送它们.

## 饰品

`initializeCart` 返回shopper的手推车的标识。 如果浏览器没有车名 `localStorage`它制造了一辆推车 并存储了它的身份证. `getCartId` 读取存储的ID。 两者都使用导出 `client`,所以打电话 `configureClient` 先说.

```ts
import { getCartItems, initializeCart } from "@epcc-sdk/sdks-shopper"

const cartId = await initializeCart()
const { data } = await getCartItems({ path: { cartID: cartId } })
```

## 响应查询

这个 `./react-query` 导出为 TanStack 查询 5 提供查询选项、查询密钥和突变。 安装 `@tanstack/react-query` 只有您使用此导出.

```ts
import { useQuery } from "@tanstack/react-query"
import { getByContextProductOptions } from "@epcc-sdk/sdks-shopper/react-query"

const { data } = useQuery(
  getByContextProductOptions({ path: { product_id: productId } }),
)
```

选项使用导出 `client` 当你不给他们一个,你叫 `configureClient` 先说.

## Zod 计划

这个 `./zod` 导出对每次请求和响应都有Zod计划. `zod` 4是可选的对等依赖,因此主要出口不导入.

```ts
import { zGetByContextAllProductsResponse } from "@epcc-sdk/sdks-shopper/zod"

const result = zGetByContextAllProductsResponse.safeParse(data)
```

Spec 给出的字段 `int64` 是一个 `number` 在各种种类和计谋中.

## 让客户自己来

软件包输出部件 `createShopperClient` 使用 : `createTokenSource`, (中文(简体) ), `implicitProvider`, (中文(简体) ), `createAuthCallback`, (中文(简体) ), `createAuthenticatedFetch`, (中文(简体) ), `createRetryFetch`, (中文(简体) ), `localStorageAdapter`, (中文(简体) ), `memoryStorage`, (中文(简体) ), `createClient` 财务报告和审定财务报表 `createConfig`。当您需要您自己的符号源或您自己的符号源时使用它们 `fetch`。 。 。 .

1.  制作 `createAuthCallback` 财务报告和审定财务报表 `createAuthenticatedFetch` 同一来源. `createAuthenticatedFetch` 仅替换来自其来源的符号.
2.  打开 `createAuthenticatedFetch` 内部 `createRetryFetch`。在另一个顺序中,每次重试都会再次发送过期的符号.

不要用请求截取器添加符号 。 截取器无法看到响应,因此在401响应后无法得到新的信号.

## 常见问题

### @epcc-sdk/sdks-shopper 是什么？

一个用于Elastic Path可编译商务商店前端的TypeScript客户端\. 它包含一个商店头通常调用的API,在一个软件包中,并在浏览器中管理shopper令牌\. 函数、类型和 Zod 计划由 OpenA 生成

### 如何安装 @epcc-sdk/sdks-shopper？

在项目目录运行 npm install @epcc-sdk/sdks-shopper，或使用 pnpm add / yarn add / bun add。

### @epcc-sdk/sdks-shopper 支持 TypeScript 吗？

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

### @epcc-sdk/sdks-shopper 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @epcc-sdk/sdks-shopper 可以商用吗？

@epcc-sdk/sdks-shopper 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @epcc-sdk/sdks-shopper 的下载量有多少？

根据 npm 官方下载统计，@epcc-sdk/sdks-shopper 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,731 次，日均约 124 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @epcc-sdk/sdks-shopper 还在维护吗？

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