管理员 API

管理员 API 提供了 11 个平台管理方法。本节中的所有方法都要求已认证用户具有 admin 角色。非管理员用户将收到 "forbidden" 错误。

警告

这些 endpoint 仅限管理员用户使用。access token 必须属于 role: 'admin' 的用户。

方法

方法	参数	返回值	描述
adminListUsers(options?)	options?: AdminListOptions	ApiResponse<PaginatedResult<AdminUser>>	列出所有平台用户，支持分页和筛选。
adminGetUser(userId)	userId: string	ApiResponse<AdminUser>	返回单个用户的详细资料和使用数据。
adminUpdateUser(userId, updates)	userId: string, updates: AdminUserUpdate	ApiResponse<AdminUser>	更新用户的资料、角色或状态。
adminListProjects(options?)	options?: AdminListOptions	ApiResponse<PaginatedResult<AdminProject>>	列出平台上的所有项目。
adminGetProject(projectId)	projectId: string	ApiResponse<AdminProject>	返回项目的详细配置和使用数据。
adminUpdateProject(projectId, updates)	projectId: string, updates: AdminProjectUpdate	ApiResponse<AdminProject>	更新项目的设置或状态。
adminRegenerateApiKey(projectId)	projectId: string	ApiResponse<{ clientId: string; secretKey: string }>	重新生成项目的 API 密钥。旧密钥立即失效。
adminGetStats()	--	ApiResponse<SystemStats>	返回系统级统计数据（用户、项目、交易、收入）。
adminGetLogs(options?)	options?: LogQueryOptions	ApiResponse<SystemLog[]>	查询平台审计和错误日志。
adminGetRateLimits(projectId?)	projectId?: string	ApiResponse<RateLimitInfo[]>	返回当前速率限制状态，可选限定到某个项目。
adminClearRateLimits(projectId)	projectId: string	ApiResponse<{ cleared: boolean }>	清除项目的速率限制计数器。

类型

AdminUser

interface AdminUser {
  id: string;
  email?: string;
  walletAddress?: string;
  displayName?: string;
  avatarUrl?: string;
  role: 'user' | 'admin';
  status: 'active' | 'suspended' | 'banned';
  /** Number of projects owned by this user. */
  projectCount: number;
  /** Total API calls made by this user. */
  totalApiCalls: number;
  /** Last login timestamp. */
  lastLoginAt?: string;
  createdAt: string;
  updatedAt: string;
}

AdminUserUpdate

interface AdminUserUpdate {
  displayName?: string;
  role?: 'user' | 'admin';
  status?: 'active' | 'suspended' | 'banned';
}

AdminProject

interface AdminProject {
  id: string;
  name: string;
  ownerId: string;
  ownerEmail?: string;
  /** Masked client ID. */
  clientId: string;
  plan: 'free' | 'starter' | 'pro' | 'enterprise';
  status: 'active' | 'suspended' | 'archived';
  /** Enabled feature flags. */
  features: string[];
  /** API call count for the current billing period. */
  apiCallsThisPeriod: number;
  /** API call limit for the current plan. */
  apiCallLimit: number;
  /** Monthly revenue from this project. */
  monthlyRevenue?: string;
  createdAt: string;
  updatedAt: string;
}

AdminProjectUpdate

interface AdminProjectUpdate {
  name?: string;
  plan?: 'free' | 'starter' | 'pro' | 'enterprise';
  status?: 'active' | 'suspended' | 'archived';
  apiCallLimit?: number;
}

AdminListOptions

interface AdminListOptions {
  /** Search by email, name, or ID. */
  search?: string;
  /** Filter by status. */
  status?: string;
  /** Filter by role (users) or plan (projects). */
  role?: string;
  plan?: string;
  /** Sort field. */
  sortBy?: 'createdAt' | 'updatedAt' | 'apiCalls';
  /** Sort direction. */
  sortOrder?: 'asc' | 'desc';
  /** Page number (1-based). */
  page?: number;
  /** Items per page. Default 20, max 100. */
  pageSize?: number;
}

PaginatedResult<T>

interface PaginatedResult<T> {
  items: T[];
  totalCount: number;
  page: number;
  pageSize: number;
  totalPages: number;
  hasMore: boolean;
}

SystemStats

interface SystemStats {
  totalUsers: number;
  activeUsers30d: number;
  totalProjects: number;
  activeProjects30d: number;
  totalTransactions: number;
  transactions24h: number;
  totalApiCalls: number;
  apiCalls24h: number;
  totalRevenue: string;
  revenue30d: string;
  topChains: { chainId: string; chainName: string; transactionCount: number }[];
  /** Stats snapshot timestamp. */
  generatedAt: string;
}

SystemLog

interface SystemLog {
  id: string;
  level: 'info' | 'warn' | 'error';
  /** Log category (e.g. "auth", "transaction", "webhook"). */
  category: string;
  message: string;
  /** Associated user ID, if applicable. */
  userId?: string;
  /** Associated project ID, if applicable. */
  projectId?: string;
  /** Additional metadata. */
  metadata?: Record<string, unknown>;
  timestamp: string;
}

LogQueryOptions

interface LogQueryOptions {
  level?: 'info' | 'warn' | 'error';
  category?: string;
  userId?: string;
  projectId?: string;
  startDate?: string;
  endDate?: string;
  search?: string;
  limit?: number;
  cursor?: string;
}

RateLimitInfo

interface RateLimitInfo {
  projectId: string;
  projectName: string;
  /** Endpoint or endpoint group. */
  endpoint: string;
  /** Current request count in the window. */
  currentCount: number;
  /** Maximum requests allowed in the window. */
  limit: number;
  /** Window duration in seconds. */
  windowSeconds: number;
  /** Time until the window resets (seconds). */
  resetsIn: number;
  /** Whether the project is currently rate-limited. */
  isLimited: boolean;
}

示例

列出用户

const res = await engine.adminListUsers({
  status: 'active',
  sortBy: 'createdAt',
  sortOrder: 'desc',
  page: 1,
  pageSize: 20,
});

if (res.success && res.data) {
  console.log(`Total users: ${res.data.totalCount}`);
  for (const user of res.data.items) {
    console.log(`${user.id} | ${user.email ?? user.walletAddress} | ${user.role} | API calls: ${user.totalApiCalls}`);
  }
}

暂停用户

const res = await engine.adminUpdateUser('user_xyz', {
  status: 'suspended',
});

if (res.success && res.data) {
  console.log(`User ${res.data.id} status: ${res.data.status}`);
}

查看系统统计

const res = await engine.adminGetStats();

if (res.success && res.data) {
  const s = res.data;
  console.log(`Users: ${s.totalUsers} (${s.activeUsers30d} active in 30d)`);
  console.log(`Projects: ${s.totalProjects} (${s.activeProjects30d} active in 30d)`);
  console.log(`Transactions 24h: ${s.transactions24h}`);
  console.log(`API calls 24h: ${s.apiCalls24h}`);
  console.log(`Revenue (30d): $${s.revenue30d}`);
}

查询错误日志

const res = await engine.adminGetLogs({
  level: 'error',
  category: 'transaction',
  limit: 50,
});

if (res.success && res.data) {
  for (const log of res.data) {
    console.log(`[${log.timestamp}] ${log.level.toUpperCase()} [${log.category}] ${log.message}`);
  }
}

管理速率限制

// Check rate limits for a project
const limitsRes = await engine.adminGetRateLimits('proj_abc123');

if (limitsRes.success && limitsRes.data) {
  for (const rl of limitsRes.data) {
    console.log(`${rl.endpoint}: ${rl.currentCount}/${rl.limit} (resets in ${rl.resetsIn}s)`);
    if (rl.isLimited) {
      console.log('  ** Currently rate-limited **');
    }
  }
}

// Clear rate limits for a project
const clearRes = await engine.adminClearRateLimits('proj_abc123');
if (clearRes.success && clearRes.data?.cleared) {
  console.log('Rate limits cleared');
}

重新生成 API 密钥

const res = await engine.adminRegenerateApiKey('proj_abc123');

if (res.success && res.data) {
  console.log('New client ID:', res.data.clientId);
  console.log('New secret key:', res.data.secretKey);
  // Communicate new keys to the project owner securely
}

列出和更新项目

// List projects on the free plan
const res = await engine.adminListProjects({
  plan: 'free',
  sortBy: 'apiCalls',
  sortOrder: 'desc',
  pageSize: 10,
});

if (res.success && res.data) {
  for (const proj of res.data.items) {
    console.log(`${proj.name} | ${proj.plan} | Calls: ${proj.apiCallsThisPeriod}/${proj.apiCallLimit}`);
  }
}

// Upgrade a project
await engine.adminUpdateProject('proj_abc123', {
  plan: 'pro',
  apiCallLimit: 100000,
});

后续步骤

• Project API -- 面向非管理员用户的项目管理。
• Webhooks API -- 配置事件通知。