@revyl/verify 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,15 +1,60 @@
 # Changelog
 
+## 0.3.0 (2026-10-31)
+
+- Sign in automatically on the first interactive `open()`, `attach()`, or `currentComputer()` call using the Revyl CLI browser-approval flow; CI remains key-only and browser-free.
+- Make `npx @revyl/verify init` install Verify, scaffold a project, sign in through the Revyl CLI browser approval flow when needed, and print the example command. Non-interactive runs use `REVYL_API_KEY` without prompting or opening a browser.
+- Add `currentComputer()`, Python `current_computer()` / `async_current_computer()`, and Go `CurrentComputer` to attach non-owning to `REVYL_COMPUTER_ID`, with explicit ownership opt-in and a typed error when no current computer is configured.
+- Add explicit non-owning computer attachment with `stopOnClose: false`, Python `stop_on_close=False`, and Go `OpenOptions.StopOnClose`. Closing these attachments still cleans up hosted children but leaves the computer running for its owner to release; the default remains owning.
+
+- Removed environment overrides.
+
+- **Breaking wire change:** encode computer-operation arguments as `argv_b64` and file paths as `path_b64` using padded URL-safe base64 of UTF-8, without changing public APIs, argument boundaries, or existing stdin/data fields. Verify 0.3.0 requires the encoded-only backend, which is already live on revyl.ai; no plaintext fallback or automatic replay is provided.
+
+- Classify HTTP 403 responses with a `text/html` content type and nonempty `cf-ray` as `EDGE_BLOCKED` across TypeScript, Go and Python, unless the body is syntactically valid JSON. Preserve origin authentication errors, omit response content from edge-block messages, and do not retry blocked requests.
+
+- Map hosted Web navigation `request_timeout` and `protocol_error` responses to `ACTION_UNCERTAIN` with safe reasons and HTTP status. Timeout messages explain that navigation may still commit and the session remains open; Verify never replays it.
+
+- Treat ordinary Web `409 web_runtime_unavailable` admission refusals as definite pre-dispatch failures: preserve `API_ERROR` plus safe reason/status details and do not send a stop request. Allocated or otherwise uncertain Web failures retain cleanup.
+
+- Bound parent computer cleanup's child phase to five seconds so slow child stops cannot prevent requesting parent release. Recognize `web_runtime_not_configured` as a definite hosted refusal, reject reports without a known session ID locally, preserve safe TypeScript startup diagnostics, and keep the original TypeScript `Session` interface compatible through the extended `OpenedSession` interface.
+
+- Add public computer attachment, computer-hosted child sessions and deterministic Web navigation in TypeScript, Go and Python. Child sessions reuse the parent's authenticated client and expire with it; parent close attempts bounded child cleanup before requesting computer release. Initial hosted Web builds remain HTTPS; localhost is reached by navigation after start, subject to runtime availability.
+- Preserve typed server refusal reasons and HTTP status alongside existing error codes, including Web `web_runtime_unavailable`, computer `computer_limit` and `runtime_unavailable`, without replaying starts or navigation.
+
+- Preserve Python startup session identity, viewer links and separate cleanup outcomes on typed errors; add optional lifecycle logging to sync/async opening. Clean up identifiable malformed or uncertain starts, interrupt cancelled async startup, validate device stop acknowledgments, and preserve original failures when cleanup also fails.
+
+- Prepare Python SDK 0.1.0 (`revyl-verify`, import `revyl_verify`) for Python ≥3.10, with typed sync and thread-adapted async sessions, seconds-based timeouts, web/mobile steps and early-access computer operations. Include fake-server coverage, wheel/sdist checks and an isolated installed-wheel smoke; Python has not been published or verified live. Its independent `py/v*` release workflow validates without publishing on dispatch, skips exact published versions, and requires administrator-enabled, protected-environment PyPI trusted publishing for new tag releases.
+
+- Add the source-free `revyl-verify` npm alias with matching API, TypeScript types and CLI, pinned to the exact `@revyl/verify` version. Validate and pack both packages; optional CI publication checks each version independently and publishes the scoped package before the alias.
+- Add a standard-library-only Go SDK for web, iOS, Android, and early-access Mac and Linux computers. Computer commands, binary files, process handles, screenshots, recording metadata, and confirmed-release cleanup require computer access through support@revyl.ai. Capacity refusals have a distinct `COMPUTER_LIMIT` code; no start or operation is automatically replayed.
+
+## 0.2.0
+
+Prepared for release; see npm for publication status.
+
+- Enable Linux named and inline computer targets with the shared Mac command, file, process, screenshot, and confirmed-release cleanup surface. Both operating systems remain early access; contact support@revyl.ai for access.
+- Add `COMPUTER_LIMIT` for queued work (including iOS) or concurrency admission refusals, without retrying or stopping a definitely refused start. Preserve `SESSION_BUSY` for operation limits.
+- Explain the 120-second unclaimed-start failure without shortening the default 10-minute start timeout.
+- Expose optional `expiresAt` and bound operation/screenshot observation by the hard 60-minute lifetime from create, while keeping explicit close possible.
+- Add computer `recording()` metadata retrieval after terminal state and confirmed release, including after close. Missing recordings return null; signed URLs remain private, with no automatic waiting or download.
+- Keep Linux CLI init intentionally unavailable; use inline targets or config entries. Computer instruction/validation remain locally unavailable.
+- Observe mobile first-screen content best-effort for up to 10 seconds after connection/launch, without pretending the runtime provides rendered-readiness guarantees. Generated mobile examples begin with an instruction to wait for the first screen before validation.
+- Retry structured computer screen-not-ready responses with bounded backoff during the fixed startup window; do not replay mutations or unrelated failures.
+- Skip CI publication when the exact version is already on npm, require explicit administrator opt-in for new CI publications, fail closed on registry lookup errors, and document manual Mac publication, optional trusted publishing, and independent Go module tags.
+
+Regression validation uses fake API responses. The [end-to-end record](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/end-to-end.md) distinguishes baseline live runs from startup fixes still awaiting live re-verification.
+
 ## 0.1.0
 
-Initial release preparation; this entry does not mean the package has been published.
+Published manually from a maintainer's Mac without provenance.
 
 - Open Revyl cloud web browsers, iOS simulators, and Android emulators from TypeScript.
 - Run natural-language instruction and validation steps, with typed failures and optional soft validation results.
 - Save screenshots, share session links, and close sessions explicitly or during best-effort process cleanup.
 - Configure named targets and initialize a script with the `verify` or `revyl-verify` command.
 - Use environment credentials or an existing Revyl CLI login, with documentation included in the package.
-- Include **early-access Mac computers, not yet available in Revyl production**, for commands, binary files, process handles, screenshots, and confirmed-release cleanup. Mac works only on Revyl staging for enabled organizations through the optional `REVYL_BACKEND_URL` override and matching credentials; ask support@revyl.ai about access.
+- Include **early-access Mac computers** for commands, binary files, process handles, screenshots, and confirmed-release cleanup. Ask support@revyl.ai about access.
 - Reserve Linux target types and document the future contract; opening Linux is not available in this release.
 
-Requires Node.js 22.18 or later and a Revyl account. There is no bundled test runner or step replay. Mac operations remain covered by source-aligned fake-API tests; a production start never reached active, so it did not prove any operation or confirmed cleanup.
+Requires Node.js 22.18 or later and a Revyl account. There is no bundled test runner or step replay. Mac operations remain covered by source-aligned fake-API tests; the attempted live start never reached active, so it did not prove any operation or confirmed cleanup.

package/README.md

@@ -1,101 +1,168 @@
 # Verify
 
-**Open cloud browsers and mobile devices for Revyl's agent, or a Mac computer for commands and files, from TypeScript.**
+Verify runs end-to-end checks in a real browser, iOS simulator, or Android emulator on Revyl. You describe what the agent should do and what must be true afterward, instead of maintaining selectors and coordinates that break when a screen changes. Use it from a script, a coding agent, or the test runner you already have. Mac and Linux computers are also available for commands, files, and screenshots, not natural-language steps.
+
+Every run gives you a link to watch the target. The session keeps its report and available recording, and the SDK keeps instruction and validation results in order. A failed check leaves evidence you can inspect.
+
+## Install and run
+
+```bash
+npm install @revyl/verify
+```
+
+Save this as `verify/check.ts`:
 
 ```ts
 import { open } from '@revyl/verify';
 
-const session = await open('ios');
-await session.instruction('Add the first product to the cart and open the cart');
-await session.validation('The cart lists one item with a price');
-await session.close();
+const session = await open({ platform: 'ios', app: { appId: 'YOUR_REVYL_APP_ID' } });
+try {
+  await session.instruction('Open General, then About');
+  await session.validation('The screen shows the operating system version');
+  await session.screenshot({ path: '.verify/about.png' });
+} finally {
+  await session.close();
+}
 ```
 
+Run the script:
+
 ```bash
-npx @revyl/verify init       # writes verify.config.ts and verify/example.ts
-node verify/example.ts       # opens the session, prints a link to watch it live, runs the steps
+node verify/check.ts
+```
+
+On the first interactive run, Verify opens the Revyl browser approval flow once and saves the login in `~/.revyl/credentials.json` for the CLI and SDK to share.
+
+Verify prints a live session URL and progress like this:
+
+```text
+[verify] ios: starting ios session https://app.revyl.ai/sessions/…
+[verify] ios: ready
+[verify] ios: ✓ instruction "Open General, then About" (12.0s)
+[verify] ios: ✓ validation "The screen shows the operating system version" (9.8s)
+[verify] ios: closed
 ```
 
-Verify is a small TypeScript library on top of [Revyl](https://revyl.com). Open a browser or mobile device for **instruction** and **validation** steps, or a Mac computer for commands, files, processes, and screenshots. It has no test framework of its own, so you call it from wherever you already write code:
+The URL is live during the run and keeps the report and available recording after it closes. A failed instruction or validation throws a typed error and includes the same URL. In CI, Verify never opens a browser: provide `REVYL_API_KEY` as a secret.
 
-- **A plain script.** A failed validation throws, the script exits non-zero, and Verify closes the session on the way out.
-- **A coding agent.** An agent can check its own change on a real device in five lines, then read a one-line outcome per step and a link to the recording.
-- **CI.** Run the script in a job. The browsers and devices run in Revyl's cloud, so the runner needs nothing but Node and an API key.
-- **Your test runner.** Call it inside node:test, Vitest, Jest, or Playwright Test, next to the tests you already have.
+For Web, use `open({ platform: 'web', app: { appId, url } })`; for a computer, use `open({ platform: 'mac' })`.
 
-## Quick start
+## Scaffold a config (optional)
 
-You need Node.js 22.18 or later and a Revyl account.
+Use `init` when you want named targets in `verify.config.ts` and a generated `verify/example.ts` script:
 
 ```bash
 npx @revyl/verify init
-npm install --save-dev @revyl/verify
-export REVYL_API_KEY=...          # or sign in with the Revyl CLI: revyl auth login
-node verify/example.ts
 ```
 
-Full walkthrough: [getting started](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/getting-started.md).
+`init` detects your package manager, asks before adding `@revyl/verify` as a dev dependency, creates `verify.config.ts` and `verify/example.ts`, and prints the command that runs the example. Use `--yes` to accept installation without a prompt, or `--no-install` when Verify is already installed. It is optional; installing the package is enough to use inline targets.
 
-## The API
+The generated project starts with a named target. Use `--platform web`, `--platform ios`, `--platform android`, or `--platform mac` when you want to skip the platform question. Web and mobile targets need a Revyl app id; a Mac target does not. The generated config is ordinary TypeScript, so edit it when the example needs a pinned build, a public Web URL, or a different target.
 
-| Call | What it does |
-| --- | --- |
-| `open(target)` | Starts a Revyl cloud browser, device, or Mac computer, from a target name in `verify.config.ts` or a target object, and waits until it is ready |
-| `session.exec(argv, options?)` | Runs structured argv on a Mac computer; returns `{ exitCode, stdout, stderr }` |
-| `session.readFile(path)`, `writeFile(path, data)`, `stat(path)` | Reads a `Buffer`, writes a string or bytes, or returns `{ kind, size }` on a computer |
-| `session.processes()`, `terminate(id)` | Lists run-owned process handles or terminates one on a computer |
-| `session.instruction(text)` | Revyl's agent does what the text says. Throws `INSTRUCTION_FAILED` if it cannot. |
-| `session.validation(text)` | Revyl's agent checks that the text holds on screen. Throws `VALIDATION_FAILED` if it does not, or returns the result with `{ soft: true }`. |
-| `session.screenshot({ path })` | A PNG of the screen |
-| `session.viewerUrl` | The session in Revyl: live while it runs, its recording after |
-| `session.close()` | Stops the session. Verify also closes open sessions on Ctrl+C, on an uncaught error, and when a script ends without closing. |
+See the [TypeScript getting-started guide](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/getting-started.md), the [Python SDK guide](https://github.com/RevylAI/verify/blob/v0.3.0/python/README.md), and the [Go SDK guide](https://github.com/RevylAI/verify/tree/go/v0.2.0/go).
 
-Revyl failures are `VerifyError`s with a stable code, a safe reason, and the session link when one exists.
+## CI
 
-## Platforms
+For a normal GitHub Actions job, install from the lockfile with `npm ci` and pass `REVYL_API_KEY` from repository secrets to the script that runs Verify:
 
-| | Web | iOS | Android | Mac | Linux |
-| --- | --- | --- | --- | --- | --- |
-| Runs on | Revyl cloud browser | Revyl iOS simulator | Revyl Android emulator | Revyl macOS computer | Contract only; open unavailable |
-| Opens | A public URL, or a web build in Revyl | A build in Revyl, a build URL, or an installed app | A build in Revyl, a build URL, or an installed app | A workspace, no app id | Nothing in this release |
-| `instruction`, `validation` | Yes | Yes | Yes | Unavailable | Unavailable |
-| Commands, files, processes | Unavailable | Unavailable | Unavailable | Early access on staging only for enabled organizations; not yet available in Revyl production | Contract only |
-| `screenshot`, `viewerUrl` | Yes | Yes | Yes | Yes | Unconfirmed |
+```yaml
+- uses: actions/checkout@v5
+- uses: actions/setup-node@v5
+  with:
+    node-version: 24
+    cache: npm
+- run: npm ci
+- run: node verify/example.ts
+  env:
+    REVYL_API_KEY: ${{ secrets.REVYL_API_KEY }}
+```
 
-Steps on web go through the same Revyl API as on mobile. Production is the default; optional environment overrides are documented in [web.md](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/web.md). A backend without web-step support returns `NOT_AVAILABLE_ON_PLATFORM`.
+On a `revyl-macos` job, `currentComputer()` attaches to the runner's existing computer without taking ownership. The runner releases the computer; closing the Verify attachment still cleans up hosted children. See the [CI guide](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/ci.md) and [computer API](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/api.md#inside-a-revyl-macos-github-actions-job).
 
-Each step runs Revyl's agent on the live session every time. Verify does not cache or replay steps, and Revyl does not carry values from one step to the next.
+## Reference authentication
 
-For a Mac workspace, run `npx @revyl/verify init --platform mac`; it generates a command and file-round-trip script with no app id or agent steps. Mac computers are early access and not yet available in Revyl production. They work only on Revyl staging for enabled organizations using the optional `REVYL_BACKEND_URL` override and matching credentials. Linux targets are typed but `open()` rejects them with `NOT_AVAILABLE_ON_PLATFORM` before credentials or network access. See [computers](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md#availability-and-errors) and the [Linux contract](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/linux-computers-contract.md).
+Use manual setup when you need to control the package manager or keep the generated files out of the project:
 
-## Docs
+```bash
+revyl auth login
+npx @revyl/verify whoami
+```
 
-- [Getting started](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/getting-started.md) and [API](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/api.md)
-- [Configuration and CLI](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/configuration.md)
-- [Web](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/web.md) and [iOS and Android](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/mobile.md)
-- [Mac computers](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md) and the [deferred Linux contract](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/linux-computers-contract.md)
-- [CI and test runners](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/ci.md) and [error codes](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/errors.md)
-- [For coding agents](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/agents.md)
+The SDK resolves credentials in this order: a usable stored CLI login marked `local_auth_override`, `REVYL_API_KEY`, then another usable stored CLI login. In CI, use a secret manager rather than putting a key in source, command arguments, or logs. `whoami` checks the credentials without starting a session.
 
-Examples: [web store](https://github.com/RevylAI/verify/tree/main/examples/web-store), [mobile settings](https://github.com/RevylAI/verify/tree/main/examples/mobile-settings), and [Mac workspace](https://github.com/RevylAI/verify/tree/main/examples/mac-workspace).
+## TypeScript
 
-## How it works
+```ts
+import { open } from '@revyl/verify';
 
-Verify is a client for [Revyl's public API](https://docs.revyl.com). `open()` starts a device session (registering a web URL as a build first when needed) and waits until it is ready. Each instruction or validation runs as a live step on the session: Verify submits it, polls its status until Revyl reports a result, and cancels it on Revyl if it runs past its timeout. `close()` stops the session. Requests identify themselves with `X-Revyl-Client: verify` and a `revyl-verify/<version>` user agent.
+const session = await open('ios');
+try {
+  await session.instruction('Open General, then About');
+  await session.validation('The screen shows the operating system version');
+} finally {
+  await session.close();
+}
+```
 
-For computers, `open()` creates a computer run and waits for its report to become active. Commands use request UUIDs and async operation polling without resubmitting mutations; `close()` stops the run. See [the computer transport](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md#lifecycle-and-transport).
+For Web, use a public HTTPS URL in the target config. For iOS and Android, point the target at an app or build in Revyl. The [API guide](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/api.md) covers target options, step results, screenshots, reports, and cleanup.
 
-## Develop
+## Go
 
-```bash
-npm install
-npm run build
-npm test          # unit tests against a mocked Revyl API; no account needed
-npm run typecheck
+Inside a function returning `error`, with a bounded `ctx`:
+
+```go
+session, err := verify.Open(ctx, verify.Target{Platform: verify.IOS, BundleID: "com.apple.Preferences"})
+if err != nil {
+    return err
+}
+defer func() { _ = session.Close(ctx) }()
+if _, err := session.Instruction(ctx, "Open General, then About"); err != nil {
+    return err
+}
+_, err = session.Validation(ctx, "The screen shows the operating system version")
+return err
+```
+
+Go calls return errors instead of throwing. The [Go reference](https://github.com/RevylAI/verify/tree/go/v0.2.0/go) covers context deadlines, screenshots, computer operations, and hosted sessions.
+
+## Python
+
+```python
+from revyl_verify import Target, open
+
+with open(Target(platform="ios", bundle_id="com.apple.Preferences")) as session:
+    session.instruction("Open General, then About")
+    session.validation("The screen shows the operating system version")
 ```
 
-The library lives in [`packages/verify`](https://github.com/RevylAI/verify/tree/main/packages/verify) and the examples in [`examples/`](https://github.com/RevylAI/verify/tree/main/examples). Read [Contributing](https://github.com/RevylAI/verify/blob/main/CONTRIBUTING.md), [Security](https://github.com/RevylAI/verify/blob/main/SECURITY.md), and [Releasing](https://github.com/RevylAI/verify/blob/main/RELEASING.md) before changing or publishing the package.
+Python supports synchronous and asyncio APIs, but it has no bundled CLI. The [Python reference](https://github.com/RevylAI/verify/blob/v0.3.0/python/README.md) covers both APIs and computer operations.
+
+## Platforms
+
+| Platform | Instructions / validations | Commands / files / processes | PNG screenshot |
+| --- | :---: | :---: | :---: |
+| Web | Yes | — | Yes |
+| iOS simulator | Yes | — | Yes |
+| Android emulator | Yes | — | Yes |
+| Mac computer | — | Yes | Yes |
+| Linux computer | — | Yes | Yes |
+
+Computer targets are early access and use commands, files, processes, and screenshots rather than natural-language agent steps. They have a server-bounded lifetime. See [computer setup](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/computers.md).
+
+## Documentation
+
+- [Documentation index](https://github.com/RevylAI/verify/tree/v0.3.0/packages/verify/docs/) · [API](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/api.md) · [CI](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/ci.md) · [Coding agents](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/agents.md)
+- [End-to-end results and limitations](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/end-to-end.md)
+- [Examples](https://github.com/RevylAI/verify/tree/v0.3.0/examples/): [Web store](https://github.com/RevylAI/verify/tree/v0.3.0/examples/web-store/) · [Mobile Settings](https://github.com/RevylAI/verify/tree/v0.3.0/examples/mobile-settings/) · [Mac workspace](https://github.com/RevylAI/verify/tree/v0.3.0/examples/mac-workspace/)
+- [Contributing](https://github.com/RevylAI/verify/blob/v0.3.0/CONTRIBUTING.md) · [Security](https://github.com/RevylAI/verify/blob/v0.3.0/SECURITY.md) · [Releasing](https://github.com/RevylAI/verify/blob/v0.3.0/RELEASING.md)
+
+## Troubleshooting
+
+- **`NOT_AVAILABLE_ON_PLATFORM`:** the requested method is not available for that target. Computer targets do not run instruction or validation steps; Web and mobile targets do not expose computer commands or files.
+- **`COMPUTER_LIMIT`:** computer admission was refused because of queued work or a concurrency limit. Verify does not retry creation or stop a definitely refused start.
+- **Blank first screen:** mobile startup uses a bounded, best-effort blank-frame observation, not a rendered-readiness guarantee. Begin with an instruction that reaches the screen your workflow needs.
+- **A validation report looks successful but the assertion failed:** inspect each step's `effective_status` and `validation_result`, and compare `validations_passed` with `total_validations` rather than transport counters.
 
 ## License
 
-[Apache 2.0](https://github.com/RevylAI/verify/blob/main/LICENSE)
+[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.3.0/LICENSE).

package/dist/api/client.d.ts

@@ -1,4 +1,4 @@
-import { VerifyError } from '../errors.js';
+import { VerifyError, type RefusalReason } from '../errors.js';
 import type { AppResponse, BuildResponse, DeviceSessionDetail, DeviceSessionStopResponse, StartDeviceRequest, StartDeviceResponse, WhoAmI, WorkerConnection } from './types.js';
 export declare const DEFAULT_BACKEND_URL = "https://backend.revyl.ai";
 export declare const DEFAULT_APP_URL = "https://app.revyl.ai";
@@ -34,7 +34,7 @@ export declare class RevylClient {
     startDevice(request: StartDeviceRequest, signal?: AbortSignal): Promise<StartDeviceResponse>;
     getDeviceSession(sessionId: string, signal?: AbortSignal): Promise<DeviceSessionDetail>;
     getWorkerConnection(workflowRunId: string, signal?: AbortSignal): Promise<WorkerConnection>;
-    stopDeviceSession(sessionId: string): Promise<DeviceSessionStopResponse>;
+    stopDeviceSession(sessionId: string, retry?: boolean): Promise<DeviceSessionStopResponse>;
     cancelDevice(workflowRunId: string): Promise<unknown>;
     getApp(appId: string, signal?: AbortSignal): Promise<AppResponse>;
     registerWebUrlBuild(appId: string, request: {
@@ -55,9 +55,11 @@ export declare class RevylClient {
     }): Promise<RawResponse>;
     private sendOnce;
 }
-export declare function appUrl(): string;
-export declare function sessionViewerUrl(sessionId: string, kind?: 'computer'): string;
+export declare function appUrl(origin?: string): string;
+export declare function sessionViewerUrl(sessionId: string, kind?: 'computer', origin?: string): string;
 export declare function parseJson<T>(response: RawResponse, what: string): T;
 export declare function responseDetail(response: RawResponse): string | undefined;
 export declare function responseErrorCode(response: RawResponse): string | undefined;
 export declare function apiError(method: string, path: string, response: RawResponse): VerifyError;
+export declare function edgeBlockedError(response: RawResponse): VerifyError | undefined;
+export declare function responseRefusalReason(response: RawResponse): RefusalReason | undefined;

package/dist/api/client.js

@@ -15,7 +15,7 @@ export class RevylClient {
     requestTimeoutMs;
     constructor(options) {
         this.token = options.token;
-        this.backendUrl = validateBackendUrl(options.backendUrl ?? process.env.REVYL_BACKEND_URL ?? DEFAULT_BACKEND_URL);
+        this.backendUrl = validateBackendUrl(options.backendUrl ?? DEFAULT_BACKEND_URL);
         this.fetchImpl = options.fetch ?? fetch;
         this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     }
@@ -55,8 +55,8 @@ export class RevylClient {
     getWorkerConnection(workflowRunId, signal) {
         return this.json('GET', `/api/v1/execution/streaming/worker-connection/${encodeURIComponent(workflowRunId)}`, { signal });
     }
-    stopDeviceSession(sessionId) {
-        return this.json('POST', `/api/v1/execution/device/sessions/${encodeURIComponent(sessionId)}/stop`, { retry: true });
+    stopDeviceSession(sessionId, retry = true) {
+        return this.json('POST', `/api/v1/execution/device/sessions/${encodeURIComponent(sessionId)}/stop`, { retry });
     }
     cancelDevice(workflowRunId) {
         return this.json('POST', `/api/v1/execution/device/status/cancel/${encodeURIComponent(workflowRunId)}`, { retry: true });
@@ -127,11 +127,12 @@ export class RevylClient {
         }
     }
 }
-export function appUrl() {
-    return (process.env.REVYL_APP_URL ?? DEFAULT_APP_URL).replace(/\/+$/, '');
+export function appUrl(origin = DEFAULT_APP_URL) {
+    validateBackendUrl(origin, 'viewer');
+    return origin.replace(/\/+$/, '');
 }
-export function sessionViewerUrl(sessionId, kind) {
-    return `${appUrl()}/sessions/${encodeURIComponent(sessionId)}${kind ? `?kind=${kind}` : ''}`;
+export function sessionViewerUrl(sessionId, kind, origin) {
+    return `${appUrl(origin)}/sessions/${encodeURIComponent(sessionId)}${kind ? `?kind=${kind}` : ''}`;
 }
 export function parseJson(response, what) {
     try {
@@ -175,27 +176,76 @@ export function responseErrorCode(response) {
     }
 }
 export function apiError(method, path, response) {
-    const detail = responseDetail(response);
+    const blocked = edgeBlockedError(response);
+    if (blocked)
+        return blocked;
+    const detail = path === '/api/v1/execution/start_device' ? responseKnownDetail(response, START_ERROR_DETAILS) : responseDetail(response);
     const suffix = detail ? `: ${detail}` : '';
     if (response.status === 401 || response.status === 403) {
-        return new VerifyError('AUTH_REJECTED', `Revyl rejected the request ${method} ${path} (HTTP ${response.status})${suffix}. Check REVYL_API_KEY or run 'revyl auth login'.`);
+        return new VerifyError('AUTH_REJECTED', `Revyl rejected the request ${method} ${path} (HTTP ${response.status})${suffix}. Check REVYL_API_KEY or run 'revyl auth login'.`, { reason: responseRefusalReason(response), httpStatus: response.status });
     }
-    return new VerifyError('API_ERROR', `Revyl request ${method} ${path} failed with HTTP ${response.status}${suffix}`);
+    return new VerifyError('API_ERROR', `Revyl request ${method} ${path} failed with HTTP ${response.status}${suffix}`, { reason: responseRefusalReason(response), httpStatus: response.status });
 }
-function validateBackendUrl(raw) {
+export function edgeBlockedError(response) {
+    if (response.status !== 403 || response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'text/html' || !response.headers.get('cf-ray')?.trim())
+        return undefined;
+    try {
+        JSON.parse(new TextDecoder().decode(response.body));
+        return undefined;
+    }
+    catch { }
+    return new VerifyError('EDGE_BLOCKED', 'Revyl request was blocked at the network edge (HTTP 403). Check network access or contact support. Verify will not retry this request.', { httpStatus: response.status });
+}
+const REFUSAL_REASONS = new Set([
+    'web_runtime_unavailable', 'web_runtime_not_configured', 'computer_limit', 'runtime_unavailable', 'computer_runtime_unavailable',
+    'computer_at_capacity', 'computer_not_running', 'computer_cannot_host_platform', 'computer_not_found',
+    'web_build_required', 'web_build_not_supported', 'ios_build_required', 'ios_build_not_supported',
+    'android_build_required', 'android_build_not_supported', 'web_session_conflict', 'ios_session_conflict',
+    'android_session_conflict', 'not_available_on_platform', 'request_timeout', 'protocol_error',
+]);
+const START_ERROR_DETAILS = new Set([
+    ...REFUSAL_REASONS,
+    'web_start_actor_invalid', 'web_app_required', 'web_app_not_found', 'web_idle_timeout_invalid',
+    'web_preview_overrides_unsupported', 'web_env_override_invalid', 'web_env_override_secret',
+    'web_sign_in_config_invalid', 'web_sign_in_override_not_secret', 'web_env_overrides_not_supported',
+    'web_build_selection_invalid', 'web_build_not_found', 'web_build_invalid', 'web_billing_not_configured',
+    'web_concurrency_unavailable', 'web_worker_unavailable', 'web_session_fence_conflict',
+    'web_callback_conflict', 'web_start_in_progress', 'web_start_unconfirmed', 'web_session_inputs_unavailable',
+    'sign_in_secret_not_found', 'sign_in_secret_unavailable', 'proof_sign_in_not_configured',
+]);
+export function responseRefusalReason(response) {
+    return responseKnownDetail(response, REFUSAL_REASONS);
+}
+function responseKnownDetail(response, codes) {
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(response.body));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        const record = parsed;
+        const values = [record.detail];
+        if (record.detail && typeof record.detail === 'object')
+            values.push(record.detail.error);
+        values.push(record.error);
+        return values.find((value) => typeof value === 'string' && codes.has(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+function validateBackendUrl(raw, label = 'backend') {
     let url;
     try {
         url = new URL(raw);
     }
     catch {
-        throw new VerifyError('CONFIG_INVALID', 'REVYL_BACKEND_URL is not a valid URL.');
+        throw new VerifyError('CONFIG_INVALID', `The ${label} URL is not a valid URL.`);
     }
     const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
     if (url.protocol !== 'https:' && !(loopback && url.protocol === 'http:')) {
-        throw new VerifyError('CONFIG_INVALID', 'REVYL_BACKEND_URL must use HTTPS (plain HTTP is allowed only on loopback).');
+        throw new VerifyError('CONFIG_INVALID', `The ${label} URL must use HTTPS (plain HTTP is allowed only on loopback).`);
     }
     if (url.username || url.password || url.search || url.hash) {
-        throw new VerifyError('CONFIG_INVALID', 'REVYL_BACKEND_URL must be an origin without credentials, query, or fragment.');
+        throw new VerifyError('CONFIG_INVALID', `The ${label} URL must be an origin without credentials, query, or fragment.`);
     }
     return url.origin;
 }

package/dist/api/types.d.ts

@@ -15,6 +15,7 @@ export interface StartDeviceRequest {
     platform: MobilePlatform | 'web';
     is_simulation?: boolean;
     session_id?: string;
+    computer_session_id?: string;
     app_id?: string;
     build_id?: string;
     app_url?: string;
@@ -130,6 +131,12 @@ export interface ComputerReport {
     state: ComputerState;
     release: 'pending' | 'confirmed' | 'unknown';
     failure_reason?: string | null;
+    expires_at?: string | null;
+}
+export interface ComputerRecordingResponse {
+    url: string;
+    duration_seconds?: number | null;
+    started_at?: string | null;
 }
 export interface ComputerProcessHandle {
     computer_session_id: string;

package/dist/cli/init.js

@@ -8,7 +8,7 @@ const CONFIG_FILE = 'verify.config.ts';
 const EXAMPLE_SCRIPT = join('verify', 'example.ts');
 export function validateInitAnswers(answers) {
     if (!['web', 'ios', 'android', 'mac'].includes(answers.platform)) {
-        throw new VerifyError('INVALID_ARGUMENT', "--platform must be 'web', 'ios', 'android', or 'mac'. Linux computers are not available yet.");
+        throw new VerifyError('INVALID_ARGUMENT', "--platform must be 'web', 'ios', 'android', or 'mac'. Linux init is unavailable; use open({ platform: 'linux' }) or a Linux config target.");
     }
     if (answers.platform === 'mac' && answers.appId !== undefined) {
         throw new VerifyError('INVALID_ARGUMENT', '--app-id does not apply to Mac computers.');
@@ -101,8 +101,7 @@ try {
     const steps = platform === 'web'
         ? `await session.instruction('Follow the link on the page');
 await session.validation('A page about domains reserved for documentation is shown');`
-        : `// Describe what a person would do and see, for example:
-// await session.instruction('Sign in as the demo user and open Settings');
+        : `await session.instruction('Wait for the app to finish opening and show its first screen');
 await session.validation('The app has opened and shows its first screen without an error');`;
     return `import { open } from '${PACKAGE_NAME}';
 

package/dist/cli/install.d.ts

@@ -0,0 +1,2 @@
+export declare function packageHasVerify(cwd: string): Promise<boolean>;
+export declare function installVerify(cwd: string): Promise<void>;

package/dist/cli/install.js

@@ -0,0 +1,64 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { VerifyError } from '../errors.js';
+import { PACKAGE_NAME } from '../version.js';
+export async function packageHasVerify(cwd) {
+    let raw;
+    try {
+        raw = await readFile(join(cwd, 'package.json'), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw new VerifyError('CONFIG_INVALID', 'Could not read package.json.', { cause: error });
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(raw);
+    }
+    catch {
+        throw new VerifyError('CONFIG_INVALID', 'package.json is not valid JSON.');
+    }
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest))
+        throw new VerifyError('CONFIG_INVALID', 'package.json must contain an object.');
+    return ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'].some((field) => {
+        const dependencies = manifest[field];
+        return dependencies && typeof dependencies === 'object' && !Array.isArray(dependencies) && Object.hasOwn(dependencies, PACKAGE_NAME);
+    });
+}
+export async function installVerify(cwd) {
+    const manager = detectPackageManager(cwd);
+    if (!existsSync(join(cwd, 'package.json')))
+        await writeFile(join(cwd, 'package.json'), '{\n  "private": true,\n  "type": "module"\n}\n', { flag: 'wx' });
+    const args = manager === 'npm'
+        ? ['install', '--save-dev', '--ignore-scripts']
+        : manager === 'yarn'
+            ? ['add', '--dev', '--mode=skip-builds']
+            : ['add', '--dev', '--ignore-scripts'];
+    args.push(PACKAGE_NAME);
+    process.stdout.write(`Installing ${PACKAGE_NAME} with ${manager}...\n`);
+    await new Promise((resolve, reject) => {
+        const env = Object.fromEntries(['PATH', 'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP'].flatMap((key) => {
+            const value = process.env[key];
+            return value === undefined ? [] : [[key, value]];
+        }));
+        const child = spawn(manager, args, { cwd, env, stdio: 'inherit', shell: process.platform === 'win32', timeout: 180_000, killSignal: 'SIGKILL' });
+        const fail = () => reject(new VerifyError('CONFIG_INVALID', `Could not install ${PACKAGE_NAME} with ${manager}. Install it manually, then retry init --no-install.`));
+        child.once('error', fail);
+        child.once('exit', (code) => code === 0 ? resolve() : fail());
+    });
+}
+function detectPackageManager(cwd) {
+    const lockfiles = [['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun'], ['package-lock.json', 'npm'], ['npm-shrinkwrap.json', 'npm']];
+    for (let directory = cwd;; directory = dirname(directory)) {
+        const managers = [...new Set(lockfiles.filter(([file]) => existsSync(join(directory, file))).map(([, manager]) => manager))];
+        if (managers.length > 1)
+            throw new VerifyError('CONFIG_INVALID', 'Found lockfiles for multiple package managers. Keep the project lockfile and retry init.');
+        if (managers[0])
+            return managers[0];
+        if (dirname(directory) === directory)
+            return 'npm';
+    }
+}

package/dist/cli/login.d.ts

@@ -0,0 +1,6 @@
+import { type Credentials } from '../auth.js';
+export declare function signIn(options?: {
+    force?: boolean;
+    backendUrl?: string;
+    appUrl?: string;
+}): Promise<Credentials>;