KingMin 客户端授权 SDK

TypeScript 多端授权 SDK，对接 KingMin 授权中心 V2.1 客户端 API。

文档

• Client API 参考（对接必读）
• OpenAPI / Apifox 导入
• PHP SDK（服务端接入）

安装

npm install @kingmin/license-sdk

本地开发（本仓库）：

cd client
npm install
npm run build

包入口

| 入口 | 用途 | |------|------| | @kingmin/license-sdk | 统一导出 | | @kingmin/license-sdk/desktop | 桌面端（激活码 + 设备） | | @kingmin/license-sdk/web | Web 域名授权 | | @kingmin/license-sdk/miniapp | 微信小程序等 | | @kingmin/license-sdk/openapi | API Key 服务端校验 | | @kingmin/license-sdk/instance | 应用实例配置 + 心跳 |

旧路径 src/license 仍兼容导出 LicenseClient / createLicenseClient。

API 路由

所有请求前缀：{apiUrl}/client.{controller}/{action}

| 端 | Controller | Action | 方法 | |----|------------|--------|------| | 桌面激活 | auth | activate / check / heartbeat / trial | POST | | 配置 | config | index | POST | | 版本 | version | check | POST | | Web | web_auth | check | POST | | 小程序 | miniapp_auth | check | POST | | OpenAPI | openapi | check | POST | | 实例 | instance | config / heartbeat | POST |

签名规则与后端 SignService 一致：md5(appKey + timestamp + nonce + sortedBodyJson + appSecret)。

桌面端快速开始

import { createDesktopLicenseClient } from '@kingmin/license-sdk/desktop'
import { createNodeStorageAdapter } from '@kingmin/license-sdk'

const client = createDesktopLicenseClient({
  apiUrl: 'https://license.example.com/api',
  wssUrl: 'wss://license.example.com:8282',
  appKey: 'your_app_key',
  appSecret: 'your_app_secret',
  clientVersion: '1.0.0',
  platform: 'windows',
  storagePath: '/path/to/app-data' // Electron 主进程推荐
}, {
  storage: createNodeStorageAdapter('/path/to/app-data')
})

await client.activate('YOUR-LICENSE-KEY')
// 或重启后：await client.startup()

Web 端

import { createWebLicenseClient } from '@kingmin/license-sdk/web'

const client = createWebLicenseClient({
  apiUrl: 'https://license.example.com/api',
  appKey: 'your_app_key',
  appSecret: 'your_app_secret', // 仅服务端或构建时注入，勿暴露在前端 bundle
  licenseKey: 'YOUR-LICENSE-KEY',
  domain: 'app.example.com',
  tenantId: 'tenant_001'
})

const result = await client.check()

小程序

支持注入 requestAdapter 替换为 uni.request：

import { createMiniappLicenseClient } from '@kingmin/license-sdk/miniapp'

const client = createMiniappLicenseClient(config, {
  requestAdapter: (url, init) => new Promise((resolve, reject) => {
    uni.request({
      url,
      method: init.method as 'POST',
      data: JSON.parse(init.body as string),
      header: init.headers as Record<string, string>,
      success: (res) => resolve(new Response(JSON.stringify(res.data))),
      fail: reject
    })
  })
})

OpenAPI（Node 中间件）

切勿在浏览器 bundle 中包含 appSecret。

import { createOpenapiClient } from '@kingmin/license-sdk/openapi'

const client = createOpenapiClient({ apiUrl, appKey, appSecret, apiKey: 'km_xxx' })
await client.assertAuthorized('/your/endpoint')

应用实例

import { createInstanceClient } from '@kingmin/license-sdk/instance'

const client = createInstanceClient({
  apiUrl, appKey, appSecret,
  instanceCode: 'inst_001' // 或 tenantId
})

const config = await client.getConfig()
client.startHeartbeat(300)

环境变量（示例 / 联调）

| 变量 | 说明 | |------|------| | KM_API_URL | API 根地址 | | KM_APP_KEY / KM_APP_SECRET | 项目密钥 | | KM_LICENSE_KEY | 激活码 | | KM_DOMAIN | Web 域名 | | KM_MINI_APP_ID | 小程序 AppID | | KM_API_KEY | OpenAPI Key | | KM_INSTANCE_CODE / KM_TENANT_ID | 实例标识 |

联调

node scripts/integration-test.mjs http://your-api/api
# 多端步骤（需对应测试数据）：
KM_TEST_WEB=1 KM_DOMAIN=localhost node scripts/integration-test.mjs
KM_TEST_MINIAPP=1 KM_MINI_APP_ID=wx... node scripts/integration-test.mjs
KM_TEST_OPENAPI=1 KM_API_KEY=km_... node scripts/integration-test.mjs
KM_TEST_INSTANCE=1 KM_INSTANCE_CODE=inst_001 node scripts/integration-test.mjs

示例

npm run example:desktop -- DEMO-0001
npm run example:web
npm run example:miniapp
npm run example:openapi
npm run example:instance

Apifox 导入

1. 打开 Apifox → 导入 → OpenAPI
2. 选择本目录 docs/openapi.yaml
3. 修改 servers.url 为实际 API 地址（如 https://license.example.com/api）
4. 签名算法见 API.md §2（Apifox 前置脚本可复用 scripts/integration-test.mjs 逻辑）