npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@jackluson/subscription-sdk

v1.3.16

Published

A sdk for subscription server

Readme

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