api2key-base-sdk 0.1.0

package/README.md

@@ -0,0 +1,181 @@
+# api2key-base-sdk
+
+`api2key-base-sdk` 是一个面向子项目的 TypeScript SDK，用于调用 Api2Key API 对外提供的稳定 API。
+
+它的目标不是让业务项目直接依赖平台内部源码，而是通过统一的 SDK 边界，把公共能力沉淀为可复用、可发布、可升级的标准接入层。
+
+## 这个包解决什么问题
+
+当你的系统采用“平台基座 + 独立业务项目”的架构时，业务项目通常都需要复用同一批公共能力，例如：
+
+1. 用户登录、注册、身份校验
+2. 项目商品与项目权限查询
+3. 支付下单与订单支付状态查询
+4. 积分余额、预扣、确认、取消、流水查询
+5. AI 模型列表与余额能力
+
+如果每个子项目都自己手写请求逻辑，会很快出现以下问题：
+
+1. 接口路径、请求头、鉴权方式在多个项目里重复维护
+2. 返回结构和错误处理不统一
+3. 平台接口一旦升级，多个子项目要分别修改
+4. 子项目容易误依赖平台内部实现，造成耦合失控
+
+这个 SDK 就是为了解决这些问题而存在。
+
+## 设计目标
+
+1. 子项目只依赖稳定 API 协议，不依赖平台内部源码
+2. 公共能力通过统一客户端暴露，减少重复开发
+3. 平台服务和业务项目可以独立演进、独立部署
+4. 接口鉴权、错误处理、请求封装保持一致
+
+## 适用场景
+
+这个包适合以下场景：
+
+1. 你有一个独立部署的平台基座服务，对外暴露 `/api/v1` 稳定接口
+2. 你有多个独立部署的业务项目，需要复用平台提供的公共能力
+3. 你希望业务项目只关心自身业务逻辑，而不是重复实现认证、支付、积分、模型等底层接入
+
+## 当前支持的能力
+
+目前 SDK 已封装以下客户端：
+
+1. `auth`：认证与身份相关接口
+2. `projects`：项目商品、项目会员、项目权限相关接口
+3. `payment`：支付创建与支付状态查询接口
+4. `credits`：积分余额、流水、预扣、确认、取消、消费接口
+5. `ai`：AI 模型列表与 AI 余额接口
+
+## 安装方式
+
+```bash
+npm install api2key-base-sdk
+```
+
+## 使用前提
+
+1. Node.js 版本需要 `>=18`
+2. 平台服务已经对外提供稳定的 `/api/v1` 路由
+3. 你的业务项目可以拿到平台服务地址，以及所需的访问令牌或服务密钥
+
+## 快速开始
+
+```ts
+import { createPlatformAClient } from 'api2key-base-sdk';
+
+const platformA = createPlatformAClient({
+  baseUrl: process.env.PLATFORM_A_BASE_URL!,
+  getServiceSecret: () => process.env.PLATFORM_A_SERVICE_SECRET,
+  getProjectId: () => process.env.PLATFORM_A_PROJECT_ID,
+});
+
+const products = await platformA.projects.getProducts('project-b');
+```
+
+上面的示例做了三件事：
+
+1. 指定平台基座服务地址 `baseUrl`
+2. 提供服务间调用所需的密钥 `getServiceSecret`
+3. 提供当前业务项目标识 `getProjectId`
+
+然后就可以直接通过 `platformA.projects.getProducts('project-b')` 调用平台对外能力，而不需要在业务项目里重复拼接请求。
+
+## 创建客户端时可配置的内容
+
+创建 SDK 客户端时，常见可配置项包括：
+
+1. `baseUrl`：平台服务地址
+2. `fetchImpl`：自定义 `fetch` 实现
+3. `defaultHeaders`：默认请求头
+4. `getAccessToken`：获取用户访问令牌
+5. `getServiceSecret`：获取服务间调用密钥
+6. `getProjectId`：获取当前项目标识
+
+这意味着同一个 SDK 既可以被前端服务端渲染层使用，也可以被后端业务服务使用。
+
+## 各客户端说明
+
+### auth
+
+用于处理认证相关能力，例如：
+
+1. 登录
+2. 注册
+3. 获取当前用户信息
+4. 退出登录
+
+### projects
+
+用于处理与项目维度相关的能力，例如：
+
+1. 查询某个项目可售商品
+2. 查询当前用户在某个项目下的会员状态
+3. 查询当前用户的项目权限
+
+### payment
+
+用于统一支付流程接入，例如：
+
+1. 创建统一支付订单
+2. 查询支付状态
+
+### credits
+
+用于积分体系接入，例如：
+
+1. 查询余额
+2. 查询流水
+3. 预扣积分
+4. 确认扣减
+5. 取消预扣
+6. 直接消费积分
+
+### ai
+
+用于 AI 能力接入，例如：
+
+1. 获取当前可用模型列表
+2. 查询 AI 余额
+
+## 错误处理
+
+SDK 内部已经区分了两类错误：
+
+1. `PlatformApiError`：平台接口已返回响应，但返回的是业务错误或非成功状态
+2. `PlatformTransportError`：请求过程本身失败，例如网络异常、返回非 JSON、缺少必要密钥等
+
+建议业务项目在接入时分别处理这两类错误，以便更容易定位问题。
+
+## 为什么推荐通过 SDK 接入，而不是直接请求 API
+
+直接请求 API 并不是不能做，但从长期维护看，SDK 更合适：
+
+1. 路径、请求头、鉴权规则可以统一管理
+2. 返回结构可以统一抽象
+3. 错误处理语义更清晰
+4. 平台升级时只需要升级 SDK，而不是逐个修改业务项目
+
+## 发布约定
+
+当前包的发布约定如下：
+
+1. 包名为 `api2key-base-sdk`
+2. 通过 Git tag 触发自动发布
+3. tag 格式为 `v*`
+4. tag 里的版本号必须与 `package.json` 中的版本号一致
+5. GitHub Actions 优先建议使用 npm trusted publishing；如果使用 `NPM_TOKEN`，则必须是启用了 `Bypass 2FA` 的 npm granular publish token
+
+例如当版本为 `0.1.0` 时，应推送：
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## License
+
+当前包元信息中的许可证仍为 `UNLICENSED`。
+
+如果你的目标是公开开源分发，请在正式发布前明确许可证类型，并补充对应的 `LICENSE` 文件。

package/dist/ai/client.d.ts

@@ -0,0 +1,18 @@
+import { PlatformHttpClient } from '../core/client';
+import type { AiModelSummary } from '../core/types';
+export declare class AiClient {
+    private readonly http;
+    constructor(http: PlatformHttpClient);
+    getModels(input: {
+        projectId?: string;
+        accessToken?: string;
+    }): Promise<{
+        projectId?: string | null;
+        userTier?: string;
+        models: AiModelSummary[];
+        grouped?: Record<string, AiModelSummary[]>;
+    }>;
+    getBalance(accessToken?: string): Promise<{
+        balance: number;
+    }>;
+}

package/dist/ai/client.js

@@ -0,0 +1,14 @@
+export class AiClient {
+    constructor(http) {
+        this.http = http;
+    }
+    getModels(input) {
+        return this.http.request('/api/v1/ai/models', {
+            accessToken: input.accessToken,
+            query: { projectId: input.projectId },
+        });
+    }
+    getBalance(accessToken) {
+        return this.http.request('/api/v1/ai/balance', { accessToken });
+    }
+}

package/dist/auth/client.d.ts

@@ -0,0 +1,21 @@
+import { PlatformHttpClient } from '../core/client';
+import type { AuthSession, AuthUser } from '../core/types';
+export declare class AuthClient {
+    private readonly http;
+    constructor(http: PlatformHttpClient);
+    login(input: {
+        email: string;
+        password: string;
+    }): Promise<AuthSession>;
+    register(input: {
+        email: string;
+        password: string;
+        name?: string;
+        projectId?: string;
+    }): Promise<AuthSession>;
+    me(accessToken?: string): Promise<{
+        user: AuthUser;
+        membership?: unknown;
+    }>;
+    logout(accessToken?: string): Promise<null>;
+}

package/dist/auth/client.js

@@ -0,0 +1,28 @@
+export class AuthClient {
+    constructor(http) {
+        this.http = http;
+    }
+    login(input) {
+        return this.http.request('/api/v1/auth/login', {
+            method: 'POST',
+            body: input,
+        });
+    }
+    register(input) {
+        return this.http.request('/api/v1/auth/register', {
+            method: 'POST',
+            body: input,
+        });
+    }
+    me(accessToken) {
+        return this.http.request('/api/v1/auth/me', {
+            accessToken,
+        });
+    }
+    logout(accessToken) {
+        return this.http.request('/api/v1/auth/logout', {
+            method: 'POST',
+            accessToken,
+        });
+    }
+}

package/dist/core/client.d.ts

@@ -0,0 +1,8 @@
+import type { PlatformClientOptions, PlatformRequestOptions } from './types';
+export declare class PlatformHttpClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly options;
+    constructor(options: PlatformClientOptions);
+    request<T>(path: string, requestOptions?: PlatformRequestOptions): Promise<T>;
+}

package/dist/core/client.js

@@ -0,0 +1,68 @@
+import { PlatformApiError, PlatformTransportError } from './errors';
+function buildQueryString(query) {
+    if (!query)
+        return '';
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value == null)
+            continue;
+        params.set(key, String(value));
+    }
+    const serialized = params.toString();
+    return serialized ? `?${serialized}` : '';
+}
+export class PlatformHttpClient {
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async request(path, requestOptions = {}) {
+        const headers = new Headers(this.options.defaultHeaders);
+        headers.set('Content-Type', 'application/json');
+        if (requestOptions.headers) {
+            for (const [key, value] of Object.entries(requestOptions.headers)) {
+                headers.set(key, value);
+            }
+        }
+        const accessToken = requestOptions.accessToken ?? (await this.options.getAccessToken?.());
+        if (accessToken) {
+            headers.set('Authorization', `Bearer ${accessToken}`);
+        }
+        const projectId = requestOptions.projectId ?? (await this.options.getProjectId?.());
+        if (projectId) {
+            headers.set('X-Project-Id', projectId);
+        }
+        if (requestOptions.useServiceSecret) {
+            const serviceSecret = await this.options.getServiceSecret?.();
+            if (!serviceSecret) {
+                throw new PlatformTransportError('Missing service secret for platform API call');
+            }
+            headers.set('X-Service-Secret', serviceSecret);
+        }
+        const url = `${this.baseUrl}${path}${buildQueryString(requestOptions.query)}`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: requestOptions.method ?? 'GET',
+                headers,
+                body: requestOptions.body == null ? undefined : JSON.stringify(requestOptions.body),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown transport error';
+            throw new PlatformTransportError(message);
+        }
+        let payload = null;
+        try {
+            payload = (await response.json());
+        }
+        catch {
+            throw new PlatformTransportError(`Platform API returned a non-JSON response for ${url}`);
+        }
+        if (!response.ok) {
+            throw new PlatformApiError(payload.message, response.status, payload.code, payload.data);
+        }
+        return payload.data;
+    }
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class PlatformApiError extends Error {
+    readonly httpStatus: number;
+    readonly code: number;
+    readonly data: unknown;
+    constructor(message: string, httpStatus: number, code: number, data?: unknown);
+}
+export declare class PlatformTransportError extends Error {
+    constructor(message: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,15 @@
+export class PlatformApiError extends Error {
+    constructor(message, httpStatus, code, data = null) {
+        super(message);
+        this.name = 'PlatformApiError';
+        this.httpStatus = httpStatus;
+        this.code = code;
+        this.data = data;
+    }
+}
+export class PlatformTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PlatformTransportError';
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,121 @@
+export type MaybePromise<T> = T | Promise<T>;
+export interface PlatformEnvelope<T> {
+    code: number;
+    message: string;
+    data: T;
+}
+export interface PlatformClientOptions {
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+    defaultHeaders?: Record<string, string>;
+    getAccessToken?: () => MaybePromise<string | undefined>;
+    getServiceSecret?: () => MaybePromise<string | undefined>;
+    getProjectId?: () => MaybePromise<string | undefined>;
+}
+export interface PlatformRequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    headers?: Record<string, string>;
+    accessToken?: string;
+    projectId?: string;
+    useServiceSecret?: boolean;
+}
+export interface AuthUser {
+    id: string;
+    email: string;
+    name?: string;
+    avatar?: string | null;
+    role: 'user' | 'admin' | 'super_admin';
+    creditsBalance?: number;
+}
+export interface AuthSession {
+    user: AuthUser;
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+}
+export interface ProjectSummary {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string | null;
+}
+export interface ProductSummary {
+    id: string;
+    projectId?: string | null;
+    name: string;
+    description?: string | null;
+    price: number;
+    discountPrice?: number | null;
+    durationDays: number;
+    credits: number;
+    tier: string;
+    features: string[];
+    sortOrder?: number;
+}
+export interface MembershipView {
+    tier: string;
+    status: string;
+    start_date?: number | null;
+    end_date?: number | null;
+    source?: 'project' | 'global' | 'none';
+    credits?: number | null;
+    role?: string | null;
+    auto_renew?: number | null;
+    is_active?: boolean;
+    days_remaining?: number;
+}
+export interface CreditsBalance {
+    balance: number;
+    reserved?: number;
+    total_earned?: number;
+    total_spent?: number;
+}
+export interface CreditsLedgerItem {
+    id: string;
+    delta: number;
+    balance_after: number;
+    type: string;
+    service?: string | null;
+    model?: string | null;
+    description?: string | null;
+    created_at: number;
+}
+export interface PaymentCreateResponse {
+    paymentType: string;
+    orderNo: string;
+    unifiedOrderNo?: string;
+    data?: {
+        qrCode?: string;
+        payUrl?: string;
+        paypalOrderId?: string;
+    };
+}
+export interface PaymentQueryResponse {
+    localStatus: string;
+    unifiedStatus: number;
+    unifiedStatusDesc: string;
+    paid?: boolean;
+    order?: {
+        orderNo: string;
+        amount: number;
+        status: string;
+        paidAt?: number | null;
+    };
+}
+export interface AiModelSummary {
+    key: string;
+    id: string;
+    name: string;
+    modelId: string;
+    provider?: string | null;
+    modelType?: string | null;
+    minTier?: string | null;
+    creditCostPerRequest?: number | null;
+    isFeatured?: boolean | null;
+    description?: string | null;
+    inputPricing?: number;
+    outputPricing?: number;
+    locked?: boolean;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/credits/client.d.ts

@@ -0,0 +1,40 @@
+import { PlatformHttpClient } from '../core/client';
+import type { CreditsBalance, CreditsLedgerItem } from '../core/types';
+export declare class CreditsClient {
+    private readonly http;
+    constructor(http: PlatformHttpClient);
+    getBalance(accessToken?: string): Promise<CreditsBalance>;
+    getLedger(input: {
+        accessToken?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        list: CreditsLedgerItem[];
+        total?: number;
+    }>;
+    spend(input: {
+        userId: string;
+        amount: number;
+        service: string;
+        taskId?: string;
+        description?: string;
+    }): Promise<{
+        balanceAfter: number;
+        idempotent?: boolean;
+    }>;
+    reserve(input: {
+        userId: string;
+        amount: number;
+        service: string;
+        taskId: string;
+    }): Promise<{
+        reservation_id: string;
+        idempotent?: boolean;
+    }>;
+    confirm(id: string): Promise<{
+        ok: boolean;
+    }>;
+    cancel(id: string): Promise<{
+        ok: boolean;
+    }>;
+}

package/dist/credits/client.js

@@ -0,0 +1,43 @@
+export class CreditsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    getBalance(accessToken) {
+        return this.http.request('/api/v1/credits/balance', { accessToken });
+    }
+    getLedger(input) {
+        return this.http.request('/api/v1/credits/ledger', {
+            accessToken: input.accessToken,
+            query: {
+                page: input.page,
+                pageSize: input.pageSize,
+            },
+        });
+    }
+    spend(input) {
+        return this.http.request('/api/v1/credits/spend', {
+            method: 'POST',
+            body: input,
+            useServiceSecret: true,
+        });
+    }
+    reserve(input) {
+        return this.http.request('/api/v1/credits/reserve', {
+            method: 'POST',
+            body: input,
+            useServiceSecret: true,
+        });
+    }
+    confirm(id) {
+        return this.http.request(`/api/v1/credits/confirm/${id}`, {
+            method: 'POST',
+            useServiceSecret: true,
+        });
+    }
+    cancel(id) {
+        return this.http.request(`/api/v1/credits/cancel/${id}`, {
+            method: 'POST',
+            useServiceSecret: true,
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { PlatformHttpClient } from './core/client';
+import type { PlatformClientOptions } from './core/types';
+import { AuthClient } from './auth/client';
+import { ProjectsClient } from './projects/client';
+import { CreditsClient } from './credits/client';
+import { PaymentClient } from './payment/client';
+import { AiClient } from './ai/client';
+export * from './core/errors';
+export * from './core/types';
+export declare class PlatformAClient {
+    readonly http: PlatformHttpClient;
+    readonly auth: AuthClient;
+    readonly projects: ProjectsClient;
+    readonly credits: CreditsClient;
+    readonly payment: PaymentClient;
+    readonly ai: AiClient;
+    constructor(options: PlatformClientOptions);
+}
+export declare function createPlatformAClient(options: PlatformClientOptions): PlatformAClient;

package/dist/index.js

@@ -0,0 +1,21 @@
+import { PlatformHttpClient } from './core/client';
+import { AuthClient } from './auth/client';
+import { ProjectsClient } from './projects/client';
+import { CreditsClient } from './credits/client';
+import { PaymentClient } from './payment/client';
+import { AiClient } from './ai/client';
+export * from './core/errors';
+export * from './core/types';
+export class PlatformAClient {
+    constructor(options) {
+        this.http = new PlatformHttpClient(options);
+        this.auth = new AuthClient(this.http);
+        this.projects = new ProjectsClient(this.http);
+        this.credits = new CreditsClient(this.http);
+        this.payment = new PaymentClient(this.http);
+        this.ai = new AiClient(this.http);
+    }
+}
+export function createPlatformAClient(options) {
+    return new PlatformAClient(options);
+}

package/dist/payment/client.d.ts

@@ -0,0 +1,16 @@
+import { PlatformHttpClient } from '../core/client';
+import type { PaymentCreateResponse, PaymentQueryResponse } from '../core/types';
+export declare class PaymentClient {
+    private readonly http;
+    constructor(http: PlatformHttpClient);
+    createUnified(input: {
+        orderId: string;
+        paymentType?: 'alipay' | 'wechat' | 'paypal';
+        accessToken?: string;
+    }): Promise<PaymentCreateResponse>;
+    queryUnified(input: {
+        orderId?: string;
+        orderNo?: string;
+        accessToken?: string;
+    }): Promise<PaymentQueryResponse>;
+}

package/dist/payment/client.js

@@ -0,0 +1,24 @@
+export class PaymentClient {
+    constructor(http) {
+        this.http = http;
+    }
+    createUnified(input) {
+        return this.http.request('/api/v1/payment/unified/create', {
+            method: 'POST',
+            accessToken: input.accessToken,
+            body: {
+                orderId: input.orderId,
+                paymentType: input.paymentType ?? 'wechat',
+            },
+        });
+    }
+    queryUnified(input) {
+        return this.http.request('/api/v1/payment/unified/query', {
+            accessToken: input.accessToken,
+            query: {
+                orderId: input.orderId,
+                orderNo: input.orderNo,
+            },
+        });
+    }
+}

package/dist/projects/client.d.ts

@@ -0,0 +1,22 @@
+import { PlatformHttpClient } from '../core/client';
+import type { MembershipView, ProductSummary, ProjectSummary } from '../core/types';
+export declare class ProjectsClient {
+    private readonly http;
+    constructor(http: PlatformHttpClient);
+    getProducts(projectId: string): Promise<{
+        project: ProjectSummary | null;
+        products: ProductSummary[];
+        total?: number;
+    }>;
+    getMembership(projectId: string, accessToken?: string): Promise<{
+        project: ProjectSummary;
+        membership: MembershipView;
+    }>;
+    getPermissions(input: {
+        accessToken?: string;
+        projectId?: string;
+    }): Promise<{
+        permission?: unknown;
+        permissions?: unknown[];
+    }>;
+}

package/dist/projects/client.js

@@ -0,0 +1,17 @@
+export class ProjectsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    getProducts(projectId) {
+        return this.http.request(`/api/v1/projects/${projectId}/products`);
+    }
+    getMembership(projectId, accessToken) {
+        return this.http.request(`/api/v1/projects/${projectId}/membership`, { accessToken });
+    }
+    getPermissions(input) {
+        return this.http.request('/api/v1/user/project-permissions', {
+            accessToken: input.accessToken,
+            query: { projectId: input.projectId },
+        });
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "api2key-base-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for consuming the Api2Key API stable APIs",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "platform",
+    "foundation",
+    "sdk",
+    "typescript",
+    "api-client",
+    "billing",
+    "credits",
+    "hono",
+    "cloudflare-workers"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "pack:check": "npm pack --dry-run",
+    "release:check": "npm run clean && npm run type-check && npm run build && npm run pack:check",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run type-check && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}