@skrillex1224/android-toolkit 0.1.8 → 1.0.0

package/index.d.ts

@@ -1,191 +1,164 @@
 export interface AndroidContext {
-  adbPath?: string;
-  fridaPath?: string;
-  fridaServerPath?: string;
-  fridaWebViewEventAgentScript?: string;
-  serial: string;
-  packageName: string;
-  query: string;
-  runId?: string;
-  [key: string]: any;
-}
-
-export interface AndroidActorShareInfo {
-  mode: 'clipboard' | 'custom';
-  prefix: string;
-  xurl: Array<string | string[]>;
-}
-
-export interface AndroidActorInfoItem {
-  key: string;
-  name: string;
-  icon: string;
-  share: AndroidActorShareInfo;
-  [key: string]: any;
-}
-
-export interface AndroidConstantsModule {
-  Code: Record<string, number>;
-  Status: Record<string, string>;
-  ActorInfo: Record<string, AndroidActorInfoItem>;
-}
-
-export interface AndroidCrawlerErrorInfo {
-  message: string;
-  code?: number;
-  context?: Record<string, any>;
-}
-
-export interface AndroidCrawlerError extends Error {
-  code: number;
-  context?: Record<string, any>;
-}
-
-export interface AndroidErrorsModule {
-  CrawlerError: new (info: AndroidCrawlerErrorInfo) => AndroidCrawlerError;
-  serializeError(error: unknown): Record<string, any>;
-}
-
-export interface AndroidLogger {
-  debug(message: string, meta?: Record<string, any>): void;
-  info(message: string, meta?: Record<string, any>): void;
-  warn(message: string, meta?: Record<string, any>): void;
-  success(message: string, meta?: Record<string, any>): void;
-  fail(message: string, error?: unknown): void;
-  start(message: string, meta?: Record<string, any>): void;
-  duration(startedAt: number): string;
-  createLogger(scope: string): AndroidLogger;
-}
-
-export interface AndroidDeviceModule {
-  adbShell(ctx: AndroidContext, args: string[], options?: Record<string, any>): Promise<string>;
-  adbExec(ctx: AndroidContext, args: string[], options?: Record<string, any>): Promise<string>;
-  forceStopApp(ctx: AndroidContext, packageName?: string): Promise<void>;
-  startActivity(ctx: AndroidContext, component: string, args?: string[]): Promise<void>;
-  startLauncher(ctx: AndroidContext, packageName?: string, launcherActivity?: string): Promise<void>;
-  waitForForeground(ctx: AndroidContext, packageName?: string, timeoutMs?: number): Promise<boolean>;
-  screenSize(ctx: AndroidContext): Promise<{ width: number; height: number }>;
-  screenDensity(ctx: AndroidContext): Promise<number>;
-  overrideScreenSize(ctx: AndroidContext, width: number, height: number): Promise<void>;
-  resetScreenSize(ctx: AndroidContext): Promise<void>;
-  resetScreenDensity(ctx: AndroidContext): Promise<void>;
-  click(ctx: AndroidContext, pointOrX: any, y?: number): Promise<void>;
-  move(ctx: AndroidContext, from: { x: number; y: number }, to: { x: number; y: number }, durationMs?: number): Promise<void>;
-  pressBack(ctx: AndroidContext): Promise<void>;
-  wakeAndUnlock(ctx: AndroidContext): Promise<void>;
-  focusedActivity(ctx: AndroidContext): Promise<string>;
-  waitForActivity(ctx: AndroidContext, predicate: (focused: string) => boolean, timeoutMs?: number, intervalMs?: number): Promise<string>;
-  screenshotPng(ctx: AndroidContext): Promise<Buffer>;
-  screenshotBase64(ctx: AndroidContext): Promise<string>;
-  [key: string]: any;
-}
-
-export interface AndroidFridaModule {
-  runScript(ctx: AndroidContext, source: string, options?: Record<string, any>): Promise<any>;
-  querySQLite(ctx: AndroidContext, options?: Record<string, any>): Promise<any>;
-  startWebViewEventRecorder(ctx: AndroidContext, config?: Record<string, any>, options?: Record<string, any>): Promise<any>;
-}
-
-export interface AndroidShareScreenCompressionOptions {
-  enabled?: boolean;
-  maxBytes?: number;
-  maxBase64Bytes?: number;
-  type?: 'jpeg' | 'jpg';
-  outputType?: 'jpeg' | 'jpg';
-  quality?: number;
-  minQuality?: number;
-  minScale?: number;
-}
-
-export interface AndroidShareScreenCaptureOptions {
-  Frida?: AndroidFridaModule;
-  frida?: AndroidFridaModule;
-  actorInfo?: string | AndroidActorInfoItem;
-  actor?: string | AndroidActorInfoItem;
-  actorKey?: string | AndroidActorInfoItem;
-  restore?: boolean;
-  maxHeight?: number;
-  width?: number;
-  height?: number;
-  settleMs?: number;
-  scrollToTop?: boolean;
-  timeoutMs?: number;
-  fridaTimeoutSeconds?: number;
-  maxBytes?: number;
-  maxBase64Bytes?: number;
-  type?: 'jpeg' | 'jpg';
-  outputType?: 'jpeg' | 'jpg';
-  quality?: number;
-  minQuality?: number;
-  minScale?: number;
-  compression?: boolean | AndroidShareScreenCompressionOptions;
-  compress?: boolean;
-}
-
-export interface AndroidShareLinkCaptureOptions {
-  actorInfo?: string | AndroidActorInfoItem;
-  actor?: string | AndroidActorInfoItem;
-  actorKey?: string | AndroidActorInfoItem;
-  share?: Partial<AndroidActorShareInfo>;
-  timeoutMs?: number;
-  pollIntervalMs?: number;
-  payloadSnapshotMaxLen?: number;
-  signal?: AbortSignal;
-  performActions?: () => any | Promise<any>;
-}
-
-export interface AndroidShareLinkCaptureResult {
-  link: string | null;
-  payloadText: string;
-  payloadSnapshot: string;
-  source: 'clipboard' | 'custom' | 'none' | string;
-}
-
-export interface AndroidShareModule {
-  captureScreen(ctx: AndroidContext, options?: AndroidShareScreenCaptureOptions): Promise<string>;
-  captureLink(ctx: AndroidContext, options?: AndroidShareLinkCaptureOptions): Promise<AndroidShareLinkCaptureResult>;
-}
-
-export interface AndroidApifyKitInstance {
-  runStep<T>(name: string, meta: any, fn: () => Promise<T> | T): Promise<T>;
-  runStepLoose<T>(name: string, meta: any, fn: () => Promise<T> | T): Promise<T>;
-  pushSuccess(data: any): Promise<void>;
-  pushFailed(error: unknown, context?: Record<string, any>): Promise<void>;
-  pushArtifact(data: any): Promise<void>;
-  hasPushed(): boolean;
-}
-
-export interface AndroidApifyKitModule {
-  useApifyKit(options?: Record<string, any>): Promise<AndroidApifyKitInstance>;
-}
-
-export interface AndroidLaunchRunHandlerArgs {
-  input: any;
-  ctx: AndroidContext;
-  kit: {
-    ApifyKit: AndroidApifyKitInstance;
-    Device: AndroidDeviceModule;
-    Frida: AndroidFridaModule;
-    Share: AndroidShareModule;
-    Logger: AndroidLogger;
-  };
-  ApifyKit: AndroidApifyKitInstance;
-}
-
-export interface AndroidLaunchModule {
-  run(handler: (args: AndroidLaunchRunHandlerArgs) => Promise<void> | void, options?: Record<string, any>): Promise<void>;
+    runId: string;
+    query: string;
+    serial: string;
+    packageName: string;
+    adbPath: string;
+    fridaPath: string;
+    actorKey?: string;
+    appVersion?: string;
+    slotKey?: string;
+    instanceId?: string;
+    externalIp?: string;
+}
+
+export interface ViewBounds {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+    centerX: number;
+    centerY: number;
+}
+
+export interface ViewNode {
+    resourceId: string;
+    id: string;
+    text: string;
+    contentDesc: string;
+    className: string;
+    packageName: string;
+    bounds: ViewBounds;
+    clickable: boolean;
+    enabled: boolean;
+    focusable: boolean;
+    focused: boolean;
+    scrollable: boolean;
+    visible: boolean;
+    children: ViewNode[];
+}
+
+export type ViewSelector = {
+    id?: string;
+    text?: string;
+    textContains?: string;
+    contentDesc?: string;
+};
+
+export namespace Constants {
+    export const Code: Record<string, number>;
+    export const Status: Record<string, string>;
+    export const UnicodeIme: {
+        packageName: string;
+        component: string;
+        inputTextAction: string;
+    };
+    export const ActorInfo: Record<string, {
+        key: string;
+        name: string;
+        icon: string;
+        share: {
+            mode: 'clipboard';
+            prefix: string;
+            xurl: unknown[];
+        };
+    }>;
+}
+
+export namespace Errors {
+    export class CrawlerError extends Error {
+        code: number;
+        context: Record<string, unknown>;
+        constructor(input?: string | {
+            message?: string;
+            code?: number;
+            context?: Record<string, unknown>;
+        });
+        static isCrawlerError(error: unknown): boolean;
+        static from(error: unknown, fallback?: {
+            code?: number;
+            context?: Record<string, unknown>;
+        }): CrawlerError;
+    }
+    export function serializeError(error: unknown): Record<string, unknown>;
 }
 
 export interface AndroidToolkit {
-  Launch: AndroidLaunchModule;
-  ApifyKit: AndroidApifyKitModule;
-  Device: AndroidDeviceModule;
-  Frida: AndroidFridaModule;
-  Share: AndroidShareModule;
-  Constants: AndroidConstantsModule;
-  Errors: AndroidErrorsModule;
-  Logger: AndroidLogger;
-  Context: Record<string, any>;
+    Launch: {
+        run(handler: (args: {
+            input: Record<string, unknown>;
+            ctx: AndroidContext;
+            kit: AndroidToolkitRuntime;
+            ApifyKit: AndroidToolkitRuntime['ApifyKit'];
+        }) => Promise<void>, options?: Record<string, unknown>): Promise<void>;
+    };
+    ApifyKit: {
+        useApifyKit(options?: Record<string, unknown>): Promise<AndroidToolkitRuntime['ApifyKit']>;
+    };
+    DeviceInput: AndroidToolkitRuntime['DeviceInput'];
+    DeviceView: AndroidToolkitRuntime['DeviceView'];
+    Device: AndroidToolkitRuntime['Device'];
+    Mutation: AndroidToolkitRuntime['Mutation'];
+    Share: AndroidToolkitRuntime['Share'];
+    Frida: AndroidToolkitRuntime['Frida'];
+    Constants: typeof Constants;
+    Errors: typeof Errors;
+    Logger: AndroidToolkitRuntime['Logger'];
+    Context: {
+        createAndroidContext(input?: Record<string, unknown>, defaults?: Record<string, unknown>): AndroidContext;
+        firstNonEmpty(...values: unknown[]): string;
+        requireNonEmpty(value: unknown, name: string): string;
+    };
+}
+
+export interface AndroidToolkitRuntime {
+    ApifyKit: {
+        runStep<T>(step: string, target: unknown, actionFn: () => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+        runStepLoose<T>(step: string, target: unknown, actionFn: () => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+        pushSuccess(data?: Record<string, unknown>, options?: Record<string, unknown>): Promise<void>;
+        pushFailed(error: unknown, meta?: Record<string, unknown>): Promise<void>;
+        pushArtifact(data?: Record<string, unknown>): Promise<void>;
+        hasPushed(): boolean;
+    };
+    Device: Record<string, (...args: any[]) => Promise<any>>;
+    DeviceInput: {
+        click(ctx: AndroidContext, selectorOrPoint: ViewSelector | ViewBounds | {x: number; y: number}, options?: Record<string, unknown>): Promise<unknown>;
+        tap(ctx: AndroidContext, selectorOrPoint: ViewSelector | ViewBounds | {x: number; y: number}, options?: Record<string, unknown>): Promise<unknown>;
+        fill(ctx: AndroidContext, selector: ViewSelector, text: string, options?: Record<string, unknown>): Promise<void>;
+        type(ctx: AndroidContext, selector: ViewSelector, text: string, options?: Record<string, unknown>): Promise<void>;
+        press(ctx: AndroidContext, key: string, options?: Record<string, unknown>): Promise<void>;
+        pressEnter(ctx: AndroidContext, options?: Record<string, unknown>): Promise<void>;
+        scroll(ctx: AndroidContext, selector: ViewSelector, direction: 'up' | 'down', options?: Record<string, unknown>): Promise<void>;
+        scrollToEnd(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<unknown>;
+        scrollToTop(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<unknown>;
+    };
+    DeviceView: {
+        snapshot(ctx: AndroidContext, options?: Record<string, unknown>): Promise<{xml: string; tree: ViewNode[]; roots: ViewNode[]; flat: ViewNode[]; nodes: ViewNode[]}>;
+        find(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<ViewNode>;
+        findAll(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<ViewNode[]>;
+        waitFor(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<ViewNode>;
+        bounds(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<ViewBounds>;
+        text(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<string>;
+        exists(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<boolean>;
+        isScrollable(ctx: AndroidContext, selector: ViewSelector, options?: Record<string, unknown>): Promise<boolean>;
+        hashNode(node: ViewNode): string;
+    };
+    Mutation: {
+        waitForStable(ctx: AndroidContext, selectors: ViewSelector | ViewSelector[] | string | string[], options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+        waitForStableAcrossRoots(ctx: AndroidContext, selectors: ViewSelector | ViewSelector[] | string | string[], options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+        useMonitor(ctx: AndroidContext, selectors: ViewSelector | ViewSelector[] | string | string[], options?: Record<string, unknown>): Promise<{stop(): Promise<Record<string, unknown>>}>;
+    };
+    Share: {
+        captureScreen(ctx: AndroidContext, options?: Record<string, unknown>): Promise<string>;
+        captureLink(ctx: AndroidContext, options?: Record<string, unknown>): Promise<{link: string; source: string; payloadSnapshot: string}>;
+    };
+    Frida: {
+        querySQLite(ctx: AndroidContext, options: Record<string, unknown>): Promise<Record<string, unknown>>;
+        health(ctx: AndroidContext): Promise<Record<string, unknown>>;
+    };
+    Logger: Record<string, any>;
 }
 
 export function useAndroidToolKit(): AndroidToolkit;

package/package.json

@@ -1,29 +1,47 @@
 {
   "name": "@skrillex1224/android-toolkit",
-  "version": "0.1.8",
+  "version": "1.0.0",
+  "description": "Native Android automation toolkit for Apify-compatible actors.",
   "type": "module",
-  "main": "index.js",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
   "types": "index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "browser": {
+        "types": "./browser.d.ts",
+        "default": "./dist/browser.js"
+      },
+      "types": "./index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./browser": {
+      "types": "./browser.d.ts",
+      "default": "./dist/browser.js"
+    }
   },
   "files": [
-    "index.js",
+    "dist/",
+    "browser.d.ts",
     "index.d.ts",
-    "entrys",
-    "src",
-    "scripts",
     "README.md"
   ],
   "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "check": "node --check index.js && node --check entrys/node.js && node --check src/launch.js && node --check src/apify-kit.js && node --check src/context.js && node --check src/constants.js && node --check src/device.js && node --check src/errors.js && node --check src/frida-client.js && node --check src/logger.js && node --check src/share.js && node --check src/internals/compression.js && node --check src/internals/frida/webview_event_agent.js",
-    "test": "node --test test/*.test.js"
+    "build": "node build.js",
+    "check": "node --check index.js && node --check entrys/node.js && node --check entrys/browser.js && node --check build.js && find src -name '*.js' -maxdepth 3 -print0 | xargs -0 -n1 node --check",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm run build"
   },
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
+    "esbuild": "^0.24.2",
+    "fast-xml-parser": "^4.5.1",
     "jimp": "^1.6.1"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/entrys/node.js

@@ -1,26 +0,0 @@
-import { Launch } from '../src/launch.js';
-import { ApifyKit } from '../src/apify-kit.js';
-import { Device } from '../src/device.js';
-import { Frida } from '../src/frida-client.js';
-import { Share } from '../src/share.js';
-import * as Constants from '../src/constants.js';
-import * as Errors from '../src/errors.js';
-import { Logger } from '../src/logger.js';
-import { Context } from '../src/context.js';
-
-// Unified Entry Point
-// 和 playwright-toolkit 的 usePlaywrightToolKit() 保持同一种入口格式：
-// visitor/androider 只从这里取模块，不直接穿透到内部文件。
-export const useAndroidToolKit = () => {
-  return {
-    Launch,
-    ApifyKit,
-    Device,
-    Frida,
-    Share,
-    Constants,
-    Errors,
-    Logger,
-    Context
-  };
-};

package/index.js

@@ -1 +0,0 @@
-export { useAndroidToolKit } from './entrys/node.js';

package/scripts/postinstall.js

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-
-import {execFileSync, spawnSync} from 'node:child_process';
-
-log('检查 Android toolkit 运行环境');
-checkAdb();
-installOrCheckFrida();
-
-function checkAdb() {
-    const adb = findCommand('adb');
-    if (adb) {
-        log(`已找到 adb: ${adb}`);
-        return;
-    }
-    warn(`未找到 adb。请安装 Android platform-tools，并确保 \`adb\` 在 PATH 中。${installHintForAdb()}`);
-}
-
-function installOrCheckFrida() {
-    const frida = findCommand('frida');
-    if (frida) {
-        log(`已找到 frida: ${frida}`);
-        return;
-    }
-
-    const pip3 = findCommand('pip3');
-    const python3 = findCommand('python3');
-    if (!pip3 || !python3) {
-        warn(`未找到 frida，且当前机器缺少 python3/pip3，无法自动安装 frida-tools。${installHintForFrida()}`);
-        return;
-    }
-
-    try {
-        log('尝试自动安装 frida-tools 到用户目录');
-        execFileSync(python3, ['-m', 'pip', 'install', '--user', '--upgrade', 'frida-tools'], {stdio: 'inherit'});
-        const installedFrida = findCommand('frida');
-        if (installedFrida) {
-            log(`frida 安装成功: ${installedFrida}`);
-            return;
-        }
-        warn('frida-tools 已安装，但 `frida` 仍不在 PATH 中。请把 Python user bin 加入 PATH。');
-        return;
-    } catch (error) {
-        warn(`自动安装 frida-tools 失败: ${error.message || String(error)}`);
-    }
-
-    warn(`未能自动准备 frida，请手动确认 \`frida --version\` 可执行。${installHintForFrida()}`);
-}
-
-function findCommand(command) {
-    const result = spawnSync('which', [command], {encoding: 'utf8'});
-    return result.status === 0 ? String(result.stdout || '').trim() : '';
-}
-
-function installHintForAdb() {
-    if (process.platform === 'darwin') return ' macOS 可用 `brew install android-platform-tools`。';
-    if (process.platform === 'linux') return ' Linux 可安装 Android platform-tools，或用系统包管理器安装 adb（如 apt/dnf/pacman/apk）。';
-    return '';
-}
-
-function installHintForFrida() {
-    if (process.platform === 'darwin') return ' macOS 也可用 `python3 -m pip install --user frida-tools`。';
-    if (process.platform === 'linux') return ' Linux 也可用 `python3 -m pip install --user frida-tools`。';
-    return '';
-}
-
-function log(message) {
-    console.log(`[android-toolkit] ${message}`);
-}
-
-function warn(message) {
-    console.warn(`[android-toolkit] ${message}`);
-}