# @jackluson/subscription-sdk 中文文档

规范地址：https://npmcn.com/package/%40jackluson/subscription-sdk/

版本：1\.3\.16
npm 元数据更新时间：2026-11-01T09:33:49.896Z
中文译文更新时间：2026-11-01T12:59:16.359Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：34.5 kB，36 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-10-06T04:14:32.359Z
- 最新版本发布：2026-11-01T09:33:49.742Z
- 已发布版本数：5（近 12 个月 4 个）

## 中文简介

用于订阅服务器的sdk

## 安装

```sh
npm install @jackluson/subscription-sdk
```

也可以使用：`pnpm add @jackluson/subscription-sdk`、`yarn add @jackluson/subscription-sdk`、`bun add @jackluson/subscription-sdk`

## README

## @jackluson / subscription-sdk

## 个人历史订单（业务后端调用）

订阅服务提供 `GET /api/pay/orders`，要求请求头 `x-user-auth-api-key` 与服务端 `USER_AUTH_API_KEY` 一致。查询参数为 `appKey`、`userId`、 `page`（默认 1）、`pageSize`（默认 10，最多 50）。

```ts
import { SubscriptionSDK } from '@jackluson/subscription-sdk';

const sdk = new SubscriptionSDK({
  appKey: 'your-app',
  baseUrl: process.env.SUBSCRIPTION_API_URL!,
});

// 在业务后端完成登录校验，从会话取得 userId；不要信任浏览器传入的 userId。
const orders = await sdk.pay.listOrders(session.user.id, {
  apiKey: process.env.USER_AUTH_API_KEY!,
  page: 1,
  pageSize: 10,
});
```

返回 `{ list, total, page, pageSize }`。每条记录包含 `orderNo`、`title`、 `planKey`、`amount`、`status`、`createdAt`（iso）、（中国）、（中国）。 状态为 0 未支付、1 已支付、2 已开通；默认查询包含这三种状态，排除软删除订单。 整整整整，整整整整，整整整整，整整整整。

API密钥： “笨笨笨笨，笨笨笨笨，笨笨笨笨，笨笨笨笨。” sdk。【关键字】：

### 按订单状态筛选

接口支持可选参数 `status`：不传查询全部，`0` 未支付、`1` 已支付待开通、 `2` 已开通。`paid` 同时包含状态 1 和 2，适合查询所有支付成功的订单。 分页和 `total` 均按筛选后的结果计算。

```ts
const orders = await sdk.pay.listOrders(session.user.id, {
  apiKey: process.env.USER_AUTH_API_KEY!,
  status: 'paid',
});
```

HTTP：`GET /api/pay/orders?appKey=your-app&userId=123&status=paid`。

## 后端授权授予（1.3.10）

需要匹配的订阅服务器迁移和 `USER_AUTH_API_KEY` 配置。永远不要在客户端代码中公开此凭据。

```ts
const sdk = new SubscriptionSDK({ appKey: 'anchor-arbitrage-toolbox', baseUrl: process.env.SUBSCRIBE_URL! });
const options = { apiKey: process.env.SUBSCRIPTION_ENTITLEMENT_API_KEY! };
const facts = await sdk.grants.facts(userId, options);
const result = await sdk.grants.grant({ userId, targetKey: 'Standard', days: 3, idempotencyKey: `invitation:${rewardId}` }, options);
const existing = await sdk.grants.findGrant(`invitation:${rewardId}`, options);
await sdk.grants.revoke(`invitation:${rewardId}`, `invitation:${rewardId}:revoke`, options);
```

在重试时保持相同的请求键。具有不同参数的重用键或取消的授权返回409。 `findGrant` 只对缺席/挂起的请求返回null；传输错误不是缺席。 `facts` 拒绝不完整的历史付款/退款数据。员工在管理订单页面中维护退款状态；没有自动对账工人或每日审查到期。看到 `docs/ENTITLEMENT_GRANTS.md` 对于手动工作流。

前 `reconcilePayment`， `enqueuePaymentSync`， `paymentSyncStatus`, `recordPaymentFacts` 方法和服务器路由已被删除。后端集成应该如下所示 `facts`;退款更改是通过认证的管理界面进行的。

### 退款状态

订单记录的 `refundState` 独立于支付流程的数字 `status`：`UNKNOWN` 待核对、 `NONE` 无退款（当前登记状态）、`PENDING` 退款中、`REFUNDED` 已退款。 `status: 'refunding'` 和 `status: 'refunded'` 分别筛选退款中、已退款订单。 `paid` 以及数字状态筛选均排除退款中和已退款订单；不传仍返回全部订单。 管理员可以登记退款状态并填写核对依据；该操作不发起资金退款、不自动取消订阅。

授权请求使用统一的 `x-user-auth-api-key` 头。传递订阅服务器的 `USER_AUTH_API_KEY` 作为 `options.apiKey`;不需要每个产品的凭据或授权权限列表。

### 查询后续待生效套餐

```ts
// 默认仅返回当前有效套餐（保留原有行为）
await sdk.plan.getAvailablePlan(userId, source);
// 包含未来生效的套餐，按 startDate 升序返回
await sdk.plan.getAvailablePlan(userId, source, { includeUpcoming: true });
```

`includeUpcoming` 默认为 `false`。开启后仍排除已过期、已删除及无效状态的套餐，保留免费套餐以展示当前权益。登录与权限判断应使用默认查询，避免提前使用未来权益。需要服务端同时支持此参数。

## 常见问题

### @jackluson/subscription-sdk 是什么？

用于订阅服务器的sdk

### 如何安装 @jackluson/subscription-sdk？

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

### @jackluson/subscription-sdk 支持 TypeScript 吗？

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

### @jackluson/subscription-sdk 支持 ESM 还是 CommonJS？

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

### @jackluson/subscription-sdk 可以商用吗？

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

### @jackluson/subscription-sdk 还在维护吗？

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