Engine Client

OneEngineClient 是 ONE SDK 中所有服务端通信的统一入口。本页介绍其构造方式、配置选项、Token 管理和请求生命周期。

导入

import { createOneEngineClient } from '@one_deploy/sdk';

工厂函数

function createOneEngineClient(options?: OneEngineClientOptions): OneEngineClient;

OneEngineClientOptions

interface OneEngineClientOptions {
  /** Base URL for the ONE Engine API. Defaults to "https://engine.one23.io". */
  engineUrl?: string;
  /** Project client ID from the dashboard. */
  clientId: string;
  /** Project secret key from the dashboard. */
  secretKey: string;
}

选项	类型	是否必填	默认值	说明
engineUrl	string	否	https://engine.one23.io	ONE Engine API 的基础 URL。
clientId	string	是	--	从 ONE 控制面板获取的项目 Client ID。
secretKey	string	是	--	从 ONE 控制面板获取的项目 Secret Key。

基本构造

const engine = createOneEngineClient({
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

自定义 Engine URL

将客户端指向测试环境或自托管实例：

const engine = createOneEngineClient({
  engineUrl: 'https://staging-engine.one23.io',
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

Access Token 管理

受保护的 endpoint 需要 Bearer token。在完成用户身份验证后，将 token 存储到客户端实例上。

setAccessToken

engine.setAccessToken(token: string): void;

参数	类型	是否必填	说明
token	string	是	由身份验证方法返回的 JWT access token。

示例流程

// 1. Create the engine client
const engine = createOneEngineClient({
  clientId: 'proj_abc123',
  secretKey: 'sk_live_xyz789',
});

// 2. Authenticate (email OTP flow)
const otpRes = await engine.sendEmailOtp('user@example.com');
// ... user enters the OTP code ...
const authRes = await engine.verifyEmailOtp('user@example.com', '123456');

if (authRes.success && authRes.data) {
  // 3. Store the token on the client
  engine.setAccessToken(authRes.data.accessToken);
}

// 4. Now call protected endpoints
const walletRes = await engine.getWalletBalance('0xABC...');

请求生命周期

每个方法都遵循相同的内部流程：

1. Serialize parameters to JSON body or query string.
2. Attach headers:
   - x-client-id: <clientId>
   - x-secret-key: <secretKey>
   - Authorization: Bearer <accessToken>  (if set)
   - Content-Type: application/json
3. Send HTTP request to engineUrl + endpoint path.
4. Parse JSON response into ApiResponse<T>.
5. Return { success, data?, error? }.

请求头

请求头	来源	是否始终发送
x-client-id	来自选项的 clientId	是
x-secret-key	来自选项的 secretKey	是
Authorization	通过 setAccessToken 设置的 Bearer <token>	仅在设置了 token 时
Content-Type	application/json	是

响应处理

所有方法返回 ApiResponse<T>：

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

成功路径

const res = await engine.getCurrentUser();
if (res.success) {
  console.log('User:', res.data);
}

错误路径

const res = await engine.getCurrentUser();
if (!res.success) {
  console.error('Failed:', res.error);
  // res.error is a human-readable string like "unauthorized"
}

单例模式（React）

在 React 应用中，客户端通常只创建一次，并通过 context 共享：

// lib/engine.ts
import { createOneEngineClient } from '@one_deploy/sdk';

export const engine = createOneEngineClient({
  clientId: process.env.NEXT_PUBLIC_ONE_CLIENT_ID!,
  secretKey: process.env.NEXT_PUBLIC_ONE_SECRET_KEY!,
});

当使用 OneProvider 时，provider 会在内部创建并管理客户端。通过 useOneEngine hook 访问它：

import { useOneEngine } from '@one_deploy/sdk';

function MyComponent() {
  const engine = useOneEngine();
  // engine is a fully configured OneEngineClient
}

React Native -- 缓存客户端

对于 React Native，使用缓存工厂函数以避免在每次渲染时重新创建客户端：

import { createCachedEngineClient } from '@one_deploy/sdk';

const engine = createCachedEngineClient({
  clientId: 'proj_abc123',
  secretKey: 'sk_live_xyz789',
});

当使用相同选项再次调用时，此函数将返回同一个实例。

下一步

• Auth API -- 对用户进行身份验证并获取 access token。
• Wallet API -- 查询余额并发送交易。
• API 参考概览 -- 完整方法索引。