qing-client

qing-client 是一个统一的 JavaScript / TypeScript SDK，用于访问 Qing 平台提供的各类服务能力，包括：

• 用户与认证
• 消息中心
• AI / AIGC 能力
• 静态 HTML 托管（gateway-h5）

该 SDK 为 公开 npm 包，任何 拥有合法账号的第三方开发者 均可使用。

特性

• 前后端统一 SDK
• 支持 浏览器 / H5 / 移动端 / Node.js
• 自动处理认证与请求头
• 支持多服务调用
• 完整 TypeScript 类型定义
• 支持静态前端托管管理（上传 zip）

安装

npm install qing-client

或

yarn add qing-client

使用模式说明

SDK 根据初始化方式不同，分为 前端模式 和 后端模式。

前端模式（推荐）

适用于：

• 浏览器
• H5 页面
• App WebView
• 移动端前端应用

所有请求会通过 API 网关转发。

后端模式

适用于：

• Node.js 服务
• 后端应用
• 内部服务调用

请求会直连具体服务地址。

前端模式示例（客户端 / 移动端）

初始化 Client

import { Client } from "qing-client";

const client = new Client({
  gatewayUrl: "https://api.example.com",
  projectId: "your-project-id",
  appId: "your-app-id",
});

设置访问令牌

await client.setToken("YOUR_ACCESS_TOKEN");

SDK 会自动为所有请求附加：

• Authorization: Bearer <token>
• x-project-id
• x-app-id

后端模式示例（Node.js）

import { Client } from "qing-client";

const client = new Client({
  authServiceUrl: "http://auth-service",
  userServiceUrl: "http://user-service",
  gatewayH5ServiceUrl: "http://gateway-h5-service",
});

设置用户上下文（仅后端模式）

client.setUserContext({
  userId: "123",
  role: "ADMIN",
  projectId: "project-1",
});

用户与认证

登录

const result = await client.auth.login("username", "password");
await client.setToken(result.access_token);

消息与用户服务

// 获取当前用户
const user = await client.user.getCurrentUser();

// 获取消息列表
const messages = await client.msg.getMessages();

AI / AIGC 示例

const response = await client.ai.chatCompletion({
  sessionId: "session-id",
  message: "你好",
});

HTML 静态托管（gateway-h5）

SDK 提供了静态 HTML 托管管理能力，用于上传和管理前端站点。

⚠️ 重要说明

平台 不会 帮你构建前端项目 你需要 自行 build 前端项目，并将构建产物打包为 .zip 上传

标准流程

1. 使用你自己的前端工具构建项目（如 Vite / Vue / React / Nuxt 静态模式）

2. 将构建产物打包为 zip

   • index.html 必须位于 zip 根目录

3. 通过 API 上传 zip 进行部署

创建托管项目

import { FrontHostService } from "qing-client";

const fronthost = new FrontHostService({
  gatewayUrl: "https://api.example.com",
  projectId: "your-project-id",
  appId: "your-app-id",
});

await fronthost.setToken("YOUR_ACCESS_TOKEN");

await fronthost.createProject({
  deployType: "route",
  routePath: "/my-app",
  file: zipFile, // File 或 Blob（.zip）
});

部署新版本

await fronthost.deployNewVersion(projectId, zipFile);

支持的部署类型

| 类型 | 说明 | | ----------- | ------------- | | route | 路径托管，如 /app | | subdomain | 子域名托管 | | proxy | 自定义域名托管 |

Token 存储说明

默认情况下，Token 存储在内存中，刷新页面后会丢失。

如需持久化登录状态，可自定义 Token 存储：

const client = new Client({
  gatewayUrl: "...",
  tokenStorage: {
    async getToken() {
      return localStorage.getItem("token") || undefined;
    },
    async setToken(token) {
      localStorage.setItem("token", token);
    },
    async clearToken() {
      localStorage.removeItem("token");
    },
  },
});

TypeScript 支持

SDK 完全使用 TypeScript 编写，并自带类型声明文件。

安全与隐私

• 不暴露任何内部服务实现
• 不包含任何敏感信息
• 所有认证信息由使用方自行提供
• 适合公开发布到 npm

License

MIT