# toolsource-sdk

**Repository Path**: gongdnq/toolsource-sdk

## Basic Information

- **Project Name**: toolsource-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ToolSource SDK

ToolSource SDK is the integration SDK for Qiling AI sub applications. It provides license-code login, device binding, site branding, support information, product plans, and WeChat Native payment QR content.

## Packages

```text
packages/js      TypeScript / JavaScript SDK for Electron, Web, and Node-like runtimes
packages/python  Python SDK for desktop tools, automation tools, and scripts
```

## Core Flow

Sub applications do not need to hard-code every agent site. A user buys a product on the platform site or an agent site, then receives a license code in the user center. The client submits:

```text
license_key + app_key + device_id
```

The backend identifies the user, order, plan, site, and sub application, then returns license status, branding, support QR, device quota, and available plans for the current site.

Purchases inside a sub application must happen after license login. The SDK uses the site bound to the license session, so prices, site income, and promoter commission are calculated for the correct site.

## Multi Feature Entitlements

The existing SDK methods are backward compatible. Older clients can keep using `session.valid`, `session.license.expires_at`, and `session.product.plans`.

For a sub application that contains multiple sellable modules, such as WeChat Official Account, Baijiahao, and Toutiao, the backend may return an additional top-level `entitlements` array from `license/login` and `license/check`.

```json
{
  "entitlements": [
    {
      "feature_code": "wechat_mp",
      "feature_name": "WeChat Official Account",
      "plan_code": "wechat_mp_monthly",
      "plan_name": "WeChat Monthly",
      "kind": "duration",
      "valid": true,
      "reason": "",
      "expires_at": "2026-08-30T12:00:00+08:00",
      "quota_total": null,
      "quota_used": 0
    }
  ]
}
```

Use `entitlements` when the client needs to enable or disable specific modules. Plans without a configured `feature_code` are treated as the default product entitlement and remain compatible with old integrations.

时长套餐也可能带 `quota`（本期赠送额度）和 `quota_mode`（`reset` = 续费后额度重置，`accumulate` = 续费累加）；`ai_enabled` 为 `false` 表示该套餐不能调用平台 AI 网关。授权会话里的 `license.quota_total / quota_used` 可直接展示剩余额度。

套餐和授权会话都带有 `account_limit_type`（`limited` / `unlimited`）和 `account_limit`，表示子应用可绑定的自媒体账号数量限制；子应用绑定/登录账号时应读取 `license.account_limit_type / account_limit` 进行校验。

授权会话的 `license.is_free` 表示当前授权是否为免费套餐；免费授权升级付费后，`plan_code` 会变为付费套餐、`is_free` 变为 `false`，有效期从升级时刻重新起算。

## Main APIs

```text
bootstrap            Get app branding, current product, and current product plans
getStorefront        Get all products and plans for the licensed site
loginWithLicense     Login with a license code and bind the current device
checkLicense         Check license status with sdk_token
createOrder          Create a new purchase order and return WeChat Native QR content
createRenewOrder     Renew the current license and return WeChat Native QR content
getOrderStatus       Query payment order status
claimFreePlan        Claim a free plan without payment (requires a customer token)
consumeQuota         Report quota usage back to the platform and atomically deduct it
activate / verify / deactivate  Bind, check or remove the current device (customer token)
aiChat / aiTranslate / aiImage  Call the platform AI gateway (chat, Youdao translation, image)
```

## Server APIs

```text
GET  /api/v1/public/apps/{app_key}/bootstrap
GET  /api/v1/sdk/storefront
POST /api/v1/sdk/license/login
POST /api/v1/sdk/license/check
POST /api/v1/sdk/attribution
POST /api/v1/payments/mediacore/create
GET  /api/v1/payments/mediacore/status/{order_no}
POST /api/v1/orders/claim-free
POST /api/v1/sdk/licenses/consume
POST /api/v1/sdk/licenses/activate
POST /api/v1/sdk/licenses/verify
DELETE /api/v1/sdk/licenses/devices/{device_id}
POST /api/v1/sdk/ai/chat
POST /api/v1/sdk/ai/translate
POST /api/v1/sdk/ai/image
```

`bootstrap`, `license/login`, `license/check`, and `storefront` return final sale prices for the current site. Platform settlement price is not exposed to the client.

## App Key

Each sub application has a unique `app_key`, for example:

```text
qi-tui-desktop
```

The `app_key` is configured in Qiling AI platform admin and bundled into the client app.