# @haatlabs-core/shopify 中文文档

规范地址：https://npmcn.com/package/%40haatlabs-core/shopify/

版本：0\.18\.5
npm 元数据更新时间：2026-11-13T18:16:45.022Z
中文译文更新时间：2026-11-17T08:12:28.284Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40haatlabs-core/shopify
原文对照：https://npmcn.com/package/%40haatlabs-core/shopify/?lang=original
项目主页：https://haatlabs.shop/docs/packages/shopify/
源码仓库：https://github.com/Haatlabs/haatlabs-platform

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

- 包体积（解压后）：415 kB，139 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- 首次发布：2026-11-06T18:20:11.774Z
- 最新版本发布：2026-11-13T18:16:44.845Z
- 近 30 天下载量：4989（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

为节点应用程序购买:OAuth,会话符,Admin GraphQL客户端,产品,webhooks和计费.

## 安装

```sh
npm install @haatlabs-core/shopify
```

也可以使用：`pnpm add @haatlabs-core/shopify`、`yarn add @haatlabs-core/shopify`、`bun add @haatlabs-core/shopify`

## README

# @haatlabs- core/ 处理

为项目购买: OAuth 和会话令牌、 保存令牌、 管理员图形QL 客户、产品和批量出口、媒体、产品内容和创建、网络呼和收费. 它会扔 `SHOPIFY_MEDIA_ERROR` 除了核心代码之外; 项目扩展 `SHOPIFY_ERRORS` 输入 `defineErrors`. 一个项目将网点主题传递给 `ensureWebhookSubscriptions`页:1 重新连接到 `StoreAccessTokens`,以及 `VARIANT_COST_FIELDS` 作为 `extraVariantFields` 当它 拥有库存范围.

## 安装

```
pnpm add @haatlabs-core/shopify
```

## 入境点

-   `@haatlabs-core/shopify`:下面的一切,为节点.
-   `@haatlabs-core/shopify/contracts` (0.12.1) (中文(简体) ) `SHOPIFY_ERRORS` 财务报告和审定财务报表 `ShopifyErrorCode`没有 的节点:一个项目的合同,它的页面装入,从这里导入.
-   `@haatlabs-core/shopify/embedded`: 对于一个嵌入式应用程序在浏览器中的页面; 它不导入任何 节点.
-   `@haatlabs-core/shopify/testing`:项目测试的助手.

## App URL 在管理员外打开( 0.11)

安装后, Shopify 可以打开 App URL 作为顶级页面, 有 `?shop=` 没有 `host`。 。 。 . 一个嵌入式的应用程序会让自己在商店的管理员内部进行访问,然后进行:

```
import { redirectTopLevelVisitToAdmin } from '@haatlabs-core/shopify/embedded';

if (!redirectTopLevelVisitToAdmin(import.meta.env.VITE_SHOPIFY_API_KEY)) render();
```

它会去 `https://<shop>/admin/apps/<api key>` 仅来自顶级页面 `host`, (中文(简体) ), 谁 `shop` 是一个 `*.myshopify.com` 地址,带有 API 密钥;否则它返回虚假 什么也没做. `topLevelAdminRedirect({ search, isTopLevel, apiKey })` 给出该 URL,或无效, 不碰窗户.

## 时限和时间间隔(0.9)

每个行政图表QL 请求都有限制, `timeoutMs` (30s) (中文(简体) ). 运行的查询 超时被重试, 如网络故障; 突变没有( 它可能已被应用) : 被抛下作一瞬间 `SHOPIFY_API_ERROR`"Shopify没有及时回答" 任务本身的重试决定. `request(query, variables, { signal, timeoutMs })` 拿着 呼叫器的信号;其中止被重播为呼叫器.

当对商店的要求可以启动时,由 `ShopifyThrottle`,告诉成本桶 答完每回一回 然后把水桶的一分之一放回去 每个客户份额 `processShopifyThrottle` 除非给定了; `RedisShopifyThrottle` (@haatlabs-core/rate-limit) (中文(简体) ) 跨越各个进程分享:

```
new ShopifyAdminClient({ shopDomain, accessToken, apiVersion, throttle });
```

在过程中,在商店等候的呼叫者一次一个地走. 轮到她了 它又读了店铺的起步, 如果在它移动起步之前的答案, 睡觉 一边握住转弯 没有要求等待超过60 s, 睡觉和排队 它的盖子. `resetProcessShopifyThrottle` 进入 `@haatlabs-core/shopify/testing`。 。 。 .

`getBulkOperation(client, id, { signal })` 读过一次批量操作, 对于一个处理者 投票 与 `PollAgain` (@haatlabs-core/queue),以及 互联网档案馆的存檔,存档日期2013-12-22 `classifyBulkOperation(op)` 说 `'running'`, (中文(简体) ), `'completed'` 或者说 `'failed'` (单位:千美元)`BULK_TERMINAL_STATUSES`失败 被击倒 被击倒 被击倒. `startProductsBulkOperation(client, { signal })` 开始一个。 超时的开始 无论如何,开始一个, 所以重试读 `currentBulkOperation(client, { signal })` 第一:店铺 仍在创建或运行的最新批量查询( e)`bulkOperations`,管理 API 2026-01及以后) 收养。 自2026-01起 店铺一次最多可打出5个批量的询问 所以不会拒绝开店 最新的可能是另一个应用: 运行不止一个的应用 那种时候不能单靠这个通过. `readLines` 作为瞬间,放弃发送的下载 一分钟都没有.

## 任何节点框架

这里的一切都是无框架的:简单的函数和类结束 `fetch`,所以一个应用与它的 自己的Shopify代码(快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快取快.

-   **OAuth 安装 :** `verifyOAuthHmac`, (中文(简体) ), `buildAuthorizeUrl`, (中文(简体) ), `exchangeCodeForToken` (与 过期离线代币, `exchangeSessionToken` 财务报告和审定财务报表 `refreshAccessToken`。 。 。 .
-   **管理图形QL 客户端 :** `ShopifyAdminClient`,带有API版本,基于成本的节流 和Shophify的错误.
-   **网络呼声 :** `verifyWebhookHmac(rawBody, header, apiSecret)` 检查发送的字节 , 因此,路线必须看到生体。 在巢穴JS上: `NestFactory.create(AppModule, { rawBody: true })` 财务报告和审定财务报表 `req.rawBody` (单位:千美元)`RawBodyRequest<Request>`单靠快车: `express.raw()` 在这条路上.
-   **会话符号 :** `verifySessionToken(token, { apiKey, apiSecret })` 给商店和 用户在 App Bridge 请求后.
-   **计费:** 计划是商店通过Shoppify支付.

`src/express.int.test.ts` 通过快递上的NestJS应用程序运行一个webhook和一个会话符号.

## 常见问题

### @haatlabs-core/shopify 是什么？

为节点应用程序购买:OAuth,会话符,Admin GraphQL客户端,产品,webhooks和计费\.

### 如何安装 @haatlabs-core/shopify？

在项目目录运行 npm install @haatlabs-core/shopify，或使用 pnpm add / yarn add / bun add。

### @haatlabs-core/shopify 支持 TypeScript 吗？

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

### @haatlabs-core/shopify 支持 ESM 还是 CommonJS？

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

### @haatlabs-core/shopify 需要什么版本的 Node\.js？

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

### @haatlabs-core/shopify 可以商用吗？

@haatlabs-core/shopify 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @haatlabs-core/shopify 的下载量有多少？

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

### @haatlabs-core/shopify 还在维护吗？

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

