api2key-project-sdk

api2key-project-sdk 用于承载项目运行时相关的业务接口。

它的定位是：

1. 承接 base api 之上的业务扩展能力
2. 给普通业务项目提供商品、会员、订单、支付、AI 等能力
3. 避免把业务逻辑重新塞回 api2key-base-sdk

它不是后台管理 SDK，也不应该承载 /admin/* 控制面能力。

适用能力：

1. 项目商品目录
2. 项目会员查询
3. 订单
4. 支付
5. AI 模型业务接口

什么时候安装

在以下场景安装：

1. 你的项目需要商品目录或会员能力
2. 你的项目需要下单或支付能力
3. 你的项目需要 AI 模型查询或 AI 业务接入

如果项目只需要登录、积分、API Key、用户设置，则不要安装这个包，直接使用 api2key-base-sdk 即可。

包边界

当前 api2key-project-sdk 只包含四个客户端：

1. projects
2. orders
3. payment
4. ai

不包含：

1. auth
2. credits
3. apiKeys
4. settings
5. 任意 admin 客户端

这些能力分别属于：

1. api2key-base-sdk
2. api2key-admin-sdk

安装

npm install api2key-project-sdk

使用示例

import { createProjectPlatformClient } from 'api2key-project-sdk';

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

const catalog = await projectClient.projects.getCatalogProducts(process.env.PROJECT_ID!);

暴露的客户端

1. projects

负责项目级公开业务能力。

当前主要方法：

1. getCatalogProducts(projectId)
2. getMembership(projectId, options?)

适合：

1. 前台会员页
2. 商品展示页
3. 项目级权限查询

2. orders

负责订单创建、订单列表、订单详情。

当前主要方法：

1. create(input)
2. list(accessToken?)
3. get(orderId, accessToken?)

适合：

1. 用户下单流程
2. 用户订单页

3. payment

负责支付网关相关调用。

当前主要方法：

1. createUnified(input)
2. queryUnified(input)

适合：

1. 收银台
2. 支付状态轮询

4. ai

负责项目运行时 AI 业务能力。

当前主要方法：

1. getModels(input)
2. getBalance(accessToken?)

适合：

1. 模型列表展示
2. 用户可用模型判断
3. AI 使用余额展示

推荐组合方式

业务项目通常这样组合：

1. api2key-base-sdk 负责基础能力
2. api2key-project-sdk 负责业务能力

示例：

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

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

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

const me = await baseClient.auth.me();
const catalog = await projectClient.projects.getCatalogProducts(process.env.PROJECT_ID!);

Agent 约定

后续 agent 在处理业务项目需求时，默认遵循以下规则：

1. 认证、积分、API Key、设置相关需求优先看 api2key-base-sdk
2. 商品、会员、订单、支付、AI 相关需求优先看 api2key-project-sdk
3. 不要把 admin 能力加回这个包
4. 如果某个业务前台临时需要少量 admin 能力，优先留在项目本地 helper，不要因此把 api2key-admin-sdk 设为默认依赖

文档维护规则

如果这个包新增客户端或新增方法，至少同步更新：

1. 本 README 的“适用能力”
2. 本 README 的“暴露的客户端”
3. 根目录 AGENTS.md 的边界说明