TypeScript SDK

The phonebox npm package is a typed client for the REST API. It runs on Node.js 20 or later, is published as an ES module, and depends only on zod. The same package contains the CLI.

InstallCopy Anchor Link

npm install https://phonebox.dev/downloads/phonebox-0.1.0.tgz

The package includes its type definitions. Import it with import, because it has no CommonJS build.

Quick exampleCopy Anchor Link

import { Phonebox, PhoneboxError } from "phonebox";

const pb = new Phonebox(); // reads PHONEBOX_API_KEY
const key = `signup-test-${Date.now()}`; // a new key for each phone; reuse it only to repeat this create
const phone = await pb.phones.create({ name: "signup-test", idempotencyKey: key });
try {
  if (phone.status !== "ready") await phone.waitUntil("ready"); // create() returns the phone even when its wait was cut short
  console.log(await phone.look());
  await phone.tap({ text: "Sign in" });
  await phone.tap({ id: "email" });
  await phone.type("alex@example.com", { submit: true });
  await phone.waitFor({ text: "Welcome" }, { timeoutMs: 20_000 });
} catch (error) {
  if (error instanceof PhoneboxError) console.error(error.code, error.next);
  throw error;
} finally {
  await phone.park();
}

The clientCopy Anchor Link

new Phonebox(options) takes these options, all of them optional:

Without a key, the constructor throws a PhoneboxError with the code missing_api_key.

The SDK names options in camelCase, such as idleTimeout and maxDuration, and it sends them as the API's snake_case fields. Timers are in seconds and timeoutMs values in milliseconds. Actions and targets keep the API's own field names, such as timeout_ms and snapshot_id. So do the objects the SDK returns, except that pb.phones.list() names its cursor nextCursor.

A phoneCopy Anchor Link

A Phone holds the phone's latest state in phone.data, with phone.id and phone.status as shortcuts. Lifecycle methods refresh data, and screen and action methods leave it as it is. Call refresh() to read the phone again.

LifecycleCopy Anchor Link

The screenCopy Anchor Link

ActionsCopy Anchor Link

act(actions, { observe }) runs a batch of actions and returns the batch result. It doesn't throw when an action fails, so check completed and each result's ok. It throws only when the request as a whole fails.

const result = await phone.act(
  [
    { type: "tap", target: { text: "Search apps" } },
    { type: "type", text: "chrome" },
  ],
  { observe: "ui" },
);
if (result.completed < 2) console.log(result.results.at(-1)?.error);

These methods each send one action, and they throw a PhoneboxError when it fails:

A target is an object in one of the target forms, such as { text: "Sign in" } or { ref: 3, snapshot_id: "snp_4f2k7m3q6z3a" }.

Apps, files and the deviceCopy Anchor Link

ErrorsCopy Anchor Link

An error that the API reports is a PhoneboxError, carrying the API's error envelope:

When a single-action method such as tap() fails, the error carries the action's code with that code's usual HTTP status, so a phone_unavailable has the status 503 and a target_not_found 422.

An answer without the envelope, such as a gateway's 504, becomes a PhoneboxError with the code internal_error, that status and retryable set to false. Only an answer that carries an X-Request-Id header is read as Phonebox's envelope, so a proxy's JSON error, whatever it says, is reported this way too. A network error or a timeout is thrown as the error that fetch gave, such as a TypeError or a TimeoutError. After either on a write, such as act() or tap(), the write may have happened: observe before you send it again.

Retries and waitingCopy Anchor Link

• A GET that fails with a network error, a timeout, or the status 429, 502, 503 or 504 is sent up to twice more, after a quarter and then half a second.
• A POST, PUT, PATCH or DELETE is sent only once, so the SDK never repeats an action or a create. Pass idempotencyKey to create() so that you can repeat a create yourself safely.
• create(), start() and park() send their request, which itself waits up to about 50 seconds, and then poll GET /v1/phones/{id}?wait=… in requests of about 50 seconds each, until the phone gets there or timeoutMs passes after that first answer. When the time runs out, start(), park() and waitUntil() throw a PhoneboxError with the code wait_timeout and the status 422, which is retryable and names the phone in details.phone. create() returns the phone instead, as it was last seen.
• A wait stops at once when the phone lands where it can't get there without a new request. A phone that failed, or was deleted, makes it throw with the failure's code, retryable set to false, and a next that says to create a new phone with a new idempotency key. A start that fails and leaves the phone parked again throws with the failure's code too, but keeps the code's usual retryable, because the same phone can start again. A phone that someone else parked makes a wait for ready throw phone_not_running, whose next is the start request.
• A poll that answers at once without reaching the status waits before the next one: 1 second, doubling to 10.
• Each HTTP request gives up after 130 seconds, except a batch of actions, from act() or a single-action method, which waits up to 310 seconds: a little longer than the 300 seconds a request may run at the platform, so the batch's own answer arrives first.