@phone-use/sdk 0.1.0

package/dist/testing.mjs

@@ -0,0 +1,188 @@
+import { n as BaseDeviceBackend, t as ALL_CAPABILITIES } from "./device-BzPnHvQy.mjs";
+//#region src/testing.ts
+/**
+* The device-free test double the VPS test tier stands on (docs/20 item 2
+* verification protocol). Scripts a sequence of snapshot "screens"; records
+* every call; lets tests simulate screen transitions per action. Zero deps,
+* Node-only. Public via the `@phone-use/sdk/testing` subpath so harness tests
+* and third-party backend authors share it.
+*/
+var FakeBackend = class extends BaseDeviceBackend {
+	/** Every backend call made, in order. */
+	calls = [];
+	screens;
+	current = 0;
+	onAction;
+	failWith;
+	constructor(opts) {
+		super(opts.name ?? "fake", opts.capabilities ?? ALL_CAPABILITIES);
+		if (!opts.screens.length) throw new Error("FakeBackend needs at least one screen");
+		this.screens = opts.screens;
+		this.onAction = opts.onAction;
+		this.failWith = opts.failWith;
+	}
+	/** Jump to screen `i` (throws when out of range). */
+	setScreen(i) {
+		if (i < 0 || i >= this.screens.length) throw new Error(`no screen ${i}`);
+		this.current = i;
+	}
+	/** Index of the screen currently being served. */
+	get screenIndex() {
+		return this.current;
+	}
+	record(method, ...args) {
+		const call = {
+			method,
+			args
+		};
+		this.calls.push(call);
+		const err = this.failWith?.(call);
+		if (err !== void 0) throw err;
+		const next = this.onAction?.(call, this.current);
+		if (next !== void 0) this.setScreen(next);
+		return call;
+	}
+	snapshot(opts) {
+		this.record("snapshot", opts);
+		return Promise.resolve(this.screens[this.current]);
+	}
+	screenshot(opts) {
+		this.record("screenshot", opts);
+		return Promise.resolve({ path: opts.path });
+	}
+	press(target) {
+		this.record("press", target);
+		return Promise.resolve();
+	}
+	longPress(ref, durationMs) {
+		this.record("longPress", ref, durationMs);
+		return Promise.resolve();
+	}
+	fill(ref, text) {
+		this.record("fill", ref, text);
+		return Promise.resolve();
+	}
+	typeText(text) {
+		this.record("typeText", text);
+		return Promise.resolve();
+	}
+	pressKey(key) {
+		this.record("pressKey", key);
+		return Promise.resolve();
+	}
+	scroll(direction) {
+		this.record("scroll", direction);
+		return Promise.resolve();
+	}
+	pan(x, y, dx, dy, durationMs) {
+		this.record("pan", x, y, dx, dy, durationMs);
+		return Promise.resolve();
+	}
+	waitForText(text, timeoutMs) {
+		this.record("waitForText", text, timeoutMs);
+		return Promise.resolve();
+	}
+	systemAlert(action) {
+		this.record("systemAlert", action);
+		return Promise.resolve({ alert: null });
+	}
+	home() {
+		this.record("home");
+		return Promise.resolve();
+	}
+	back() {
+		this.record("back");
+		return Promise.resolve();
+	}
+	openApp(opts) {
+		this.record("openApp", opts);
+		const s = this.screens[this.current];
+		return Promise.resolve({
+			appName: s.appName,
+			appBundleId: s.appBundleId
+		});
+	}
+	listApps() {
+		this.record("listApps");
+		return Promise.resolve([]);
+	}
+	closeSession() {
+		this.record("closeSession");
+		return Promise.resolve();
+	}
+};
+const DEFAULT_RECT = {
+	x: 0,
+	y: 100,
+	width: 390,
+	height: 44
+};
+/** Fixture sugar: an element with sane defaults (Button role, on-screen rect). */
+function el(partial) {
+	return {
+		type: "Button",
+		label: "",
+		rect: { ...DEFAULT_RECT },
+		...partial
+	};
+}
+/** Fixture sugar: a screen with an Application root so viewport detection works. */
+function screen(nodes, app = {}) {
+	return {
+		nodes: [{
+			type: "Application",
+			rect: {
+				x: 0,
+				y: 0,
+				width: 390,
+				height: 844
+			}
+		}, ...nodes],
+		appName: app.appName,
+		appBundleId: app.appBundleId
+	};
+}
+/**
+* The DI'd process runner for lifecycle tests (docs/19: dependency-inject the
+* spawn/exec runner). Takes an ordered script of steps; each call consumes the
+* next step, optionally asserting the argv shape, and resolves/rejects in the
+* execFile-error shape defaultExecRunner produces.
+*/
+function scriptedExecRunner(steps) {
+	const queue = [...steps];
+	const calls = [];
+	const runner = (async (file, args) => {
+		calls.push({
+			file,
+			args: [...args]
+		});
+		const step = queue.shift();
+		if (!step) throw new Error(`scriptedExecRunner: unexpected call ${file} ${args.join(" ")}`);
+		if (step.expectArgs && !step.expectArgs(file, args)) throw new Error(`scriptedExecRunner: argv mismatch for ${file} ${args.join(" ")}`);
+		if (step.code !== void 0 && step.code !== 0) {
+			const err = /* @__PURE__ */ new Error(`Command failed: ${file} ${args.join(" ")}\n${step.stderr ?? ""}`);
+			err.code = step.code;
+			err.stdout = step.stdout ?? "";
+			err.stderr = step.stderr ?? "";
+			err.killed = step.killed ?? false;
+			throw err;
+		}
+		if (step.killed) {
+			const err = /* @__PURE__ */ new Error(`Command killed: ${file}`);
+			err.killed = true;
+			err.signal = "SIGTERM";
+			throw err;
+		}
+		return {
+			stdout: step.stdout ?? "",
+			stderr: step.stderr ?? ""
+		};
+	});
+	runner.calls = calls;
+	runner.remaining = () => queue.length;
+	return runner;
+}
+//#endregion
+export { FakeBackend, el, screen, scriptedExecRunner };
+
+//# sourceMappingURL=testing.mjs.map

package/dist/testing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.mjs","names":[],"sources":["../src/testing.ts"],"sourcesContent":["import { BaseDeviceBackend } from './backend.ts';\nimport type {\n  AlertAction,\n  BackendAlertResult,\n  Capability,\n  OpenAppResult,\n  PressTarget,\n  Rect,\n  ScrollDirection,\n  Snapshot,\n  SnapshotNode,\n} from './device.ts';\nimport { ALL_CAPABILITIES } from './device.ts';\n\n/** One scripted screen in a {@link FakeBackend} sequence (alias of Snapshot). */\nexport type FakeScreen = Snapshot;\n/** A recorded backend call: method name plus the arguments it received. */\nexport type FakeCall = { method: string; args: unknown[] };\n\n/**\n * The device-free test double the VPS test tier stands on (docs/20 item 2\n * verification protocol). Scripts a sequence of snapshot \"screens\"; records\n * every call; lets tests simulate screen transitions per action. Zero deps,\n * Node-only. Public via the `@phone-use/sdk/testing` subpath so harness tests\n * and third-party backend authors share it.\n */\nexport class FakeBackend extends BaseDeviceBackend {\n  /** Every backend call made, in order. */\n  readonly calls: FakeCall[] = [];\n  private screens: FakeScreen[];\n  private current = 0;\n  private readonly onAction: ((call: FakeCall, current: number) => number | undefined) | undefined;\n  private readonly failWith: ((call: FakeCall) => unknown) | undefined;\n\n  constructor(opts: {\n    screens: FakeScreen[];\n    name?: string;\n    capabilities?: Iterable<Capability>;\n    /** Return a new screen index to simulate a transition caused by the call. */\n    onAction?: (call: FakeCall, current: number) => number | undefined;\n    /** Throw for matching calls — return the error to throw, undefined to pass. */\n    failWith?: (call: FakeCall) => unknown;\n  }) {\n    super(opts.name ?? 'fake', opts.capabilities ?? ALL_CAPABILITIES);\n    if (!opts.screens.length) throw new Error('FakeBackend needs at least one screen');\n    this.screens = opts.screens;\n    this.onAction = opts.onAction;\n    this.failWith = opts.failWith;\n  }\n\n  /** Jump to screen `i` (throws when out of range). */\n  setScreen(i: number): void {\n    if (i < 0 || i >= this.screens.length) throw new Error(`no screen ${i}`);\n    this.current = i;\n  }\n\n  /** Index of the screen currently being served. */\n  get screenIndex(): number {\n    return this.current;\n  }\n\n  private record(method: string, ...args: unknown[]): FakeCall {\n    const call: FakeCall = { method, args };\n    this.calls.push(call);\n    const err = this.failWith?.(call);\n    if (err !== undefined) throw err;\n    const next = this.onAction?.(call, this.current);\n    if (next !== undefined) this.setScreen(next);\n    return call;\n  }\n\n  override snapshot(opts?: {\n    interactiveOnly?: boolean | undefined;\n    depth?: number | undefined;\n  }): Promise<Snapshot> {\n    this.record('snapshot', opts);\n    return Promise.resolve(this.screens[this.current]!);\n  }\n\n  override screenshot(opts: { path: string; overlayRefs?: boolean | undefined }): Promise<{ path: string }> {\n    this.record('screenshot', opts);\n    return Promise.resolve({ path: opts.path }); // records; writes nothing\n  }\n\n  override press(target: PressTarget): Promise<void> {\n    this.record('press', target);\n    return Promise.resolve();\n  }\n\n  override longPress(ref: string, durationMs?: number): Promise<void> {\n    this.record('longPress', ref, durationMs);\n    return Promise.resolve();\n  }\n\n  override fill(ref: string, text: string): Promise<void> {\n    this.record('fill', ref, text);\n    return Promise.resolve();\n  }\n\n  override typeText(text: string): Promise<void> {\n    this.record('typeText', text);\n    return Promise.resolve();\n  }\n\n  override pressKey(key: 'return'): Promise<void> {\n    this.record('pressKey', key);\n    return Promise.resolve();\n  }\n\n  override scroll(direction: ScrollDirection): Promise<void> {\n    this.record('scroll', direction);\n    return Promise.resolve();\n  }\n\n  override pan(x: number, y: number, dx: number, dy: number, durationMs?: number): Promise<void> {\n    this.record('pan', x, y, dx, dy, durationMs);\n    return Promise.resolve();\n  }\n\n  override waitForText(text: string, timeoutMs?: number): Promise<void> {\n    this.record('waitForText', text, timeoutMs);\n    return Promise.resolve();\n  }\n\n  override systemAlert(action: AlertAction): Promise<BackendAlertResult> {\n    this.record('systemAlert', action);\n    return Promise.resolve({ alert: null });\n  }\n\n  override home(): Promise<void> {\n    this.record('home');\n    return Promise.resolve();\n  }\n\n  override back(): Promise<void> {\n    this.record('back');\n    return Promise.resolve();\n  }\n\n  override openApp(opts: {\n    app?: string | undefined;\n    url?: string | undefined;\n    relaunch?: boolean | undefined;\n  }): Promise<OpenAppResult> {\n    this.record('openApp', opts);\n    const s = this.screens[this.current]!;\n    return Promise.resolve({ appName: s.appName, appBundleId: s.appBundleId });\n  }\n\n  override listApps(): Promise<string[]> {\n    this.record('listApps');\n    return Promise.resolve([]);\n  }\n\n  override closeSession(): Promise<void> {\n    this.record('closeSession');\n    return Promise.resolve();\n  }\n}\n\nconst DEFAULT_RECT: Rect = { x: 0, y: 100, width: 390, height: 44 };\n\n/** Fixture sugar: an element with sane defaults (Button role, on-screen rect). */\nexport function el(partial: Partial<SnapshotNode> & { ref: string }): SnapshotNode {\n  return { type: 'Button', label: '', rect: { ...DEFAULT_RECT }, ...partial };\n}\n\n/** Fixture sugar: a screen with an Application root so viewport detection works. */\nexport function screen(\n  nodes: SnapshotNode[],\n  app: { appName?: string | undefined; appBundleId?: string | undefined } = {},\n): FakeScreen {\n  const root: SnapshotNode = { type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } };\n  return { nodes: [root, ...nodes], appName: app.appName, appBundleId: app.appBundleId };\n}\n\nexport type { ExecOptions, ExecResult, ExecRunner } from './exec.ts';\n\n/** One step in a {@link scriptedExecRunner} script — what the next exec call gets. */\nexport type ScriptedExecStep = {\n  /** Optional argv guard — the step throws if the call doesn't match. */\n  expectArgs?: ((file: string, args: string[]) => boolean) | undefined;\n  stdout?: string | undefined;\n  stderr?: string | undefined;\n  /** Nonzero → the call rejects with an execFile-shaped error. */\n  code?: number | undefined;\n  /** Simulate a runner timeout kill. */\n  killed?: boolean | undefined;\n};\n\n/** The runner {@link scriptedExecRunner} returns: an ExecRunner plus call inspection. */\nexport type ScriptedExecRunner = import('./exec.ts').ExecRunner & {\n  /** Every exec call made, in order. */\n  calls: { file: string; args: string[] }[];\n  /** Steps not yet consumed (assert 0 at test end for full-sequence checks). */\n  remaining(): number;\n};\n\n/**\n * The DI'd process runner for lifecycle tests (docs/19: dependency-inject the\n * spawn/exec runner). Takes an ordered script of steps; each call consumes the\n * next step, optionally asserting the argv shape, and resolves/rejects in the\n * execFile-error shape defaultExecRunner produces.\n */\nexport function scriptedExecRunner(steps: ScriptedExecStep[]): ScriptedExecRunner {\n  const queue = [...steps];\n  const calls: { file: string; args: string[] }[] = [];\n  const runner = (async (file: string, args: string[]) => {\n    calls.push({ file, args: [...args] });\n    const step = queue.shift();\n    if (!step) throw new Error(`scriptedExecRunner: unexpected call ${file} ${args.join(' ')}`);\n    if (step.expectArgs && !step.expectArgs(file, args)) {\n      throw new Error(`scriptedExecRunner: argv mismatch for ${file} ${args.join(' ')}`);\n    }\n    if (step.code !== undefined && step.code !== 0) {\n      const err = new Error(`Command failed: ${file} ${args.join(' ')}\\n${step.stderr ?? ''}`) as Error & {\n        code: number;\n        stdout: string;\n        stderr: string;\n        killed: boolean;\n      };\n      err.code = step.code;\n      err.stdout = step.stdout ?? '';\n      err.stderr = step.stderr ?? '';\n      err.killed = step.killed ?? false;\n      throw err;\n    }\n    if (step.killed) {\n      const err = new Error(`Command killed: ${file}`) as Error & { killed: boolean; signal: string };\n      err.killed = true;\n      err.signal = 'SIGTERM';\n      throw err;\n    }\n    return { stdout: step.stdout ?? '', stderr: step.stderr ?? '' };\n  }) as ScriptedExecRunner;\n  runner.calls = calls;\n  runner.remaining = () => queue.length;\n  return runner;\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@phone-use/sdk",
+  "version": "0.1.0",
+  "description": "Typed mobile-device SDK — Device, backends, errors, actions",
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rajmeet/phone-use.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.mts",
+      "bun": "./src/testing.ts",
+      "import": "./dist/testing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "agent-device": "0.19.3"
+  }
+}