@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 已开通；默认查询包含这三种状态，排除软删除订单。
只返回 Pay 表记录，手动开通而未生成支付订单的订阅不在此列表中。
API Key 是服务间凭证，不是个人登录凭证；它不能证明传入 userId 的归属。 前端应请求业务后端的“我的订单”接口，由业务后端绑定当前登录用户和固定 appKey， 再调用本 SDK。不要将 API Key 放进前端代码或浏览器请求。
按订单状态筛选
接口支持可选参数 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。
Backend entitlement grants (1.3.10)
Requires the matching subscription-server migration and USER_AUTH_API_KEY configuration. Never expose this credential in client-side code.
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);
Keep the same request key on retries. A reused key with different parameters or a canceled grant returns 409. findGrant returns null only for an absent/pending request; transport errors are not absence. facts rejects incomplete historical payment/refund data. Staff maintain refund states in the admin order page; there is no automatic reconciliation worker or daily review expiry. See docs/ENTITLEMENT_GRANTS.md for the manual workflow.
The former reconcilePayment, enqueuePaymentSync, paymentSyncStatus, and recordPaymentFacts methods and server routes have been removed. Backend integrations should read facts; refund changes are made through the authenticated admin interface.
退款状态
订单记录的 refundState 独立于支付流程的数字 status：UNKNOWN 待核对、
NONE 无退款（当前登记状态）、PENDING 退款中、REFUNDED 已退款。
status: 'refunding' 和 status: 'refunded' 分别筛选退款中、已退款订单。
paid 以及数字状态筛选均排除退款中和已退款订单；不传仍返回全部订单。
管理员可以登记退款状态并填写核对依据；该操作不发起资金退款、不自动取消订阅。
Entitlement requests use the unified x-user-auth-api-key header. Pass the subscription server's USER_AUTH_API_KEY as options.apiKey; no per-product credential or grants permission list is required.
查询后续待生效套餐
// 默认仅返回当前有效套餐（保留原有行为）
await sdk.plan.getAvailablePlan(userId, source);
// 包含未来生效的套餐，按 startDate 升序返回
await sdk.plan.getAvailablePlan(userId, source, { includeUpcoming: true });
includeUpcoming 默认为 false。开启后仍排除已过期、已删除及无效状态的套餐，保留免费套餐以展示当前权益。登录与权限判断应使用默认查询，避免提前使用未来权益。需要服务端同时支持此参数。