@bryce3310687963/android-toolkit 0.0.0-stage → 1.0.51

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# Android Toolkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@bryce3310687963/android-toolkit` is the native Android counterpart to
+`@skrillex1224/playwright-toolkit`.
+
+Actor code should import only `useAndroidToolKit()` and then use the returned modules.
+The public API is intentionally small and destructive from v1 onward.
+
+```js
+import { useAndroidToolKit } from '@bryce3310687963/android-toolkit';
+
+const { Launch } = useAndroidToolKit();
+
+await Launch.run(async ({ ctx, kit }) => {
+  const { ApifyKit, DeviceInput, Mutation, Share } = kit;
+  await ApifyKit.runStep('输入并发送', ctx, async () => {
+    await DeviceInput.click(ctx, { id: 'input_text' });
+    await DeviceInput.fill(ctx, { id: 'input_text' }, ctx.query);
+    await DeviceInput.click(ctx, { id: 'action_send' });
+  });
+  await Mutation.waitForStable(ctx, { id: 'message_list' });
+  const screenshotBase64 = await Share.captureScreen(ctx);
+  await ApifyKit.pushArtifact({ screenshotBase64 });
+});
+```
+
+## Public Modules
+
+| Module | Responsibility |
+| --- | --- |
+| `Launch` | Native actor entrypoint with fixed `/apify_storage/input.json` and `/apify_storage/output.json` paths plus lifecycle hooks. |
+| `ApifyKit` | `runStep`, `runStepLoose`, `pushSuccess`, `pushFailed`, `pushArtifact`. |
+| `Device` | Low-level ADB primitives only. |
+| `DeviceView` | Native View-tree snapshot and selector lookup over `uiautomator dump`. |
+| `DeviceInput` | View-tree-backed click/fill/press/scroll APIs using ADB input. |
+| `Mutation` | Playwright-like stable wait semantics over matched ViewNode subtrees. |
+| `Share` | Sprite screenshot and clipboard share-link polling. |
+| `DeviceSQLite` | Root ADB-backed private SQLite snapshot queries. |
+| `Constants` | Native-useful actor metadata and codes. |
+| `Errors` | `CrawlerError` and error serialization. |
+
+## Runtime Contract
+
+The toolkit does not install or discover runtime tools.
+
+Required environment:
+
+- `ANDROID_TOOLKIT_ADB_PATH`
+
+Device initialization, Appium Settings, UnicodeIME, and root ADB access belong
+to manager/cluster runtime. Runtime checks fail clearly when prerequisites are missing.
+
+## Boundaries
+
+Included:
+
+- ADB command execution, app launch, key input, screenshot, activity checks.
+- View-tree parsing with a real XML parser.
+- View selector operations: `id`, `text`, `textContains`, `contentDesc`, `className`.
+- Root ADB-backed SQLite queries through `DeviceSQLite.query()` only.
+
+Excluded:
+
+- Public generic process injection or app hook execution.
+- App hook clipboard helpers.
+- WebView event recorder.
+- App hook UI traversal/click helpers.
+- Package name and activity truth. Backend/runtime input owns those values.
+- Actor-specific DB schemas, message parsing, product parsing, and success criteria.
+
+## Android Actor Rules
+
+- Do not use hardcoded absolute coordinates, screen-ratio coordinates, or naked point taps in actor code.
+- Do not add fallback clicks. If the expected selector, DOM element, activity, or key-driven flow is unavailable, fail with a typed error and useful context.
+- UI actions must be driven by one of: native `DeviceView` selectors, WebView DOM actions, Android activity/intents, or deterministic key events with activity/state verification.
+- If an app renders custom UI that is invisible to `uiautomator`, use a stable app/runtime capability instead of guessing screen positions.
+- Bounds-based taps are allowed only when the bounds come from a located native view; WebView clicks must stay in `WebView.click`/`WebView.evaluate`.
+
+## Browser Entry
+
+`@bryce3310687963/android-toolkit/browser` exports only `Constants` and `Errors`.
+
+## Clear App Cache
+
+`Device.clearAppCache(ctx, packageName = ctx.packageName)` requires root ADB access.
+Stop the app before clearing its cache, then launch it again:
+
+```js
+await Device.forceStopApp(ctx);
+await Device.clearAppCache(ctx);
+await Device.startLauncher(ctx);
+```
+
+This clears the contents of `/data/data/<package>/cache`,
+`/data/data/<package>/code_cache`, and `/sdcard/Android/data/<package>/cache`.
+It preserves the cache directories themselves and toolkit runtime directories
+`apify-webview-bridge` and `network-capture`. Databases, preferences, files,
+WebView cookies, and login data are outside the cleanup scope. Missing cache
+directories are skipped; invalid package names and cleanup errors fail the call.
+Each actor chooses whether to call this method; `Launch.run` does not clear caches
+automatically.

package/browser.d.ts

@@ -0,0 +1,158 @@
+export interface WebViewHookConfig {
+    name: string | string[];
+    value: string[];
+}
+
+export namespace Constants {
+    export const Code: Record<string, number>;
+    export const Status: Record<string, string>;
+    export const StoragePath: {
+        Input: '/apify_storage/input.json';
+        Output: '/apify_storage/output.json';
+    };
+    export const ActorKey: {
+        DoubaoAndroid: 'doubao.android';
+        ErineAndroid: 'erine.android';
+        WechatAndroid: 'wechat.android';
+        QwenAndroid: 'qwen.android';
+        YuanbaoAndroid: 'yuanbao.android';
+        XhsAndroid: 'xhs.android';
+    };
+    export const WebViewBridge: {
+        packageName: string;
+        actionCommand: string;
+        cacheDir: string;
+        hookConfigFile: string;
+        commandDir: string;
+        resultDir: string;
+    };
+    export const ActorInfo: Record<string, {
+        key: string;
+        name: string;
+        icon: string;
+        webviews: WebViewHookConfig[];
+        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 interface LoggerAdapter {
+    info(message: string): void;
+    warning?(message: string): void;
+    warn?(message: string): void;
+    error?(message: string): void;
+    debug?(message: string): void;
+}
+
+export interface LoggerTemplate {
+    step(step: string, status?: string, details?: unknown, level?: 'info' | 'warn' | 'warning' | 'error' | 'success' | 'start' | 'debug'): void;
+    taskStart(detail?: unknown): void;
+    taskSuccess(detail?: unknown): void;
+    taskFail(detail?: unknown, error?: unknown): void;
+    launchStart(detail?: unknown): void;
+    launchSuccess(detail?: unknown): void;
+    launchFail(detail?: unknown, error?: unknown): void;
+    inputMethodSnapshotFail(error?: unknown): void;
+    inputMethodRestoreFail(error?: unknown): void;
+    stepStart(step?: string, detail?: unknown): void;
+    stepSuccess(step?: string, detail?: unknown): void;
+    stepFail(step?: string, error?: unknown): void;
+    stepRetry(step?: string, attempt?: unknown): void;
+    adbExec(detail?: unknown): void;
+    adbRetry(detail?: unknown): void;
+    mutationWaitStart(detail?: unknown): void;
+    mutationWaitSuccess(detail?: unknown): void;
+    mutationWaitWarn(detail?: unknown): void;
+    webViewCommand(detail?: unknown): void;
+    webViewSuccess(detail?: unknown): void;
+    webViewWarn(detail?: unknown): void;
+    webViewFail(error?: unknown): void;
+    screenshotStart(detail?: unknown): void;
+    screenshotDone(detail?: unknown): void;
+    shareStart(detail?: unknown): void;
+    shareSuccess(detail?: unknown): void;
+    shareFail(error?: unknown): void;
+    dataPush(detail?: unknown): void;
+    dataPushFail(error?: unknown): void;
+    info(message: string, detail?: unknown): void;
+    success(message: string, detail?: unknown): void;
+    warning(message: string, detail?: unknown): void;
+    warn(message: string, detail?: unknown): void;
+    error(message: string, detail?: unknown): void;
+    debug(message: string, detail?: unknown): void;
+    start(message: string, detail?: unknown): void;
+}
+
+export interface LoggerModule {
+    setLogger(logger: LoggerAdapter | null): void;
+    createLogger(scope?: string): ScopedLoggerModule;
+    useTemplate(logger?: LoggerAdapter | null): LoggerTemplate;
+    start(message: string, detail?: unknown): void;
+    success(message: string, detail?: unknown): void;
+    fail(message: string, error?: unknown): void;
+    warn(message: string, detail?: unknown): void;
+    warning(message: string, detail?: unknown): void;
+    error(message: string, detail?: unknown): void;
+    info(message: string, detail?: unknown): void;
+    debug(message: string, detail?: unknown): void;
+    duration(startedAt: number): string;
+}
+
+export interface ScopedLoggerModule {
+    start(message: string, detail?: unknown): void;
+    success(message: string, detail?: unknown): void;
+    fail(message: string, error?: unknown): void;
+    warn(message: string, detail?: unknown): void;
+    warning(message: string, detail?: unknown): void;
+    error(message: string, detail?: unknown): void;
+    info(message: string, detail?: unknown): void;
+    debug(message: string, detail?: unknown): void;
+    useTemplate(): LoggerTemplate;
+}
+
+export interface LogTemplate {
+    key: string;
+    label: string;
+    group: string;
+    attention: 'low' | 'medium' | 'high' | 'critical';
+    patterns: RegExp[];
+    defaultSelected?: boolean;
+}
+
+export interface BrowserAndroidToolkit {
+    Constants: typeof Constants;
+    Errors: typeof Errors;
+    Logger: LoggerModule;
+    LOG_TEMPLATES: LogTemplate[];
+    $Internals: {
+        LOG_TEMPLATES: LogTemplate[];
+        stripAnsi(input: unknown): string;
+    };
+}
+
+export function useAndroidToolKit(): BrowserAndroidToolkit;
+export namespace useAndroidToolKit {
+    const Mode: {
+        default: 'default';
+    };
+}