TypeScript 客户端 SDK

适用于 Node.js 环境。

依赖关系

| 文档 | 说明 | |------|------| | client/README.md | SDK 总览与三端方法对照 | | docs/dev/client-storage.md | 存储、device_id、状态文件与加解密约定 | | docs/dev/payment.md | 付费授权与公开支付页 |

安装

npm i py-auth-client

AuthClientConfig 字段

| 字段 | 是否必需 | 说明 | |------|----------|------| | serverUrl | 必填 | 服务地址 | | softwareName | 必填 | 产品名称 | | softwareVersion | 可选 | 软件版本 | | deviceId | 可选 | 省略时自动生成或复用 | | deviceInfo | 可选 | 省略时自动采集 | | clientSecret | 条件必填 | 可信接入标识，硬编码在发行包；服务端信任该值确定套餐 plan。开发时可用 CLIENT_SECRET | | cacheValidityDays | 可选 | 本地缓存有效期，默认 7 | | checkIntervalDays | 可选 | 检查间隔，默认 2 | | debug | 可选 | 是否输出调试日志 | | heartbeatTimeoutMs | 可选 | 心跳超时（毫秒）；默认 3000 | | planInfoTimeoutMs | 可选 | 套餐查询超时；默认 10000 | | paymentContextTimeoutMs | 可选 | 付费上下文查询超时；默认 10000 |

示例

启动时要求授权通过

import { AuthClient, AuthorizationError } from "py-auth-client";

async function main() {
  const client = new AuthClient({
    serverUrl: "http://localhost:8000",
    softwareName: "我的软件",
    clientSecret: process.env.CLIENT_SECRET ?? "",
  });

  try {
    await client.requireAuthorization();
  } catch (e) {
    if (e instanceof AuthorizationError) {
      console.error(e.message);
      process.exit(1);
    }
    throw e;
  }
}

void main();

检查授权并按结果处理

const result = await client.checkAuthorization();

if (result.success && result.authorized) {
  console.log(result.from_cache ? "已授权，来自缓存" : "已授权，在线刷新");
} else {
  console.warn("未授权或校验失败：", result.message);
}

仅读取本地授权信息

const info = await client.getAuthorizationInfo();
console.log(info.authorized, info.message, info.device_id, info.cache_remaining_time);

要求授权（不抛异常）

const ok = await client.requireAuthorization({ raiseException: false });

后台刷新授权

const { soft, promise } = client.startBackgroundRefresh({
  onDone: (r) => console.log(r.message),
});
const result = await promise;

读取缓存详情

const cache = client.getCacheInfo();

查询套餐信息

const plan = await client.getPlanInfo();
if (plan.success) {
  console.log(plan.plan, plan.price);
  if (plan.plan_detail) console.log(plan.plan_detail);
}

const ctx = await client.getPaymentContext();
if (ctx.success) {
  console.log(ctx.plan, ctx.can_pay);
}

getPlanInfo() 返回产品套餐配置（档位、价格、详情等），不表示本机是否已付款。心跳返回的 authorized 表示能否上线；plan 表示当前生效档位。

清除本地缓存

client.clearCache();

开发构建说明见 docs/dev/client-ts-build.md。