api2key-base-sdk

api2key-base-sdk 是当前唯一保留的 SDK 入口，统一承载基础平台能力、项目运行时能力和后台管理客户端。

适合放进所有新项目作为默认基础依赖。

当前边界

当前统一暴露：

1. auth
2. credits
3. apiKeys
4. settings
5. projects
6. orders
7. payment
8. ai
9. admin

安装原则：

1. 所有新项目默认只安装 api2key-base-sdk
2. 后台项目也只安装 api2key-base-sdk
3. 单项目私有逻辑优先留在本地 facade，而不是再拆新的 SDK 包

暴露的客户端

当前 api2key-base-sdk 暴露以下客户端：

1. auth
2. credits
3. apiKeys
4. settings
5. projects
6. orders
7. payment
8. ai
9. admin

1. auth

负责稳定的用户认证能力。

当前主要方法：

1. login(input)
2. register(input)
3. me(accessToken?)
4. logout(accessToken?)

2. credits

负责稳定的积分账户与服务侧扣减能力。

当前主要方法包括：

1. getBalance(accessToken?)
2. getLedger(input)（仅管理员账号可查询当前账户积分消耗流水，普通用户前台不应依赖）
3. spend(input)
4. reserve(input)
5. confirm(id)
6. cancel(id)

3. apiKeys

负责用户 API Key 生命周期管理。

4. settings

负责用户级设置的读取与更新。

5. projects / orders / payment / ai

负责项目商品、会员、订单、支付、AI 等运行时能力。

6. admin

负责项目管理、产品管理、用户管理、会员管理、模型管理、后台积分操作等控制面能力。

适合哪些项目

适合：

1. 所有新项目
2. 只需要登录、积分、用户设置、API Key 的项目
3. 需要一个长期稳定基础依赖的项目

适合同一个 SDK 内统一暴露所有共享客户端，但不适合把某个单项目专属兼容逻辑强行塞进共享包。

安装

npm install api2key-base-sdk

使用示例

import { createBasePlatformClient } from 'api2key-base-sdk';

const baseClient = createBasePlatformClient({
  baseUrl: process.env.API2KEY_BASE_URL!,
  getAccessToken: () => process.env.ACCESS_TOKEN,
  getServiceSecret: () => process.env.SERVICE_SECRET,
});

const me = await baseClient.auth.me();
const credits = await baseClient.credits.getBalance();

const projectClient = createProjectPlatformClient({
  baseUrl: process.env.API2KEY_BASE_URL!,
  getAccessToken: () => process.env.ACCESS_TOKEN,
  getProjectId: () => process.env.PROJECT_ID,
});

const adminClient = createAdminPlatformClient({
  baseUrl: process.env.API2KEY_BASE_URL!,
  getAccessToken: () => process.env.ADMIN_ACCESS_TOKEN,
});

const products = await projectClient.projects.getCatalogProducts(process.env.PROJECT_ID!);
const projects = await adminClient.admin.listProjects();

设计原则

1. 新项目默认只依赖这个包
2. 共享客户端统一收敛在一个包里
3. api2key-base-api 可以继续保持清晰的路由分层，而不需要在消费侧安装多个 SDK

Agent 约定

后续 agent 在处理需求时，默认把这个包视为“稳定基础层”。

规则：

1. 如果需求属于共享客户端能力，优先在这里找
2. 后端路由边界仍按 base/project/admin 区分，不要因为 SDK 合并而改乱 API 归属
3. 如果新需求只服务单个项目，优先留在项目本地 facade

兼容说明

当前仍保留 createPlatformAClient 作为过渡别名，它返回基础能力客户端。

建议新代码统一使用：

• createBasePlatformClient
• createProjectPlatformClient
• createAdminPlatformClient