@jackluson / subscription-sdk
个人历史订单（业务后端调用）
订阅服务提供 GET /api/pay/orders，要求请求头 x-user-auth-api-key
与服务端 USER_AUTH_API_KEY 一致。查询参数为 appKey、userId、
page（默认 1）、pageSize（默认 10，最多 50）。
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 均按筛选后的结果计算。
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 配置。永远不要在客户端代码中公开此凭据。
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;不需要每个产品的凭据或授权权限列表。
查询后续待生效套餐
// 默认仅返回当前有效套餐（保留原有行为）
await sdk.plan.getAvailablePlan(userId, source);
// 包含未来生效的套餐，按 startDate 升序返回
await sdk.plan.getAvailablePlan(userId, source, { includeUpcoming: true });
includeUpcoming 默认为 false。开启后仍排除已过期、已删除及无效状态的套餐，保留免费套餐以展示当前权益。登录与权限判断应使用默认查询，避免提前使用未来权益。需要服务端同时支持此参数。