@mearl/client 2.0.0

package/dist/fileRefs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Payload 文件引用解析（@ 前缀，仅顶层字段）
+ *
+ * 约定：payload 的**顶层字段**若是以 `@` 开头的字符串，`@` 之后视为文件路径，
+ * 发送前会被替换为该文件内容：
+ * - 默认按 JSON 解析；解析失败则按原始文本注入（适配脚本 / HTML / 纯文本 body）。
+ * - **找不到 / 读不到该文件时，原样保留这个字符串**（不报错），因此 `@xxx` 这类
+ *   非文件路径的普通值不会被误伤。
+ *
+ * 用途：把大体积字段（mock 响应体、send_request 的 body、page_eval 的 script 等）
+ * 放到本地文件，调用方只传 `"@/abs/path"`，避免把整段内容塞进上下文。
+ *
+ * 解析在 client `invoke` 中统一执行，对所有 action 生效；路径按运行进程 cwd 解析，
+ * 建议传绝对路径。仅作用于顶层字段，不递归嵌套。
+ */
+/**
+ * 解析 payload 顶层字段中的 `@<path>` 文件引用。返回新对象，不修改入参。
+ * 非对象入参原样返回。
+ */
+export declare function resolveFileRefs(data: Record<string, any>): Record<string, any>;

package/dist/fileRefs.js

@@ -0,0 +1,52 @@
+/**
+ * Payload 文件引用解析（@ 前缀，仅顶层字段）
+ *
+ * 约定：payload 的**顶层字段**若是以 `@` 开头的字符串，`@` 之后视为文件路径，
+ * 发送前会被替换为该文件内容：
+ * - 默认按 JSON 解析；解析失败则按原始文本注入（适配脚本 / HTML / 纯文本 body）。
+ * - **找不到 / 读不到该文件时，原样保留这个字符串**（不报错），因此 `@xxx` 这类
+ *   非文件路径的普通值不会被误伤。
+ *
+ * 用途：把大体积字段（mock 响应体、send_request 的 body、page_eval 的 script 等）
+ * 放到本地文件，调用方只传 `"@/abs/path"`，避免把整段内容塞进上下文。
+ *
+ * 解析在 client `invoke` 中统一执行，对所有 action 生效；路径按运行进程 cwd 解析，
+ * 建议传绝对路径。仅作用于顶层字段，不递归嵌套。
+ */
+import fs from 'node:fs';
+const FILE_REF_PREFIX = '@';
+function resolveValue(value) {
+    if (typeof value !== 'string' || !value.startsWith(FILE_REF_PREFIX))
+        return value;
+    const filePath = value.slice(FILE_REF_PREFIX.length);
+    if (!filePath)
+        return value;
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        // 找不到 / 读不到文件：原样保留该字符串
+        return value;
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        // 非 JSON 文件按原始文本注入
+        return content;
+    }
+}
+/**
+ * 解析 payload 顶层字段中的 `@<path>` 文件引用。返回新对象，不修改入参。
+ * 非对象入参原样返回。
+ */
+export function resolveFileRefs(data) {
+    if (data === null || typeof data !== 'object' || Array.isArray(data))
+        return data;
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        out[key] = resolveValue(value);
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,402 @@
+/**
+ * @mearl/client — Mearl Socket Client SDK
+ *
+ * 通过 Unix Domain Socket 与 Chrome Extension 的 native host 通信，
+ * 提供类型安全的具名方法和通用的 invoke 底层方法。
+ *
+ * @example
+ * ```ts
+ * import * as client from '@mearl/client';
+ *
+ * // 具名方法（类型安全）
+ * const result = await client.sendRequest({ url: 'https://...', method: 'GET', withCookies: true });
+ *
+ * // 底层通用方法（灵活扩展）
+ * const data = await client.invoke('send_request', { url: '...' });
+ * ```
+ */
+export { invoke } from './socket.js';
+export type { InvokeOptions } from './socket.js';
+export interface GetRequestsParams {
+    tabId?: number;
+    count?: number;
+    filter?: string;
+    since?: number;
+    includeBody?: boolean;
+    includeHeaders?: boolean;
+    maxBodySize?: number;
+    fields?: string[];
+    keysOnly?: boolean;
+    source?: 'mtop' | 'requests';
+}
+export declare function getRequests(params?: GetRequestsParams): Promise<any>;
+export interface GetLogsParams {
+    level?: 'log' | 'warn' | 'error' | 'info' | 'all';
+    since?: number;
+    limit?: number;
+    filter?: string;
+}
+export declare function getLogs(params?: GetLogsParams): Promise<any>;
+export interface GetEventsParams {
+    source?: 'rum' | 'aplus' | 'all';
+    event_type?: string;
+    filter?: string;
+    since?: number;
+    limit?: number;
+}
+export declare function getEvents(params?: GetEventsParams): Promise<any>;
+export interface SetMockParams {
+    apiName: string;
+    mockData?: any;
+    fields?: Array<{
+        path: string;
+        value: any;
+    }>;
+    enabled?: boolean;
+    /** 完整响应时长（毫秒）：mock 的总耗时，绕过真实服务器精确控制 */
+    duration?: number;
+    /** 请求 query/body 字段子集匹配；$index 从 0 开始指定调用顺序 */
+    conditions?: Record<string, any>;
+}
+export declare function setMock(params: SetMockParams): Promise<any>;
+export interface GetMocksParams {
+    apiName?: string;
+}
+export declare function getMocks(params?: GetMocksParams): Promise<any>;
+export interface GetApiSchemaParams {
+    api: string;
+    version?: string;
+    fields?: ('schema' | 'hsf')[];
+}
+export declare function getApiSchema(params: GetApiSchemaParams): Promise<any>;
+export interface SendRequestParams {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    body?: any;
+    withCookies?: boolean;
+    cookieDomain?: string;
+    responseType?: 'json' | 'text' | 'auto';
+    timeout?: number;
+}
+export declare function sendRequest(params: SendRequestParams): Promise<any>;
+export interface SendMtopRequestParams {
+    api: string;
+    data?: any;
+    version?: string;
+    method?: string;
+    appKey?: string;
+    env?: string;
+    timeout?: number;
+}
+export declare function sendMtopRequest(params: SendMtopRequestParams): Promise<any>;
+export interface TdbankAccountParams {
+    operation?: 'current' | 'list' | 'switch' | 'borrow';
+    pageIndex?: number;
+    refresh?: boolean;
+    query?: string;
+    accountId?: string | number;
+    havanaId?: string | number;
+    site?: string | number;
+    tabId?: number;
+}
+export declare function tdbankAccount(params?: TdbankAccountParams): Promise<any>;
+export type BrowserStatus = 'connected' | 'running_disconnected' | 'stopped';
+export interface BrowserInfoBase {
+    browserId: string;
+    name: string;
+    status: BrowserStatus;
+    extensionVersion?: string;
+    nativeHostVersion?: string;
+    transport?: 'extension' | 'cdp';
+}
+export interface RegularBrowserInfo extends BrowserInfoBase {
+    type: 'regular';
+    status: 'connected';
+}
+export interface ManagedBrowserAccount {
+    accountId?: string;
+    loginId?: string;
+    nickname: string;
+}
+export interface ManagedBrowserInfo extends BrowserInfoBase {
+    type: 'managed';
+    headless: boolean;
+    persistent: boolean;
+    cdpPort: number;
+    createdAt: string;
+    account?: ManagedBrowserAccount;
+    copiedCookies?: {
+        domains: string[];
+        count: number;
+    };
+}
+export type BrowserInfo = RegularBrowserInfo | ManagedBrowserInfo;
+export interface BrowserListResult {
+    count: number;
+    connectedCount: number;
+    defaultBrowserId: string | null;
+    browsers: BrowserInfo[];
+}
+export declare function browserList(): Promise<BrowserListResult>;
+export interface SelectBrowserParams {
+    browser?: string;
+}
+export interface SelectBrowserResult {
+    selected: {
+        browserId: string;
+        name: string;
+    } | null;
+    note?: string;
+}
+export declare function selectBrowser(params?: SelectBrowserParams): Promise<SelectBrowserResult>;
+export interface BrowserLaunchParams {
+    name: string;
+    headless?: boolean;
+    userAgentMode?: 'default' | 'desktop';
+    persistent?: boolean;
+    executablePath?: string;
+    url?: string;
+    accountId?: string | number;
+    havanaId?: string | number;
+    site?: string | number;
+    query?: string;
+    tabId?: number;
+    copyCookieDomains?: string[];
+}
+export declare function browserLaunch(params: BrowserLaunchParams): Promise<any>;
+export interface BrowserCloseParams {
+    browser: string;
+    deleteProfile?: boolean;
+}
+export declare function browserClose(params: BrowserCloseParams): Promise<any>;
+export interface SetRuleParams {
+    actionType: 'redirect' | 'block' | 'allow' | 'upgradeScheme' | 'modifyHeaders';
+    filter: string;
+    redirectUrl?: string;
+    requestHeaders?: Array<{
+        header: string;
+        operation: 'set' | 'append' | 'remove';
+        value?: string;
+    }>;
+    responseHeaders?: Array<{
+        header: string;
+        operation: 'set' | 'append' | 'remove';
+        value?: string;
+    }>;
+    initiatorDomains?: string;
+    resourceTypes?: string[];
+    priority?: number;
+    description?: string;
+}
+export declare function setRule(params: SetRuleParams): Promise<any>;
+/** 返回当前存储的全部请求规则（含 Options 面板配置的），字段结构与 set_rule 入参对齐。 */
+export declare function getRules(): Promise<{
+    enabled: boolean;
+    rules: Array<Record<string, any>>;
+}>;
+export interface PageScreenshotParams {
+    tabId: number;
+    selector?: string;
+    format?: 'png' | 'jpeg';
+    quality?: number;
+}
+export declare function pageScreenshot(params: PageScreenshotParams): Promise<any>;
+export interface PageSelectedElementParams {
+    tabId: number;
+    includeOuterHTML?: boolean;
+    includeScreenshot?: boolean;
+}
+export declare function pageSelectedElement(params: PageSelectedElementParams): Promise<any>;
+export interface TabOpenParams {
+    url: string;
+    active?: boolean;
+    /** 打开前先关闭 Agent 受控的已有标签页。默认 false */
+    closeExisting?: boolean;
+    /** 是否复用匹配标签页。默认 never，保持始终新开的兼容行为。 */
+    reuse?: 'never' | 'prefer' | 'require';
+    /** 复用标签页时的 URL 匹配规则。 */
+    match?: {
+        /** 完整 URL glob，`*` 匹配任意字符；省略时匹配 url。 */
+        urlPattern?: string;
+        ignoreSearch?: boolean;
+        ignoreHash?: boolean;
+        onMultiple?: 'error' | 'first';
+    };
+    /** active 新标签页关闭后，恢复打开前的活动标签页。默认 false。 */
+    restoreFocusOnClose?: boolean;
+    /**
+     * 开 tab 即进入移动端模拟态（视口/UA/触摸），在导航前生效，页面首屏即移动态、无需 reload。
+     * 等价于随后立即调用 set_device_emulation，但省一次整页加载并避开桌面态首屏的 UA 判端跳转。
+     */
+    emulation?: EmulationOptions;
+    /** 把标签页加入指定标题的分组（同窗口同名分组存在则加入，否则新建）。仅扩展模式支持。 */
+    group?: string;
+}
+export declare function tabOpen(params: TabOpenParams): Promise<any>;
+export interface TabCloseParams {
+    tabId: number;
+}
+export declare function tabClose(params: TabCloseParams): Promise<any>;
+export declare function tabList(): Promise<any>;
+/**
+ * 页面交互动作（click/type/hover/scroll/press/upload）默认内置观察：
+ * 同一次调用内执行动作并等待异步稳定，返回 `{ action, observation }`。
+ * 传 `observe: false` 关闭观察，仅执行裸动作并直接返回其结果。
+ */
+export interface PageObserveOptions {
+    quietMs?: number;
+    firstChangeTimeoutMs?: number;
+    timeoutMs?: number;
+    navigationGraceMs?: number;
+    navigationTimeoutMs?: number;
+    networkIdleMs?: number;
+    contentReadyAfterMs?: number;
+}
+export interface PageClickParams {
+    tabId: number;
+    /** 原生 CSS 选择器或 @eN snapshot ref。selector/text/point 三选一。 */
+    selector?: string;
+    /** 按可见文本（AX name）定位；可配合 role/exact 消歧。 */
+    text?: string;
+    /** 按视口坐标点击（CSS 像素）。 */
+    point?: {
+        x: number;
+        y: number;
+    };
+    /** 配合 text，按 AX role 过滤。 */
+    role?: string;
+    /** 配合 text，默认 true（精确匹配），false 时子串匹配。 */
+    exact?: boolean;
+    /**
+     * 点击方式。默认 'js'（对 selector / @ref 调用 el.click()）。
+     * 'cdp' 走真实 mouse/touch 事件；text 与 point 始终用 CDP。
+     */
+    clickType?: 'js' | 'cdp';
+    /** 观察选项；传 false 关闭内置观察。 */
+    observe?: PageObserveOptions | false;
+}
+export declare function pageClick(params: PageClickParams): Promise<any>;
+export interface PageTypeParams {
+    tabId: number;
+    selector: string;
+    text: string;
+    clearFirst?: boolean;
+    /** 观察选项；传 false 关闭内置观察。 */
+    observe?: PageObserveOptions | false;
+}
+export declare function pageType(params: PageTypeParams): Promise<any>;
+export interface PageScrollParams {
+    tabId: number;
+    direction: string;
+    distance?: number;
+    /** 观察选项；传 false 关闭内置观察。 */
+    observe?: PageObserveOptions | false;
+}
+export declare function pageScroll(params: PageScrollParams): Promise<any>;
+export interface PageHoverParams {
+    tabId: number;
+    selector: string;
+    /** 观察选项；传 false 关闭内置观察。 */
+    observe?: PageObserveOptions | false;
+}
+export declare function pageHover(params: PageHoverParams): Promise<any>;
+export interface PageEvalParams {
+    tabId: number;
+    expression: string;
+    frameId?: string;
+    awaitPromise?: boolean;
+}
+export declare function pageEval(params: PageEvalParams): Promise<any>;
+export interface PageSnapshotParams {
+    tabId: number;
+    depth?: number;
+    maxChars?: number;
+    maxNodes?: number;
+    rootSelector?: string;
+    mode?: 'full' | 'interactive' | 'viewport';
+}
+export declare function pageSnapshot(params: PageSnapshotParams): Promise<any>;
+export interface PagePressParams {
+    tabId: number;
+    key: string;
+    modifiers?: string[];
+    /** 观察选项；传 false 关闭内置观察。 */
+    observe?: PageObserveOptions | false;
+}
+export declare function pagePress(params: PagePressParams): Promise<any>;
+export interface PageWaitParams {
+    tabId: number;
+    time?: number;
+    selector?: string;
+    /** 在页面主执行上下文中轮询，表达式返回 truthy 时结束。 */
+    condition?: string;
+    timeout?: number;
+    interval?: number;
+}
+export declare function pageWait(params: PageWaitParams): Promise<any>;
+export interface PageNavigateParams {
+    tabId: number;
+    /** 要导航到的 URL；refresh 为 true 时可省略。 */
+    url?: string;
+    /** 为 true 时直接重新加载当前页面（忽略 url），用于刷新页面。 */
+    refresh?: boolean;
+}
+export declare function pageNavigate(params: PageNavigateParams): Promise<any>;
+export interface PageUploadParams {
+    tabId: number;
+    selector: string;
+    filePaths: string[];
+    /** 观察选项；传 false 关闭内置观察。 */
+    observe?: PageObserveOptions | false;
+}
+export declare function pageUpload(params: PageUploadParams): Promise<any>;
+export interface PageFramesParams {
+    tabId: number;
+}
+export declare function pageFrames(params: PageFramesParams): Promise<any>;
+export type DevicePresetName = 'iphone-15-pro' | 'iphone-se' | 'pixel-8' | 'ipad-mini' | 'galaxy-s23';
+/**
+ * 移动端模拟入参（不含 enabled/tabId/reload）。tab_open 的 emulation 字段与
+ * set_device_emulation 复用同一套字段，规则一致。
+ */
+export interface EmulationOptions {
+    preset?: DevicePresetName;
+    width?: number;
+    height?: number;
+    deviceScaleFactor?: number;
+    mobile?: boolean;
+    userAgent?: string;
+    orientation?: 'portrait' | 'landscape';
+    touch?: boolean;
+}
+export interface SetDeviceEmulationParams extends EmulationOptions {
+    tabId: number;
+    enabled: boolean;
+    reload?: boolean;
+}
+export declare function setDeviceEmulation(params: SetDeviceEmulationParams): Promise<any>;
+export interface SetTimezoneParams {
+    tabId: number;
+    /** IANA timezone identifier, or an empty string to restore the browser default. */
+    timezone: string;
+}
+export interface SetTimezoneResult {
+    enabled: boolean;
+    timezone: string | null;
+}
+export declare function setTimezone(params: SetTimezoneParams): Promise<SetTimezoneResult>;
+export interface GetUserInfoParams {
+    detail?: boolean;
+}
+export declare function getUserInfo(params?: GetUserInfoParams): Promise<any>;
+export interface ActionStep {
+    action: string;
+    data?: Record<string, any>;
+}
+export interface RunActionsParams {
+    actions: ActionStep[];
+    tabId: number;
+}
+export declare function runActions(params: RunActionsParams): Promise<any>;

package/dist/index.js

@@ -0,0 +1,125 @@
+/**
+ * @mearl/client — Mearl Socket Client SDK
+ *
+ * 通过 Unix Domain Socket 与 Chrome Extension 的 native host 通信，
+ * 提供类型安全的具名方法和通用的 invoke 底层方法。
+ *
+ * @example
+ * ```ts
+ * import * as client from '@mearl/client';
+ *
+ * // 具名方法（类型安全）
+ * const result = await client.sendRequest({ url: 'https://...', method: 'GET', withCookies: true });
+ *
+ * // 底层通用方法（灵活扩展）
+ * const data = await client.invoke('send_request', { url: '...' });
+ * ```
+ */
+export { invoke } from './socket.js';
+import { invoke } from './socket.js';
+export function getRequests(params = {}) {
+    return invoke('get_requests', params);
+}
+export function getLogs(params = {}) {
+    return invoke('get_logs', params);
+}
+export function getEvents(params = {}) {
+    return invoke('get_events', params);
+}
+export function setMock(params) {
+    return invoke('set_mock', params);
+}
+export function getMocks(params = {}) {
+    return invoke('get_mocks', params);
+}
+export function getApiSchema(params) {
+    return invoke('get_api_schema', params);
+}
+export function sendRequest(params) {
+    return invoke('send_request', params);
+}
+export function sendMtopRequest(params) {
+    return invoke('send_mtop_request', params);
+}
+export function tdbankAccount(params = {}) {
+    return invoke('tdbank_account', params);
+}
+export function browserList() {
+    return invoke('browser_list', {});
+}
+export function selectBrowser(params = {}) {
+    return invoke('browser_select_browser', params);
+}
+export function browserLaunch(params) {
+    return invoke('browser_launch', params);
+}
+export function browserClose(params) {
+    return invoke('browser_close', params);
+}
+export function setRule(params) {
+    return invoke('set_rule', params);
+}
+/** 返回当前存储的全部请求规则（含 Options 面板配置的），字段结构与 set_rule 入参对齐。 */
+export function getRules() {
+    return invoke('get_rules', {});
+}
+export function pageScreenshot(params) {
+    return invoke('page_screenshot', params);
+}
+export function pageSelectedElement(params) {
+    return invoke('page_selected_element', params);
+}
+export function tabOpen(params) {
+    return invoke('tab_open', params);
+}
+export function tabClose(params) {
+    return invoke('tab_close', params);
+}
+export function tabList() {
+    return invoke('tab_list', {});
+}
+export function pageClick(params) {
+    return invoke('page_click', params);
+}
+export function pageType(params) {
+    return invoke('page_type', params);
+}
+export function pageScroll(params) {
+    return invoke('page_scroll', params);
+}
+export function pageHover(params) {
+    return invoke('page_hover', params);
+}
+export function pageEval(params) {
+    return invoke('page_eval', params);
+}
+export function pageSnapshot(params) {
+    return invoke('page_snapshot', params);
+}
+export function pagePress(params) {
+    return invoke('page_press', params);
+}
+export function pageWait(params) {
+    return invoke('page_wait', params);
+}
+export function pageNavigate(params) {
+    return invoke('page_navigate', params);
+}
+export function pageUpload(params) {
+    return invoke('page_upload', params);
+}
+export function pageFrames(params) {
+    return invoke('page_frames', params);
+}
+export function setDeviceEmulation(params) {
+    return invoke('set_device_emulation', params);
+}
+export function setTimezone(params) {
+    return invoke('set_timezone', params);
+}
+export function getUserInfo(params = {}) {
+    return invoke('get_user_info', params);
+}
+export function runActions(params) {
+    return invoke('run_actions', params);
+}

package/dist/socket.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 底层 Socket 通信模块
+ *
+ * 通过 Unix Domain Socket (macOS/Linux) 或 Named Pipe (Windows) 与 native host 进程通信。
+ * 每次调用新建连接，收到响应后关闭，简单可靠。
+ *
+ * 当 Socket 文件不存在（ENOENT）时，自动尝试拉起 native host，稍后重试连接。
+ */
+export declare const CLIENT_VERSION: string;
+/**
+ * Legacy well-known socket. New native-hosts publish per-browser sockets in the
+ * registry and we address those; this path is a fallback for pre-registry hosts
+ * (or the pre-ping startup window) and is what auto-spawn targets.
+ */
+export declare const SOCKET_PATH: string;
+export interface InvokeOptions {
+    /** 超时时间（秒），默认 15 */
+    timeoutSec?: number;
+    /** Force CDP transport instead of extension */
+    transport?: 'cdp';
+    /** Target a specific browser by id / name (see the browser registry). */
+    browser?: string;
+}
+/** Pin the default target browser for subsequent invokes (undefined clears it). */
+export declare function setDefaultBrowser(selector: string | undefined): void;
+export declare function getDefaultBrowser(): string | undefined;
+export declare function decorateBrowserListResult(result: Record<string, any>): Record<string, any>;
+/**
+ * 向 native host 发送一个 action 请求并等待响应。
+ *
+ * 目标解析优先级：显式 options.browser → setDefaultBrowser → 环境变量
+ * MEARL_BROWSER → 自动（注册表中最近聚焦的浏览器）。注册表为空时回退到
+ * legacy well-known socket，并在 socket 不存在（ENOENT）时自动拉起 native host。
+ */
+export declare function invoke(action: string, data?: Record<string, any>, options?: InvokeOptions): Promise<any>;