@aixnn/aixautots 0.0.0-stage → 0.5.2

package/dist/config-Bm1hmXhD.d.ts

@@ -0,0 +1,1380 @@
+import { w as AuthResult, aH as SendCodeResult, a$ as VerifyCodeResult, ar as ProjectUserResult, ap as Project, I as CreateProjectInput, J as CreateProjectResult, as as ProvisionUserInput, at as ProvisionUserResult, D as DeviceRow, P as ProvisionSpec, a as ProvisionResult, C as CatalogBrand, R as DeviceOp, aG as ScreenshotResult, X as ElementNode, am as PowerAction, r as AppCandidate, aD as RecycledDeviceRow, aw as ProxyPatchResult, ax as ProxyProbe, T as DeviceProfileView, aK as SetProfileResult, ao as ProfileOverrides, a3 as InstallAntiDetectResult, aJ as SetDisguiseResult, N as NodeRow, aE as RegisterNodeInput, aF as RegisterNodeResult, aZ as UpdateNodeInput, aI as SetDataRootResult, o as AgentTaskSubmitInput, p as AgentTaskSubmitResult, m as AgentTaskReadResult, l as AgentTaskEventsResult, b as DiscoveredDevice, i as AdbScanResult, a8 as IosScanResult, a4 as IosAccountState, a7 as IosLoginResult, a6 as IosLibraryApp, E as Cluster, G as CreateClusterInput, f as ScriptSummary, S as Script, aL as Shortcut, ae as NewShortcut, ab as Locator, H as CreateLocatorInput, $ as FleetRunSubmit, Z as FleetRunDetail, aT as TaskStatus, aR as TaskListFilter, aS as TaskListResult, aQ as TaskEventsResult, b0 as WebhookConfig, L as CreateWebhookInput, aa as LlmTestResult, U as DeviceRate, aB as RateInput, y as BillingPlan, aj as PlanInput, V as DeviceUsageSession, aC as RebateLedgerRow, ak as PlatformOem, al as PlatformOemInput, a0 as ImageArtifact, a1 as ImageInput, a2 as ImageOption, x as BalanceResp, aq as ProjectSubscription, aO as SubscribeInput, ai as OwnNodeDailyCharge, aX as TopupInput, aY as TopupResult, q as ApiTokenRow, K as CreateTokenInput, M as CreatedToken, t as AppTemplate, ad as NewAppTemplate, ah as NodeScope } from './types-C2WXVcam.js';
+
+type OutgoingFrame = {
+    t: 'adb_exec';
+    id: string;
+    argv: string[];
+    timeout_ms?: number;
+} | {
+    t: 'wda_req';
+    id: string;
+    method: string;
+    path: string;
+    body?: unknown;
+} | {
+    t: 'frida_run';
+    id: string;
+    script: string;
+    target?: unknown;
+    spawn?: boolean;
+} | {
+    t: 'frida_call';
+    id: string;
+    run_id: string;
+    method: string;
+    args?: unknown;
+} | {
+    t: 'frida_cancel';
+    id: string;
+    run_id: string;
+} | {
+    t: 'scriptlet_run';
+    id: string;
+    script: string;
+    vars?: unknown;
+} | {
+    t: 'scriptlet_call';
+    id: string;
+    run_id: string;
+    method: string;
+    args?: unknown;
+} | {
+    t: 'scriptlet_cancel';
+    id: string;
+    run_id: string;
+} | {
+    t: 'open';
+    stream: string;
+    kind: 'adb' | 'wda' | 'frida' | 'tcp';
+    addr?: string;
+} | {
+    t: 'data';
+    stream: string;
+    b64: string;
+} | {
+    t: 'close';
+    stream: string;
+};
+interface RetFrame {
+    t: 'ret';
+    id: string | null;
+    ok: boolean;
+    value?: unknown;
+    error?: string;
+}
+interface FridaEventFrame {
+    t: 'frida_event';
+    run_id: string;
+    name: string;
+    data: unknown;
+}
+interface ScriptletEventFrame {
+    t: 'scriptlet_event';
+    run_id: string;
+    name: string;
+    data: unknown;
+}
+interface StatusFrame {
+    t: 'status';
+    state: string;
+    detail?: string;
+    stream?: string;
+}
+type RunEventKind = {
+    kind: 'started';
+    total: number;
+} | {
+    kind: 'step';
+    index: number;
+    status: string;
+} | {
+    kind: 'finished';
+    status: string;
+    error?: string;
+};
+interface ExecutionFrame {
+    run_id: string;
+    device_id: string;
+    event: RunEventKind;
+}
+interface EnvStepMeta {
+    id: string;
+    label: string;
+}
+interface EnvResultDto {
+    vm: string;
+    arch: string;
+    docker_socket: string;
+    env: Record<string, string>;
+}
+type EnvEventKind = {
+    kind: 'started';
+    total: number;
+    steps: EnvStepMeta[];
+} | {
+    kind: 'step';
+    index: number;
+    id: string;
+    state: string;
+    pct: number;
+    detail?: string | null;
+} | {
+    kind: 'log';
+    index: number;
+    id: string;
+    line: string;
+} | {
+    kind: 'finished';
+    ok: boolean;
+    result?: EnvResultDto | null;
+    failed_id?: string | null;
+    code?: string | null;
+    error?: string | null;
+    hint?: string | null;
+};
+type IncomingFrame = RetFrame | FridaEventFrame | ScriptletEventFrame | StatusFrame | ExecutionFrame | {
+    t: string;
+    [k: string]: unknown;
+};
+declare function parseIncoming(text: string): IncomingFrame;
+declare function isRetFrame(f: IncomingFrame): f is RetFrame;
+declare function isFridaEventFrame(f: IncomingFrame): f is FridaEventFrame;
+declare function isScriptletEventFrame(f: IncomingFrame): f is ScriptletEventFrame;
+declare function isStatusFrame(f: IncomingFrame): f is StatusFrame;
+declare function isExecutionFrame(f: IncomingFrame): f is ExecutionFrame;
+/** An env-base event frame: top-level `kind` ∈ started|step|log|finished, and
+ *  (unlike ExecutionFrame) no `run_id`/`device_id`. */
+declare function isEnvEventFrame(f: unknown): f is EnvEventKind;
+
+/** Per-request auth scope. Mirrors the backend extractors:
+ *  - `caller`    → CallerScope (project key/secret OR user bearer)
+ *  - `developer` → DeveloperAuth (dev bearer)
+ *  - `admin`     → PlatformAdminAuth (dev bearer whose developer is an admin)
+ *  - `public`    → no credentials (login / send-code / etc). */
+type Scope = 'caller' | 'developer' | 'admin' | 'public';
+/** A single credential the SDK can authenticate with. A config may carry
+ *  several (e.g. the in-house app holds a developer token AND a project-scoped
+ *  user token); the provider picks the right one per scope. */
+type Credential = {
+    kind: 'project';
+    key: string;
+    secret: string;
+} | {
+    kind: 'user';
+    getToken: () => string | Promise<string>;
+} | {
+    kind: 'developer';
+    getToken: () => string | Promise<string>;
+};
+interface AuthProvider {
+    /** Resolve the HTTP headers required for a request at the given scope.
+     *  Throws AixAuthError when no credential satisfies the scope. */
+    headers(scope: Scope): Promise<Record<string, string>>;
+    /** The user/project caller credential as a query-param token where one
+     *  exists (used for WS urls that cannot carry headers). Null otherwise. */
+    callerBearer(): Promise<string | null>;
+}
+/** Build an AuthProvider from one or more credentials. Resolution per scope:
+ *  - caller:    project headers first (third-party path), else user bearer.
+ *  - developer: developer bearer.
+ *  - admin:     developer bearer (admin gate is enforced server-side).
+ *  - public:    no headers. */
+declare function buildAuthProvider(input: Credential | Credential[]): AuthProvider;
+interface CachedUserCredentialOpts {
+    /** Mint a fresh user JWT — typically a `fetch` to your own backend's
+     *  token endpoint. Return the raw token, or `{ token, expiresIn }` (seconds). */
+    mint: () => Promise<string | {
+        token: string;
+        expiresIn?: number;
+    }>;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** TTL when expiry can't be derived (no `expiresIn`, no JWT `exp`); default 10 min. */
+    fallbackTtlMs?: number;
+    /** Injectable clock (tests). Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** A `user` credential that mints a JWT via `opts.mint` and caches it until
+ *  (near) expiry — derived from `expiresIn` or the JWT `exp` claim. Concurrent
+ *  `getToken()` calls share one in-flight mint (no stampede).
+ *
+ *  The mint itself stays with the caller (e.g. a third-party frontend fetching
+ *  from its own backend, which holds the project key/secret) — the SDK never
+ *  needs the project secret in the browser. */
+declare function createCachedUserCredential(opts: CachedUserCredentialOpts): Extract<Credential, {
+    kind: 'user';
+}>;
+
+/** 客户端 → 节点的请求帧(均带自增 `id`)。 */
+type DeviceReq = {
+    id: string;
+    t: 'list';
+    path: string;
+} | {
+    id: string;
+    t: 'delete';
+    path: string;
+    recursive?: boolean;
+} | {
+    id: string;
+    t: 'mkdir';
+    path: string;
+} | {
+    id: string;
+    t: 'rename';
+    from: string;
+    to: string;
+} | {
+    id: string;
+    t: 'exec';
+    cmd: string;
+} | {
+    id: string;
+    t: 'put';
+    name: string;
+    size: number;
+    sha256: string;
+    dest: string;
+} | {
+    id: string;
+    t: 'chunk';
+    offset: number;
+    bytes: string;
+} | {
+    id: string;
+    t: 'eof';
+} | {
+    id: string;
+    t: 'get';
+    src: string;
+} | {
+    id: string;
+    t: 'open';
+    kind: 'tcp';
+    host: string;
+    port: number;
+} | {
+    id: string;
+    t: 'open';
+    kind: 'exec';
+    cmd: string;
+} | {
+    id: string;
+    t: 'data';
+    bytes: string;
+} | {
+    id: string;
+    t: 'close';
+};
+/** 节点 → 客户端的响应帧(均带原 `id`)。 */
+type DeviceResp = {
+    id: string;
+    t: 'list_ok';
+    entries: FileEntry[];
+} | {
+    id: string;
+    t: 'ok';
+} | {
+    id: string;
+    t: 'err';
+    message: string;
+} | {
+    id: string;
+    t: 'stdout';
+    data: string;
+} | {
+    id: string;
+    t: 'stderr';
+    data: string;
+} | {
+    id: string;
+    t: 'exit';
+    code: number;
+} | {
+    id: string;
+    t: 'ack';
+    offset: number;
+} | {
+    id: string;
+    t: 'chunk';
+    offset: number;
+    bytes: string;
+    size?: number;
+} | {
+    id: string;
+    t: 'done';
+    sha256?: string;
+    size?: number;
+} | {
+    id: string;
+    t: 'opened';
+} | {
+    id: string;
+    t: 'data';
+    bytes: string;
+} | {
+    id: string;
+    t: 'close';
+};
+/** 通用流入参:TCP 端口转发(host:port 为**节点可达**地址)或交互式 exec。 */
+type StreamTarget = {
+    kind: 'tcp';
+    host: string;
+    port: number;
+} | {
+    kind: 'exec';
+    cmd: string;
+};
+/**
+ * 双工字节流:`openStream` / `shell` 的返回。把"终端"泛化成通用字节流,
+ * 端口转发也复用它。语义:
+ *   - `write(bytes)`:向流写字节(TCP write / 子进程 stdin)。
+ *   - `onData(cb)`:订阅流的出站字节(TCP 读 / 子进程 stdout+stderr 合并)。
+ *   - `onClose(cb)`:流被对端关闭(TCP 关 / 子进程退出)或本地 `close()` 后触发(一次)。
+ *   - `close()`:主动关闭流(发 `{id,t:"close"}`)。
+ */
+interface DcStream {
+    write(bytes: Uint8Array): void;
+    onData(cb: (bytes: Uint8Array) => void): void;
+    onClose(cb: () => void): void;
+    close(): void;
+}
+/** 目录项(节点 `ls` 解析结果)。 */
+interface FileEntry {
+    name: string;
+    size: number;
+    is_dir: boolean;
+    mode?: string;
+    mtime?: string;
+    is_link?: boolean;
+}
+interface TransferProgress {
+    /** 已传输字节。 */
+    loaded: number;
+    /** 总字节(pull 时若未知则为 0,直到收到首个 chunk/done)。 */
+    total: number;
+    /** 当前所用通道:'dc' = WebRTC 直连,'r2' = R2 中转兜底。 */
+    channel: 'dc' | 'r2';
+}
+type ProgressFn = (p: TransferProgress) => void;
+/** 传输结果:实际成功所用通道 + 是否走了兜底。 */
+interface TransferResult {
+    channel: 'dc' | 'r2';
+    /** 是否走了兜底(true 时 UI 可提示"已用中转通道")。 */
+    fellBack: boolean;
+}
+/** push 入参:通用字节 + 文件名 + 设备目标路径(**不接受浏览器 File**)。 */
+interface PushInput {
+    /** 待上传的字节。 */
+    data: Uint8Array | ArrayBuffer;
+    /** 文件名(用于 put 元数据 / R2 兜底的 upload-url)。 */
+    filename: string;
+    /** 设备目标路径,如 /sdcard/Download/x.apk。 */
+    dest: string;
+}
+/** pull 结果:通用字节 + 文件名(下载触发由上层做)。 */
+interface PullResult extends TransferResult {
+    /** 拉回的字节。 */
+    data: Uint8Array;
+    /** 文件名(取自 src 末段)。 */
+    filename: string;
+}
+interface TransferOpts {
+    onProgress?: ProgressFn;
+    /** answerer 建链超时(ms),默认 15000。 */
+    dcTimeoutMs?: number;
+}
+/**
+ * 设备会话:一条 "ctrl" DataChannel 上多路复用文件管理(list/delete/mkdir/rename)、
+ * 终端(exec 流式)、文件传输(put/get)。每个操作分配自增 `id`,节点回应按 `id`
+ * 路由,故可并发(一边传文件一边 list)。
+ *
+ * 用法:`const s = await DeviceSession.open(client, deviceId); ...; s.close()`。
+ */
+declare class DeviceSession {
+    readonly session: string;
+    private readonly dc;
+    private readonly dispose;
+    private nextId;
+    /** id → 该操作的响应路由回调(多路复用核心)。 */
+    private readonly pending;
+    private closed;
+    private constructor();
+    /**
+     * 打开一个设备会话:dcSession 握手 → answerer 建链 → 等 "ctrl" 通道 open。
+     * @param source   `AixClient` 或 `AixConfig | ResolvedConfig`
+     * @param deviceId 设备 id
+     * @param opts.dcTimeoutMs 建链超时(ms),默认 15000
+     */
+    static open(source: AixClient | AixConfig | ResolvedConfig, deviceId: string, opts?: {
+        dcTimeoutMs?: number;
+    }): Promise<DeviceSession>;
+    private allocId;
+    private ensureOpen;
+    private sendReq;
+    /** 列目录:返回 entries。节点 `ls -la` 解析后回 `list_ok`。 */
+    listFiles(path: string): Promise<FileEntry[]>;
+    /** 删除文件/目录(recursive=true 走 `rm -rf`)。 */
+    deleteFile(path: string, recursive?: boolean): Promise<void>;
+    /** 新建目录(`mkdir -p`)。 */
+    mkdir(path: string): Promise<void>;
+    /** 重命名/移动(`mv from to`)。 */
+    rename(from: string, to: string): Promise<void>;
+    /** 共享:发一条请求(由 id 构造完整帧),等节点回 `ok` / `err`。 */
+    private simpleOk;
+    /** 执行命令并收齐输出:返回 `{stdout, stderr, exitCode}`。 */
+    exec(cmd: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /** 流式执行命令:stdout/stderr 分块回调,resolve 退出码。 */
+    execStream(cmd: string, hooks?: {
+        onStdout?: (d: string) => void;
+        onStderr?: (d: string) => void;
+    }): Promise<number>;
+    /** 推字节到设备 `dest`:put → chunk... → eof,节点逐块回 `ack` 推进进度。 */
+    pushFile(input: PushInput, onProgress?: ProgressFn): Promise<void>;
+    /** 从设备 `src` 拉字节,收齐后返回 Uint8Array。节点流式回 chunk + done。 */
+    pullFile(src: string, onProgress?: ProgressFn): Promise<Uint8Array>;
+    /**
+     * 打开一条通用双工字节流(多路复用,沿用同一 DC)。
+     *   - `{kind:'tcp',host,port}`:节点 `TcpStream::connect(host:port)`,host 是
+     *     **节点可达**的地址(设备 adb-forward 出的端口、节点本机/局域网服务等)。
+     *   - `{kind:'exec',cmd}`:节点 spawn `adb shell <cmd>`(交互式:write→stdin,
+     *     stdout/stderr 合并→onData)。
+     * 返回的 `DcStream` 在收到节点 `opened` 后即可用;若节点回 `err` 则 reject。
+     */
+    openStream(target: StreamTarget): Promise<DcStream>;
+    /** 交互式终端:`= openStream({kind:'exec',cmd})`,cmd 默认 `sh`(交互式 shell)。 */
+    shell(cmd?: string): Promise<DcStream>;
+    /**
+     * 本地端口转发(**仅 Node 环境**):用 `node:net` 监听 `localPort`,每个进来的
+     * 连接都开一条 `openStream({kind:'tcp',host,port})` 并双向 pipe。返回停止函数
+     * (关闭监听 + 现有连接)。浏览器环境无 `node:net`,调用会抛"仅 node 可用"。
+     *
+     * 用动态 import('node:net') + try,避免把 node:net 打进浏览器 bundle
+     * (frontend 不会调用本方法)。
+     */
+    forwardLocalPort(localPort: number, remote: {
+        host: string;
+        port: number;
+    }): Promise<() => void>;
+    /** 关闭会话:断开 DC + pc + 信令 socket,清空 pending。 */
+    close(): void;
+}
+/**
+ * 推文件到设备:先试通道 A(DeviceSession DC 直连);DC 建链超时或任意失败 →
+ * 无感回退通道 B(R2 中转)。**通用入参**:接收字节而非浏览器 File。
+ *
+ * @param source   `AixClient` 或 `AixConfig | ResolvedConfig`
+ * @param deviceId 设备 id
+ * @param input    `{ data: Uint8Array|ArrayBuffer, filename, dest }`
+ */
+declare function pushFile(source: AixClient | AixConfig | ResolvedConfig, deviceId: string, input: PushInput, opts?: TransferOpts): Promise<TransferResult>;
+/**
+ * 从设备拉文件:先试通道 A;DC 建链超时或失败则无感回退通道 B(R2)。返回
+ * `{ data: Uint8Array, filename, channel, fellBack }`——下载触发由上层做。
+ *
+ * @param source   `AixClient` 或 `AixConfig | ResolvedConfig`
+ * @param deviceId 设备 id
+ * @param src      设备源路径,如 /sdcard/x.log
+ */
+declare function pullFile(source: AixClient | AixConfig | ResolvedConfig, deviceId: string, src: string, opts?: TransferOpts): Promise<PullResult>;
+
+interface RequestOpts {
+    /** Auth scope; defaults to 'caller'. */
+    scope?: Scope;
+    /** JSON body (serialized unless it is a string already). */
+    body?: unknown;
+    /** Query params (undefined values are skipped). */
+    query?: Record<string, string | number | boolean | undefined | null>;
+    /** Extra headers (override auth/content-type when set). */
+    headers?: Record<string, string>;
+}
+/** Thin REST client over `ResolvedConfig` (fetchFn + AuthProvider). Maps
+ *  HTTP failures to the SDK's typed errors and decodes JSON / 204 / text. */
+declare class RestClient {
+    private readonly cfg;
+    constructor(cfg: ResolvedConfig);
+    request<T>(method: string, path: string, opts?: RequestOpts): Promise<T>;
+    get<T>(path: string, opts?: RequestOpts): Promise<T>;
+    post<T>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;
+    put<T>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;
+    patch<T>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;
+    del<T>(path: string, opts?: RequestOpts): Promise<T>;
+}
+/** Build a RestClient from a resolved config. */
+declare function restClient(cfg: ResolvedConfig): RestClient;
+
+/** Developer + user auth flows. `login`/`register`/`send-code`/`verify-code`
+ *  are public; `set-password`/`project-user` require the developer bearer. */
+declare class AuthApi {
+    private readonly c;
+    constructor(c: RestClient);
+    login(email: string, password: string): Promise<AuthResult>;
+    register(email: string, password: string): Promise<AuthResult>;
+    sendCode(email: string): Promise<SendCodeResult>;
+    verifyCode(email: string, code: string): Promise<VerifyCodeResult>;
+    setPassword(password: string): Promise<void>;
+    /** Exchange the developer bearer for a project-scoped user token. */
+    projectUser(projectId: string): Promise<ProjectUserResult>;
+}
+
+/** Project management (developer-scoped). */
+declare class ProjectsApi {
+    private readonly c;
+    constructor(c: RestClient);
+    list(): Promise<Project[]>;
+    create(input: CreateProjectInput): Promise<CreateProjectResult>;
+    remove(id: string): Promise<void>;
+    rotateSecret(id: string): Promise<{
+        secret: string;
+    }>;
+}
+
+/** End-user provisioning — the cloud token-exchange (project-credential scoped).
+ *
+ *  `provision` upserts a user by email, joins them to the authenticated project,
+ *  and returns a project-scoped USER JWT. This is the standard integration path:
+ *  an app's own backend (which holds the project key/secret) exchanges an
+ *  end-user identity for a short-lived user token, then hands that token to its
+ *  frontend — so the project secret never reaches the browser. Pair the result
+ *  with `createCachedUserCredential` to feed it back into an `AixClient`.
+ *
+ *  Requires a `project` credential (key/secret): the backend authenticates this
+ *  endpoint by project headers, so a user bearer alone cannot mint tokens. */
+declare class UsersApi {
+    private readonly c;
+    constructor(c: RestClient);
+    /** POST /api/users — provision (or reuse) a user and mint their token. */
+    provision(input: ProvisionUserInput): Promise<ProvisionUserResult>;
+}
+
+/** Device listing, lifecycle, and live-op proxy (all caller-scoped).
+ *  For a persistent WS command channel use `DeviceChannel.open()` instead. */
+declare class DevicesApi {
+    private readonly c;
+    constructor(c: RestClient);
+    list(): Promise<DeviceRow[]>;
+    /** Register/upsert a device (`POST /api/devices`). */
+    register(body: {
+        external_id: string;
+        kind?: string;
+        name?: string;
+        meta?: Record<string, unknown>;
+        visibility?: string;
+    }): Promise<unknown>;
+    /** Provision a virtual device (`POST /api/devices/provision`). The spec is
+     *  opaque; `node_id` (optional) routes to a specific usable node. */
+    provision(spec: ProvisionSpec): Promise<ProvisionResult>;
+    /** Brand→model identity catalog for the create-wizard's 品牌 → 机型 picker
+     *  (`GET /api/devices/profile-catalog`). Static read-only data; the chosen
+     *  `model` is passed back via `ProvisionSpec.model` to lock the fingerprint base. */
+    profileCatalog(): Promise<CatalogBrand[]>;
+    /** The single generic live-op entry point, proxied to the owning node. Any
+     *  node-supported op works here without a dedicated method; the typed helpers
+     *  below are thin wrappers over it. */
+    op<T = unknown>(deviceId: string, op: DeviceOp): Promise<T>;
+    screenshot(deviceId: string): Promise<ScreenshotResult>;
+    captureUiTree(deviceId: string): Promise<ElementNode>;
+    /** Power / lifecycle op (`POST /api/devices/:id/power`). Resolves with the
+     *  node's power JSON receipt (e.g. `{ rebooted: true }`, `{ stopped: true }`,
+     *  `{ device_id, reset: true }`) — the backend awaits the node response, so a
+     *  resolved promise means the op actually ran. Rejects (RestClient throws on
+     *  non-2xx) carry the node/backend error. */
+    power<T = Record<string, unknown>>(deviceId: string, action: PowerAction, extra?: Record<string, unknown>): Promise<T>;
+    /** Typed device-control op via the power lane (install / inject / screen-record). */
+    control(deviceId: string, op: Record<string, unknown>): Promise<unknown>;
+    installApkUrl(deviceId: string, url: string): Promise<unknown>;
+    /** Install an iOS App Store app by bundle id via the node's ipatool local
+     *  library (downloads on miss). `control` lane, fire-and-forget. */
+    installIosBundle(deviceId: string, bundleId: string): Promise<unknown>;
+    /** Search APKPure for installable apps (`GET /api/apps/search?q=`). */
+    searchApps(q: string): Promise<AppCandidate[]>;
+    /** Install by APKPure package name; the backend resolves the download url and
+     *  the node downloads + installs (apk or xapk). `POST /api/devices/:id/install-app`. */
+    installByPackage(deviceId: string, pkg: string, version?: string): Promise<unknown>;
+    /** Install an apk/xapk already uploaded to R2 (key from `filesUploadUrl`). */
+    installByKey(deviceId: string, key: string): Promise<unknown>;
+    lease(deviceId: string): Promise<unknown>;
+    release(deviceId: string): Promise<unknown>;
+    claim(deviceId: string): Promise<unknown>;
+    /** 软删除（移入回收站）—`DELETE /api/devices/:id`。在线节点即时销毁容器，
+     *  离线节点标记 pending_destroy，待节点重连对账。3 天后自动彻底清除。 */
+    delete(deviceId: string): Promise<{
+        deleted: boolean;
+        pending_destroy: boolean;
+    }>;
+    /** 列回收站内的设备（`GET /api/devices/recycle`）。 */
+    recycle(): Promise<RecycledDeviceRow[]>;
+    /** 从回收站恢复（`POST /api/devices/:id/restore`）。容器已销毁的虚拟设备会按存储 spec 重建。 */
+    restore(deviceId: string): Promise<{
+        restored: boolean;
+        rebuilt: boolean;
+        device_id?: string;
+    }>;
+    /** 彻底删除（`DELETE /api/devices/:id/purge`）。不可恢复。 */
+    purge(deviceId: string): Promise<{
+        purged: boolean;
+    }>;
+    /** 清空回收站（`DELETE /api/devices/recycle`）。彻底删除当前用户所有回收站设备。 */
+    purgeAll(): Promise<{
+        purged: number;
+    }>;
+    /** Update mutable device fields — `PATCH /api/devices/:id`.
+     *  `ios_transport` switches an iOS device's live-mirror VIDEO source
+     *  (`replaykit` device-app WebRTC, default | `iosusbadapter` host screenshot
+     *  over usbmux, driven by go-ios); control is always host-mediated and
+     *  unaffected. (Legacy value `pymobiledevice3` was renamed to `iosusbadapter`.)
+     *  `sleep_timeout_min` sets the inactivity sleep timeout (0 = disabled). */
+    update(deviceId: string, patch: {
+        tags?: string[];
+        note?: string;
+        ios_transport?: 'replaykit' | 'iosusbadapter';
+        proxy?: string;
+        sleep_timeout_min?: number;
+        meta?: Record<string, unknown>;
+    }): Promise<unknown>;
+    /** Update only the device proxy and retain a typed patch receipt. */
+    updateProxy(deviceId: string, proxy: string): Promise<ProxyPatchResult>;
+    /** Probe the device's configured proxy and report its egress IP/connectivity. */
+    probeProxy(deviceId: string): Promise<ProxyProbe>;
+    /** 休眠设备 (`POST /api/devices/:id/sleep`)。
+     *  虚拟机：截图 + 快照 + 停机（关计费）。真机：锁屏（best-effort）。 */
+    sleep(deviceId: string): Promise<{
+        sleeping: boolean;
+    }>;
+    /** 唤醒设备 (`POST /api/devices/:id/wakeup`)。
+     *  虚拟机：恢复快照 + 重建计费。真机：发唤醒键（best-effort）。 */
+    wakeup(deviceId: string): Promise<{
+        sleeping: boolean;
+    }>;
+    /** Current fingerprint + curated editable subset + dropdown choices + apply
+     *  semantics (`GET /api/devices/:id/profile`). */
+    getProfile(deviceId: string): Promise<DeviceProfileView>;
+    /** One-click regenerate the fingerprint (fresh identifiers). Optional
+     *  `model`/`android_version` constrain the catalog base. */
+    regenerateProfile(deviceId: string, opts?: {
+        model?: string;
+        android_version?: string;
+    }): Promise<SetProfileResult>;
+    /** Apply curated edits onto the current fingerprint, keeping unique
+     *  identifiers (`POST /api/devices/:id/profile`). */
+    setProfileOverrides(deviceId: string, overrides: ProfileOverrides): Promise<SetProfileResult>;
+    /** Real-device only: set which apps the LSPosed spoof module disguises (and
+     *  force-stops on re-push for immediate effect). Persisted to `meta.spec.scope_pkgs`
+     *  and pushed live with the current fingerprint (`POST /api/devices/:id/profile`). */
+    setProfileScope(deviceId: string, scopePkgs: string[]): Promise<SetProfileResult>;
+    /** Real-device only: **start** the first-time install of the LSPosed identity
+     *  layer (+ spoof module) on a rooted device (`POST /api/devices/:id/anti-detect`,
+     *  `202`). The multi-reboot install (~minutes) runs in the background — poll
+     *  `getProfile().disguise_install_status` (`installing`→`installed`/`failed`).
+     *  After install, fingerprint edits push live via `setProfileOverrides`/`regenerateProfile`. */
+    installAntiDetect(deviceId: string): Promise<InstallAntiDetectResult>;
+    /** Real-device only: toggle the disguise on/off WITHOUT uninstalling LSPosed (停用伪装).
+     *  `enabled:false` empties the on-device spoof config + relaunches scoped apps so they read
+     *  the genuine identity; `enabled:true` re-pushes the stored fingerprint. App-layer effect is
+     *  immediate; `resetprop` props (model/hardware) fully revert only on the next device reboot.
+     *  Requires the anti-detect layer installed (`POST /api/devices/:id/disguise`). */
+    setDisguiseEnabled(deviceId: string, enabled: boolean): Promise<SetDisguiseResult>;
+    /** 申请直传 R2 的 presigned PUT；返回 `key` 供后续 `filesPush` 引用。 */
+    filesUploadUrl(deviceId: string, filename: string): Promise<{
+        key: string;
+        upload_url: string;
+    }>;
+    /** 让节点从 R2 拉 `key`、adb push 到设备 `dest`；成功后后端删除 R2 对象。 */
+    filesPush(deviceId: string, key: string, dest: string): Promise<unknown>;
+    /** 让节点 adb pull 设备 `src`、PUT 到 R2；返回 presigned GET 供客户端下载。 */
+    filesPull(deviceId: string, src: string, filename: string): Promise<{
+        key: string;
+        download_url: string;
+    }>;
+    /** 开一条设备会话：让后端编排目标节点 join `/ws/signal`(节点 = offerer，建
+     *  "ctrl" DataChannel)，返回 `session_id`(SDK 据此 mint viewer token、作
+     *  answerer 建链、经 `ondatachannel` 拿到 "ctrl" 通道)。这是 DataChannel 多路
+     *  复用会话(通道 A)的握手入口;push/pull 失败时由上层回退到 R2 中转
+     *  (`filesUploadUrl` / `filesPush` / `filesPull`)。 */
+    dcSession(deviceId: string): Promise<{
+        session_id: string;
+    }>;
+}
+
+/** Which host the node runs (selects the daemon-side provider). */
+type EnvOs = 'mac' | 'win';
+/** win-only host route: WSL2 (default) or a full Hyper-V VM. */
+type EnvRoute = 'wsl2' | 'full_vm';
+type EnvAction = 'setup' | 'status' | 'teardown';
+interface EnvSetupInput {
+    /** Defaults to 'mac' (matches backend: anything ≠ "win" → macOS). */
+    os?: EnvOs;
+    /** win-only; ignored for mac. Defaults to 'wsl2' server-side. */
+    route?: EnvRoute;
+}
+interface EnvTeardownInput {
+    os?: EnvOs;
+    /** Also delete the VM/distro, not just stop it. */
+    purge?: boolean;
+}
+/** A finished env event (the terminal frame). */
+type EnvFinished = Extract<EnvEventKind, {
+    kind: 'finished';
+}>;
+/**
+ * A live env-base operation. Construct via `AixClient.nodes.env{Setup,Status,
+ * Teardown}` (or `EnvRun.start`). Subscribe with `.on('event', …)` for every
+ * progress frame and `.on('done', …)` for the terminal `finished` frame; the
+ * socket auto-closes once `finished` arrives (the stream is one-shot).
+ */
+declare class EnvRun {
+    readonly reqId: string;
+    /** Relative stream path the backend advertised, e.g. `/ws/execution/<req_id>`. */
+    readonly stream: string;
+    private readonly socket;
+    private readonly eventListeners;
+    private readonly doneListeners;
+    private doneFired;
+    private last;
+    private cursor;
+    private pollTimer;
+    private closed;
+    private pendingEvents;
+    private constructor();
+    /** Trigger an env action on an owned node and start streaming its progress. */
+    static start(cfg: AixConfig | ResolvedConfig, nodeId: string, action: EnvAction, input?: EnvSetupInput & EnvTeardownInput): Promise<EnvRun>;
+    on(event: 'event', cb: (e: EnvEventKind) => void): () => void;
+    on(event: 'done', cb: (e: EnvFinished) => void): () => void;
+    private onMessage;
+    close(): void;
+}
+/** A render-ready view of one env step, folded from the event stream. */
+interface EnvStepView {
+    index: number;
+    id: string;
+    label: string;
+    /** ok | running | skipped | missing | failed | … (daemon-reported). */
+    state: string;
+    pct: number;
+    detail?: string | null;
+}
+/** Folded summary of an env run/probe — what a progress UI renders. */
+interface EnvSummary {
+    total: number;
+    steps: EnvStepView[];
+    logs: string[];
+    finished: EnvFinished | null;
+    /** For a STATUS probe: the base is fully configured. For a SETUP run: it
+     *  completed ok. False while still running or when any step is unsatisfied. */
+    ready: boolean;
+    running: boolean;
+}
+/** Fold a stream of env events into a render-ready summary. Pure — safe to call
+ *  on every event for live UI, or once on a completed STATUS probe to decide
+ *  whether `setup` is needed (`ready`). */
+declare function summarizeEnv(events: EnvEventKind[]): EnvSummary;
+/** A setup blocker the host UI can auto-resolve (vs a generic failure to just
+ *  retry). Currently only Windows WSL2-not-installed (`WSL_UNAVAILABLE`), which
+ *  needs an elevated `wsl --install` + reboot the daemon can't do itself. */
+declare function envBlocker(finished: EnvFinished | null): 'wsl-missing' | null;
+/** Best-effort detection of the host OS the local node runs on, mapped to the
+ *  env provider id the backend expects. Returns `null` on Linux/unknown — a
+ *  Linux node is redroid-native and needs no env base, so callers skip the gate. */
+declare function detectEnvOs(): EnvOs | null;
+/** Trigger an env action and resolve once the terminal `finished` frame arrives,
+ *  returning the full event list (for `summarizeEnv`). Rejects if the trigger
+ *  POST fails. Used by headless callers (e.g. `LocalNodeController` auto-init). */
+declare function runEnvToFinish(cfg: AixConfig | ResolvedConfig, nodeId: string, action: EnvAction, input?: EnvSetupInput & EnvTeardownInput): Promise<EnvSummary>;
+
+/** Node registry (caller-scoped). A node belongs to the caller who registers it. */
+declare class NodesApi {
+    private readonly c;
+    private readonly cfg;
+    constructor(c: RestClient, cfg: ResolvedConfig);
+    list(): Promise<NodeRow[]>;
+    /** Register a node. Accepts a name or a full input ({ name, scope?, region? }). */
+    register(input: string | RegisterNodeInput): Promise<RegisterNodeResult>;
+    /** Update name/scope/region of an owned node (`PATCH /api/nodes/:id`). */
+    update(nodeId: string, patch: UpdateNodeInput): Promise<NodeRow>;
+    /** Rotate the node token, returning a fresh one (`POST /api/nodes/:id/token`). */
+    rotateToken(nodeId: string): Promise<RegisterNodeResult>;
+    /** Delete (revoke) an owned node (`DELETE /api/nodes/:id`). */
+    remove(nodeId: string): Promise<void>;
+    /** Liveness/latency probe (`POST /api/nodes/:id/probe`). Round-trips a ping to
+     *  the node; `online:false` when unreachable. */
+    probe(nodeId: string): Promise<{
+        online: boolean;
+        latency_ms?: number;
+        last_seen_at?: string | null;
+        error?: string;
+    }>;
+    /** Ask an owned node to restart itself (`POST /api/nodes/:id/restart`). */
+    restart(nodeId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Persist the only remotely configurable runtime value. The node validates
+     * the native absolute path and returns a restart-required receipt. */
+    setDataRoot(nodeId: string, dataRoot: string): Promise<SetDataRootResult>;
+    /** Submit a durable node-owned agent task (`POST /api/agent-tasks`). */
+    submitAgentTask(input: AgentTaskSubmitInput): Promise<AgentTaskSubmitResult>;
+    /** Reload a durable AgentTask, including each target's current attempt. */
+    getAgentTask(taskId: string): Promise<AgentTaskReadResult>;
+    /** Explicit read alias for callers that use CRUD-style naming. */
+    readAgentTask(taskId: string): Promise<AgentTaskReadResult>;
+    /** Stop one stable target without cancelling the other devices in its task. */
+    cancelAgentTaskTarget(taskId: string, targetId: string): Promise<void>;
+    /** Create a new immutable attempt for a failed/cancelled target. */
+    retryAgentTaskTarget(taskId: string, targetId: string): Promise<void>;
+    /** Resolve the target's current approval gate. */
+    approveAgentTaskTarget(taskId: string, targetId: string): Promise<void>;
+    /** Fetch cursor-ordered events missed while the task stream was disconnected. */
+    agentTaskEvents(taskId: string, after: number): Promise<AgentTaskEventsResult>;
+    /** Devices the node currently reports, with claim status (`POST /:id/devices/discover`). */
+    discoverDevices(nodeId: string): Promise<{
+        devices: DiscoveredDevice[];
+    }>;
+    /** Enumerate adb mDNS services on a node (`POST /api/nodes/:id/adb/scan`). */
+    adbScan(nodeId: string): Promise<AdbScanResult>;
+    /** Pair a wireless device (`POST /api/nodes/:id/adb/pair`). */
+    adbPair(nodeId: string, addr: string, code: string): Promise<unknown>;
+    /** Connect an already-paired wireless device (`POST /api/nodes/:id/adb/connect`). */
+    adbConnect(nodeId: string, addr: string): Promise<unknown>;
+    /** List connected iOS devices + their usbmux lanes (`{op:'scan'}`). */
+    iosScan(nodeId: string): Promise<IosScanResult>;
+    /** Trigger the on-device Trust dialog for a udid (`{op:'pair'}`). */
+    iosPair(nodeId: string, udid: string): Promise<unknown>;
+    /** Toggle wifi-connections for a trusted udid (`{op:'wifi'}`). */
+    iosWifi(nodeId: string, udid: string, enable: boolean): Promise<unknown>;
+    /** 节点 iOS App Store 账号状态(`{op:'account_info'}`)。 */
+    iosAccount(nodeId: string): Promise<IosAccountState>;
+    /** 登录节点 iOS 账号;`needs_2fa` 时带 `auth_code` 重试(`{op:'account_login'}`)。 */
+    iosAccountLogin(nodeId: string, body: {
+        email: string;
+        password: string;
+        auth_code?: string;
+    }): Promise<IosLoginResult>;
+    iosAccountLogout(nodeId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** App Store 搜索(`{op:'store_search'}`)。 */
+    iosStoreSearch(nodeId: string, term: string, limit?: number): Promise<{
+        apps: IosLibraryApp[];
+    }>;
+    /** 下载入节点本地库(`{op:'download'}`)。 */
+    iosDownload(nodeId: string, bundleId: string, name?: string): Promise<{
+        ok: boolean;
+        app: IosLibraryApp;
+    }>;
+    /** 节点本地 IPA 库(已下载,模版多选来源)(`{op:'apps'}`)。 */
+    iosApps(nodeId: string): Promise<{
+        apps: IosLibraryApp[];
+    }>;
+    /** Configure the redroid host base on an owned node, streaming progress.
+     *  `POST /api/nodes/:id/env/setup` → subscribe `/ws/execution/:req_id`. */
+    envSetup(nodeId: string, input?: EnvSetupInput): Promise<EnvRun>;
+    /** Probe the host base without changing it (`POST /api/nodes/:id/env/status`). */
+    envStatus(nodeId: string, input?: {
+        os?: EnvSetupInput['os'];
+    }): Promise<EnvRun>;
+    /** Stop (or `purge`) the host base (`POST /api/nodes/:id/env/teardown`). */
+    envTeardown(nodeId: string, input?: EnvTeardownInput): Promise<EnvRun>;
+}
+
+/** Device clusters (caller-scoped). */
+declare class ClustersApi {
+    private readonly c;
+    constructor(c: RestClient);
+    list(): Promise<Cluster[]>;
+    create(input: CreateClusterInput): Promise<Cluster>;
+    remove(id: string): Promise<void>;
+    setDevices(id: string, deviceIds: string[]): Promise<Cluster>;
+    run(id: string, flow: unknown): Promise<{
+        run_id: string;
+    }>;
+}
+
+/** Stored script library (caller-scoped). */
+declare class ScriptsApi {
+    private readonly c;
+    constructor(c: RestClient);
+    list(): Promise<ScriptSummary[]>;
+    get(id: string): Promise<Script>;
+    create(script: Script): Promise<ScriptSummary>;
+    update(id: string, script: Script): Promise<Script>;
+    /** Create when `script.id` is unset, else update. Returns the saved entity so
+     *  callers can capture the server-assigned `id` on first create — otherwise a
+     *  new script's id is lost and every later autosave re-creates it. */
+    save(script: Script): Promise<Script | ScriptSummary>;
+    remove(id: string): Promise<void>;
+    /** Change a script's visibility (`user` | `project` | `system`). */
+    setVisibility(id: string, visibility: string): Promise<ScriptSummary>;
+    /** Manual: ask the text LLM for a title + description, written back to the script. */
+    generateMeta(id: string): Promise<Script>;
+    /** Manual: generate a cover/icon image, store it, and write back stable URLs. */
+    generateCover(id: string): Promise<Script>;
+    duplicate(id: string): Promise<ScriptSummary>;
+}
+
+/** Device quick-action registry (caller-scoped: system built-ins + own user rows). */
+declare class ShortcutsApi {
+    private readonly c;
+    constructor(c: RestClient);
+    list(platform?: 'android' | 'ios' | 'any'): Promise<Shortcut[]>;
+    create(body: NewShortcut): Promise<Shortcut>;
+    update(id: string, body: NewShortcut): Promise<Shortcut>;
+    remove(id: string): Promise<void>;
+}
+
+/** Reusable element locators (caller-scoped). */
+declare class LocatorsApi {
+    private readonly c;
+    constructor(c: RestClient);
+    list(): Promise<Locator[]>;
+    create(input: CreateLocatorInput): Promise<Locator>;
+    remove(id: string): Promise<void>;
+}
+
+/** A fleet run is settled when the run row is terminal OR every dispatched
+ *  device reached a terminal status. Treats an empty/absent device list as
+ *  not-yet-settled so we keep polling until rows appear. */
+declare function isFleetRunTerminal(detail: FleetRunDetail): boolean;
+/** Fleet runs — the app-side execution path (caller-scoped). Distinct from
+ *  `FlowRun` (third-party webhook path via `/api/webhook/tasks`). */
+declare class FleetApi {
+    private readonly c;
+    constructor(c: RestClient);
+    start(body: FleetRunSubmit): Promise<{
+        run_id: string;
+    }>;
+    get(runId: string): Promise<FleetRunDetail>;
+    /** Poll `get(runId)` until the run is terminal (see {@link isFleetRunTerminal})
+     *  or `timeoutMs` elapses. Always resolves with the latest `FleetRunDetail`
+     *  (never rejects on timeout); inspect `isFleetRunTerminal(detail)` to tell a
+     *  finished run from a polling-cap hit. Used to turn the fire-and-forget
+     *  `start()` into a real receipt for shortcut/copy runs. */
+    waitForRun(runId: string, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<FleetRunDetail>;
+    cancel(runId: string): Promise<unknown>;
+    pause(runId: string): Promise<unknown>;
+    resume(runId: string): Promise<unknown>;
+}
+
+/** Webhook task lane (`/api/webhook/tasks`) — the third-party submit/track path,
+ *  distinct from `FleetApi` (`/api/fleet/runs`, the app's interactive run path).
+ *  Submission lives in `FlowRun`; this reads/lists/cancels + reads event history. */
+declare class TasksApi {
+    private readonly c;
+    constructor(c: RestClient);
+    /** Current status of one task (`GET /api/webhook/tasks/:id`). */
+    get(id: string): Promise<TaskStatus>;
+    /** List the caller-project's tasks, newest first (paginated, filterable). */
+    list(filter?: TaskListFilter): Promise<TaskListResult>;
+    /** Cancel a task (DB-side: not-yet-terminal targets → cancelled). */
+    cancel(id: string): Promise<{
+        task_id: string;
+        cancelled: number;
+    }>;
+    /** Pause a task: still-`pending` targets → `paused` so nodes skip them
+     *  (`pending_for_external` only pulls `pending`). In-flight targets keep
+     *  running — pause only holds back not-yet-started work. */
+    pause(id: string): Promise<{
+        task_id: string;
+        paused: number;
+    }>;
+    /** Resume a paused task: `paused` targets → `pending` so nodes pick them up again. */
+    resume(id: string): Promise<{
+        task_id: string;
+        resumed: number;
+    }>;
+    /** Persisted event history for a task, newest first. */
+    events(id: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<TaskEventsResult>;
+}
+
+/** Webhook configs + manual trigger (developer-scoped). */
+declare class WebhooksApi {
+    private readonly c;
+    constructor(c: RestClient);
+    list(): Promise<WebhookConfig[]>;
+    create(input: CreateWebhookInput): Promise<{
+        status: string;
+        id: string;
+    }>;
+    setEnabled(id: string, enabled: boolean): Promise<WebhookConfig>;
+    remove(id: string): Promise<void>;
+    trigger(eventType: string, payload: unknown): Promise<unknown>;
+}
+
+/** LLM connectivity test (developer-scoped). */
+declare class LlmApi {
+    private readonly c;
+    constructor(c: RestClient);
+    test(opts?: {
+        token?: string;
+        model?: string;
+        baseUrl?: string;
+    }): Promise<LlmTestResult>;
+}
+
+/** Platform-admin + billing + image catalog (admin-scoped, except images which
+ *  also gate on PlatformAdminAuth server-side). */
+declare class AdminApi {
+    private readonly c;
+    constructor(c: RestClient);
+    listRates(): Promise<DeviceRate[]>;
+    upsertRate(body: RateInput): Promise<DeviceRate>;
+    setRebate(projectId: string, ratio: number): Promise<unknown>;
+    setNodePlatform(nodeId: string, isPlatform: boolean): Promise<unknown>;
+    listPlans(): Promise<BillingPlan[]>;
+    createPlan(body: PlanInput): Promise<BillingPlan>;
+    usage(): Promise<DeviceUsageSession[]>;
+    ledger(): Promise<RebateLedgerRow[]>;
+    getOem(): Promise<PlatformOem>;
+    putOem(body: PlatformOemInput): Promise<PlatformOem>;
+    listImages(): Promise<ImageArtifact[]>;
+    upsertImage(body: ImageInput): Promise<ImageArtifact>;
+    setImageActive(id: string, active: boolean): Promise<ImageArtifact>;
+    deleteImage(id: string): Promise<void>;
+}
+
+/** Image catalog — caller-facing reads. Admin CRUD lives on `AdminApi`
+ *  (`/api/images`); this exposes only the slim, provisionable-version list the
+ *  device-create wizard needs. */
+declare class ImagesApi {
+    private readonly c;
+    constructor(c: RestClient);
+    /** Provisionable versions for a platform, drawn from the active catalog
+     *  (`GET /api/images/options`). Omit `platform` for all platforms. */
+    options(platform?: 'android' | 'ios'): Promise<ImageOption[]>;
+}
+
+/** 账单 / 钱包(caller 读自己的钱包;`topup` 为 admin 给指定用户钱包充值)。
+ *  钱包身份恒为 user——项目 key/secret 调用解析到 representative user 的钱包。 */
+declare class BillingApi {
+    private readonly c;
+    constructor(c: RestClient);
+    /** 当前钱包余额 + 最近流水(`GET /api/billing/balance`)。 */
+    balance(): Promise<BalanceResp>;
+    /** 名下项目订阅列表(`GET /api/billing/subscriptions`)。 */
+    subscriptions(): Promise<ProjectSubscription[]>;
+    /** 订阅一个套餐(`POST /api/billing/subscriptions`)。`plan_id` 由调用方传入。 */
+    subscribe(input: SubscribeInput): Promise<ProjectSubscription>;
+    /** 自有节点日费(`GET /api/billing/own-node-charges`)。 */
+    ownNodeCharges(): Promise<OwnNodeDailyCharge[]>;
+    /** 充值到指定用户钱包(`POST /api/admin/billing/balance/topup`,admin scope)。 */
+    topup(input: TopupInput): Promise<TopupResult>;
+}
+
+/** 用户 PAT(personal access token)管理,挂在 `/api/tokens`(caller scope)。
+ *  令牌绑用户钱包/账号身份;明文仅在 create/rotate 时返回一次。 */
+declare class ApiTokensApi {
+    private readonly c;
+    constructor(c: RestClient);
+    /** 列出名下令牌(无明文/hash;`GET /api/tokens`)。 */
+    list(): Promise<ApiTokenRow[]>;
+    /** 创建一个 PAT(`POST /api/tokens`);响应 `token` 明文仅此一次。 */
+    create(input: CreateTokenInput): Promise<CreatedToken>;
+    /** 撤销一个 PAT(`DELETE /api/tokens/:id`,204)。 */
+    revoke(id: string): Promise<void>;
+    /** 轮换一个 PAT(重签明文,旧 hash 失效;`POST /api/tokens/:id/rotate`)。 */
+    rotate(id: string): Promise<CreatedToken>;
+}
+
+/** 用户级应用模版(`/api/app-templates`,caller-scoped)。 */
+declare class AppTemplatesApi {
+    private readonly c;
+    constructor(c: RestClient);
+    list(platform?: 'android' | 'ios'): Promise<AppTemplate[]>;
+    create(body: NewAppTemplate): Promise<AppTemplate>;
+    update(id: string, body: NewAppTemplate): Promise<AppTemplate>;
+    remove(id: string): Promise<void>;
+}
+
+/** One-stop typed REST facade over the whole backend `/api/*` surface.
+ *  Build once from an `AixConfig` and share it across the app. */
+declare class AixClient {
+    readonly cfg: ResolvedConfig;
+    readonly http: RestClient;
+    readonly auth: AuthApi;
+    readonly projects: ProjectsApi;
+    readonly users: UsersApi;
+    readonly devices: DevicesApi;
+    readonly nodes: NodesApi;
+    readonly clusters: ClustersApi;
+    readonly scripts: ScriptsApi;
+    readonly shortcuts: ShortcutsApi;
+    readonly locators: LocatorsApi;
+    readonly fleet: FleetApi;
+    readonly tasks: TasksApi;
+    readonly webhooks: WebhooksApi;
+    readonly llm: LlmApi;
+    readonly admin: AdminApi;
+    readonly images: ImagesApi;
+    readonly billing: BillingApi;
+    readonly tokens: ApiTokensApi;
+    readonly appTemplates: AppTemplatesApi;
+    /** Desktop local-node controller — present only when `cfg.localNode` is set
+     *  (Tauri/Electron). `ensure()` binds this machine as the caller's node and
+     *  `listDevices()`/`onDevices()` surface its connected devices. */
+    readonly localNode?: LocalNodeController;
+    constructor(cfg: AixConfig | ResolvedConfig);
+    /**
+     * 打开一条设备会话(DataChannel 多路复用):文件管理 + 终端 + 传输 + 通用流/
+     * 端口转发。返回的 `DeviceSession` 用完请 `close()`。
+     *
+     * 解耦说明:`device-session.ts` 静态依赖本文件(`AixClient`),为避免模块求值期
+     * 循环依赖,这里用**动态 import** 拿 `DeviceSession`;并把 `this.cfg`
+     * (ResolvedConfig)而非 `this` 传给 `open`(`open` 内部用 cfg + 自建 DevicesApi
+     * 即可,不必回依赖 client 实例)。
+     */
+    deviceSession(deviceId: string, opts?: {
+        dcTimeoutMs?: number;
+    }): Promise<DeviceSession>;
+}
+declare function createClient(cfg: AixConfig | ResolvedConfig): AixClient;
+
+/** Runtime status of the locally-running node process, reported by the host. */
+interface NodeHostStatus {
+    running: boolean;
+    hasToken: boolean;
+    nodeId: string | null;
+}
+/** The host-app's adapter for managing the local `aixautobot node` process.
+ *  The SDK owns the *policy* (which node, which token); the host owns the
+ *  *mechanism* (spawning the process, persisting the token). Implement this for
+ *  Tauri (`invoke`), Electron (`child_process`), or any runtime — see examples. */
+interface NodeHost {
+    status(): Promise<NodeHostStatus>;
+    start(opts: {
+        token: string | null;
+        backendWs: string;
+        requireSdkUpdate?: boolean;
+    }): Promise<void>;
+    stop(): Promise<void>;
+}
+interface LocalNodeOptions {
+    host: NodeHost;
+    /** Require a foreground SDK update check before starting the host process. */
+    requireSdkUpdate?: boolean;
+    /** Run `ensure()` automatically once the client is constructed (best-effort). */
+    auto?: boolean;
+    /** Node scope to create/reuse. Defaults to `'personal'`. */
+    scope?: NodeScope;
+    /** Name for a newly-created node. Defaults to `'desktop-node'`. */
+    nameHint?: string;
+    /** Override the backend ws URL handed to the host. Defaults to baseUrl→ws[s]. */
+    backendWs?: string;
+    /** Poll interval (ms) for `onDevices`. Defaults to 4000. */
+    pollMs?: number;
+    /** Redroid host-base (env) initialization on the bound node:
+     *  - `'manual'` (default): never auto-init. A UI app drives it via the
+     *    `useEnvGate` hook + `<EnvInitDialog>` so the user confirms (and watches
+     *    the ~GB download).
+     *  - `'auto'`: a HEADLESS/server consumer with no UI — after binding the node,
+     *    probe `env/status` and, if the base is missing, run `env/setup` to
+     *    completion automatically (no confirmation). Best-effort; never throws. */
+    envInit?: 'manual' | 'auto';
+    /** Host OS for env init (selects mac-env vs win-env). Defaults to
+     *  `detectEnvOs()`; `null`/Linux skips env init (redroid is native there). */
+    envOs?: EnvOs | null;
+    /** win-only env route handed to `env/setup` (`'wsl2'` default server-side). */
+    envRoute?: EnvRoute;
+}
+/** Drives the local node lifecycle for a desktop app: ensure a personal node
+ *  owned by the signed-in caller exists, mint/rotate a runnable token, hand it
+ *  to the host to spawn, and surface THAT node's connected devices — so a
+ *  Tauri/Electron consumer auto-lists local devices instead of adding manually.
+ *
+ *  Ported from the in-house desktop `ensureLocalNode()` so any SDK consumer gets
+ *  the same behaviour. Best-effort: `ensure()` never throws into the caller. */
+declare class LocalNodeController {
+    private readonly client;
+    private readonly opts;
+    /** The node id this machine is bound to once `ensure()` has run. */
+    nodeId: string | null;
+    /** Last best-effort failure captured by `ensure()`, for host UIs that want to surface it. */
+    lastError: unknown;
+    private startHost;
+    constructor(client: AixClient, opts: LocalNodeOptions);
+    private get scope();
+    private get backendWs();
+    /** Ensure THIS machine runs as its OWN node owned by the signed-in caller,
+     *  starting it via the host. The node is keyed by machine name (`nameHint`), so
+     *  each of the user's machines gets a distinct node (no shared-node churn).
+     *  Idempotent: keeps a running match, else restarts the persisted/rotated node,
+     *  else registers one named after the machine. Returns the bound node id, or
+     *  null on failure (best-effort). */
+    ensure(): Promise<string | null>;
+    /** Record the bound node id and, in headless `'auto'` mode, ensure its redroid
+     *  host base is configured before returning. Always returns the id. */
+    private bind;
+    /** Resolve the env OS: explicit option wins, else auto-detect; `null` (Linux/
+     *  unknown) means "no base needed" and the gate is skipped. */
+    get envOs(): EnvOs | null;
+    /** HEADLESS auto env-init: probe `env/status` on the bound node and, if the
+     *  redroid base is missing, run `env/setup` to completion — no confirmation.
+     *  No-op unless `envInit: 'auto'` and the OS needs a base. Best-effort. */
+    private maybeAutoEnv;
+    /** Run an env action on the bound node to completion. For `'status'` returns
+     *  whether the base is already ready; for `'setup'` returns whether it ok'd. */
+    private runEnv;
+    /** Stop the local node (e.g. on logout). Best-effort. */
+    stop(): Promise<void>;
+    /** Devices connected to THIS local node — `devices.list()` filtered by node id.
+     *  Empty until `ensure()` has bound `nodeId`. */
+    listDevices(): Promise<DeviceRow[]>;
+    /** Subscribe to this node's device list (polled). Fires immediately, then every
+     *  `pollMs`. Returns an unsubscribe fn. */
+    onDevices(cb: (devices: DeviceRow[]) => void): () => void;
+}
+
+interface IWebSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: unknown) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+}
+type WebSocketFactory = (url: string) => IWebSocket;
+/** Minimal RTCPeerConnection surface MirrorSession + DeviceSession depend on
+ *  (injectable for tests). Both are **answerer-only**: the node is the offerer
+ *  (owns the video track / "control" / "ctrl" DataChannel and createOffer), so the
+ *  client just createAnswer + setRemoteDescription(offer) + ondatachannel. */
+interface IRTCPeerConnection {
+    createAnswer(): Promise<{
+        type: string;
+        sdp?: string;
+    }>;
+    setLocalDescription(desc?: {
+        type: string;
+        sdp?: string;
+    }): Promise<void>;
+    setRemoteDescription(desc: {
+        type: string;
+        sdp?: string;
+    }): Promise<void>;
+    addIceCandidate(candidate: unknown): Promise<void>;
+    close(): void;
+    ontrack: ((ev: {
+        streams: ReadonlyArray<MediaStream>;
+        track?: unknown;
+        receiver?: {
+            playoutDelayHint?: number;
+        };
+    }) => void) | null;
+    onicecandidate: ((ev: {
+        candidate: unknown;
+    }) => void) | null;
+    ondatachannel: ((ev: {
+        channel: IRTCDataChannel;
+    }) => void) | null;
+    onconnectionstatechange: (() => void) | null;
+    connectionState: string;
+    /** 主动建一条命名 DataChannel(offerer 路径,当前 SDK 不再走)。 */
+    createDataChannel?(label: string, init?: unknown): IRTCDataChannel;
+    /** 生成 offer(offerer 路径,当前 SDK 不再走)。 */
+    createOffer?(): Promise<{
+        type: string;
+        sdp?: string;
+    }>;
+    /** WebRTC 连接统计(浏览器 RTCStatsReport,Map-like)。可选:mock 可不实现,
+     *  消费方(自动测速选档)拿不到时降级为 null。 */
+    getStats?(): Promise<unknown>;
+}
+interface IRTCDataChannel {
+    readonly readyState: string;
+    readonly label?: string;
+    /** Send text (mirror/control + device-session path) — or binary (后续二进制帧优化).
+     *  接受 string|ArrayBuffer|ArrayBufferView 向后兼容:当前 DeviceSession 协议为
+     *  JSON 文本帧,MirrorSession 也只传 string。 */
+    send(data: string | ArrayBuffer | ArrayBufferView): void;
+    close(): void;
+    onopen: (() => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: (() => void) | null;
+    /** 待发送字节数,用于背压判断。 */
+    readonly bufferedAmount?: number;
+    /** 低水位阈值;降到此值时触发 onbufferedamountlow。 */
+    bufferedAmountLowThreshold?: number;
+    /** bufferedAmount 回落到低水位的回调,用于背压续传。 */
+    onbufferedamountlow?: (() => void) | null;
+    /** 接收二进制类型("arraybuffer"),文件通道设为 arraybuffer。 */
+    binaryType?: string;
+}
+type RTCFactory = (config: {
+    iceServers?: unknown[];
+}) => IRTCPeerConnection;
+interface AixConfig {
+    /** Backend base URL, e.g. "https://api.example.com". */
+    baseUrl: string;
+    /** Legacy single-user-token path. Equivalent to `auth: { kind: 'user', getToken }`.
+     *  Optional now that `auth` exists — provide this OR `auth` (or both). */
+    getAuthToken?: () => string | Promise<string>;
+    /** One or more credentials (project key/secret, user JWT, developer JWT).
+     *  The resource layer selects the right one per request scope. */
+    auth?: Credential | Credential[];
+    /** Override fetch (Tauri / tests). Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+    /** Override WebSocket construction (tests). Defaults to global WebSocket. */
+    wsFactory?: WebSocketFactory;
+    /** Override RTCPeerConnection construction (tests / jsdom). Defaults to global RTCPeerConnection. */
+    rtcFactory?: RTCFactory;
+    /** Desktop (Tauri/Electron) local-node integration. When set, `client.localNode`
+     *  is available; `auto:true` runs `ensure()` on construction (best-effort). */
+    localNode?: LocalNodeOptions;
+}
+interface ResolvedConfig {
+    baseUrl: string;
+    /** Resolved user-bearer accessor (kept for the legacy device/mirror/flow
+     *  paths). Throws if no user credential is configured. */
+    getAuthToken: () => string | Promise<string>;
+    /** Multi-credential, scope-aware header provider for the resource layer. */
+    auth: AuthProvider;
+    fetchFn: typeof fetch;
+    wsFactory: WebSocketFactory;
+    rtcFactory: RTCFactory;
+    /** Desktop local-node integration (passed through from AixConfig). */
+    localNode?: LocalNodeOptions;
+}
+declare function joinUrl(base: string, path: string): string;
+/** Convert the backend base (http[s]) to the generic `/ws/execution/:id` relay.
+ * This is intentionally only URL construction; callers must use
+ * `executionWsTicketUrl` before opening a browser WebSocket. */
+declare function executionWsUrl(baseUrl: string, id: string): string;
+/** Cursor-ordered generic execution event retained by the backend stream ledger. */
+interface ExecutionStreamEvent {
+    cursor: number;
+    run_id: string;
+    target_id?: string;
+    attempt_id?: string;
+    device_id?: string;
+    event: unknown;
+}
+interface ExecutionStreamEventsResult {
+    events: ExecutionStreamEvent[];
+    next_cursor?: number;
+    has_more?: boolean;
+}
+/** Fetch a durable execution-stream page for live cursor-gap recovery. */
+declare function executionStreamEventsAfter(cfg: ResolvedConfig, id: string, after: number, limit?: number): Promise<ExecutionStreamEventsResult>;
+/**
+ * Mint a short-lived, single-use execution WebSocket ticket through an
+ * authenticated HTTP request. `ReconnectingSocket.urlProvider` must call this
+ * on every connection attempt: tickets are deliberately not reusable and no
+ * long-lived bearer credential is ever put in the WebSocket URL.
+ */
+declare function executionWsTicketUrl(cfg: ResolvedConfig, id: string, after?: number): Promise<string>;
+declare function authHeader(getAuthToken: () => string | Promise<string>): Promise<{
+    Authorization: string;
+}>;
+declare function resolveConfig(cfg: AixConfig): ResolvedConfig;
+
+export { type PullResult as $, type AixConfig as A, BillingApi as B, type CachedUserCredentialOpts as C, type DcStream as D, type EnvOs as E, type FridaEventFrame as F, type ExecutionStreamEventsResult as G, type FileEntry as H, FleetApi as I, type IRTCDataChannel as J, type IRTCPeerConnection as K, type IWebSocket as L, ImagesApi as M, type IncomingFrame as N, type OutgoingFrame as O, LlmApi as P, LocalNodeController as Q, type ResolvedConfig as R, type ScriptletEventFrame as S, type LocalNodeOptions as T, LocatorsApi as U, type NodeHost as V, type WebSocketFactory as W, type NodeHostStatus as X, NodesApi as Y, type ProgressFn as Z, ProjectsApi as _, type RunEventKind as a, type PushInput as a0, type RTCFactory as a1, type RequestOpts as a2, RestClient as a3, type RetFrame as a4, type Scope as a5, ScriptsApi as a6, ShortcutsApi as a7, type StreamTarget as a8, TasksApi as a9, restClient as aA, runEnvToFinish as aB, summarizeEnv as aC, type TransferOpts as aa, type TransferProgress as ab, type TransferResult as ac, UsersApi as ad, WebhooksApi as ae, authHeader as af, buildAuthProvider as ag, createCachedUserCredential as ah, createClient as ai, detectEnvOs as aj, envBlocker as ak, executionStreamEventsAfter as al, executionWsTicketUrl as am, executionWsUrl as an, isEnvEventFrame as ao, isExecutionFrame as ap, isFleetRunTerminal as aq, isFridaEventFrame as ar, isRetFrame as as, isScriptletEventFrame as at, isStatusFrame as au, joinUrl as av, parseIncoming as aw, pullFile as ax, pushFile as ay, resolveConfig as az, type StatusFrame as b, AixClient as c, type EnvRoute as d, type EnvEventKind as e, AdminApi as f, ApiTokensApi as g, AuthApi as h, type AuthProvider as i, ClustersApi as j, type Credential as k, type DeviceReq as l, type DeviceResp as m, DeviceSession as n, DevicesApi as o, type EnvAction as p, type EnvFinished as q, type EnvResultDto as r, EnvRun as s, type EnvSetupInput as t, type EnvStepMeta as u, type EnvStepView as v, type EnvSummary as w, type EnvTeardownInput as x, type ExecutionFrame as y, type ExecutionStreamEvent as z };