@revyl/verify 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,14 +1,39 @@
 # Changelog
 
-## Unreleased
+## 0.3.0 (2026-10-31)
 
-- 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 an enabled staging organization and are not yet available in production. Capacity refusals have a distinct `COMPUTER_LIMIT` code; no start or operation is automatically replayed.
+- 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 on staging for enabled organizations/OSes, not yet available in production.
+- 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.
@@ -29,7 +54,7 @@ Published manually from a maintainer's Mac without provenance.
 - 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,78 +1,100 @@
-<h1 align="center">Verify</h1>
+# Verify
 
-<p align="center">
-  <em>Cloud browsers, mobile devices and computers from TypeScript and Go.</em>
-</p>
+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.
 
-<p align="center">
-  <a href="https://github.com/RevylAI/verify/blob/v0.2.0/CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.2.0-9D61FF" alt="Source version" /></a>
-  <a href="https://github.com/RevylAI/verify/blob/v0.2.0/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0" /></a>
-  <a href="https://www.npmjs.com/package/@revyl/verify"><img src="https://img.shields.io/npm/v/@revyl/verify?color=9D61FF" alt="npm" /></a>
-  <a href="https://pkg.go.dev/github.com/RevylAI/verify/go"><img src="https://img.shields.io/badge/Go-reference-00ADD8?logo=go&logoColor=white" alt="Go reference" /></a>
-  <a href="https://github.com/RevylAI/verify/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/RevylAI/verify/ci.yml?branch=main&label=CI" alt="CI" /></a>
-</p>
+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
 
-Verify is a TypeScript and Go library for [Revyl](https://revyl.com). Open a cloud browser, iOS simulator or Android emulator for natural-language instructions and validations, or an early-access Mac/Linux computer for commands, files, processes and screenshots. Call it from a script, coding agent or your existing test runner.
+```bash
+npm install @revyl/verify
+```
 
-## For coding agents
+Save this as `verify/check.ts`:
 
-Run these from the project's directory with Node.js ≥22.18. The authentication command requires the [Revyl CLI](https://github.com/RevylAI/revyl-cli#install); if `REVYL_API_KEY` is already supplied securely, skip login.
+```ts
+import { open } from '@revyl/verify';
 
-```bash
-npm install --save-dev @revyl/verify
-npx @revyl/verify init --platform ios
-revyl auth login
-npx @revyl/verify whoami
+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();
+}
 ```
 
-If login prints an approval URL, share it privately with the user so they can approve it in their browser. For unattended runs, supply `REVYL_API_KEY` through a secret manager; never put credentials in argv, source or logs. Configure the generated `verify.config.ts` before running `node verify/example.ts`. Starting a cloud session requires an authorized account and workload.
+Run the script:
 
-## Install
+```bash
+node verify/check.ts
+```
 
-### npm
+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.
 
-Use Node.js ≥22.18:
+Verify prints a live session URL and progress like this:
 
-```bash
-npm install --save-dev @revyl/verify
+```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
 ```
 
-### Go
+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.
 
-Use Go ≥1.26.9 in an existing Go module:
+For Web, use `open({ platform: 'web', app: { appId, url } })`; for a computer, use `open({ platform: 'mac' })`.
+
+## Scaffold a config (optional)
+
+Use `init` when you want named targets in `verify.config.ts` and a generated `verify/example.ts` script:
 
 ```bash
-go get github.com/RevylAI/verify/go@main
+npx @revyl/verify init
 ```
 
-There is no Go release tag yet. `@main` resolves to a pseudo-version; keep the generated `go.mod` and `go.sum` to pin it. Go tags are independent of npm versions. The SDK uses only the standard library.
+`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.
 
-## Authenticate
+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.
 
-Both SDKs use this credential order:
+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).
 
-1. A usable stored CLI login marked `local_auth_override`.
-2. `REVYL_API_KEY` from the environment.
-3. Another usable CLI login stored by `revyl auth login`.
+## CI
 
-An expired access token can fall back to its stored API key. Set environment keys through a secret manager, or sign in interactively:
+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:
 
-```bash
-revyl auth login
+```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 }}
 ```
 
-See [configuration](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/configuration.md) for credential and endpoint options.
+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).
 
-## Quick Start
+## Reference authentication
+
+Use manual setup when you need to control the package manager or keep the generated files out of the project:
+
+```bash
+revyl auth login
+npx @revyl/verify whoami
+```
 
-### TypeScript
+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.
 
-Run `npx @revyl/verify init --platform ios`. For this Settings example, replace the generated `app` block with `app: { bundleId: 'com.apple.Preferences' }`. Save the following as `verify/example.ts` and run `node verify/example.ts`. For your own uploaded app, set `app.appId` and adapt the steps.
+## TypeScript
 
 ```ts
 import { open } from '@revyl/verify';
+
 const session = await open('ios');
 try {
   await session.instruction('Open General, then About');
@@ -82,22 +104,18 @@ try {
 }
 ```
 
-For web, use `init --platform web` with a Revyl web app ID and public HTTPS URL. See [getting started](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/getting-started.md).
+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.
 
-### Go
+## Go
 
-Inside a function returning `error`, with a bounded `ctx` and imports for `context`, `time`, and `verify "github.com/RevylAI/verify/go"`:
+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() {
-    cleanup, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-    defer cancel()
-    _ = session.Close(cleanup)
-}()
+defer func() { _ = session.Close(ctx) }()
 if _, err := session.Instruction(ctx, "Open General, then About"); err != nil {
     return err
 }
@@ -105,34 +123,46 @@ _, err = session.Validation(ctx, "The screen shows the operating system version"
 return err
 ```
 
-This sketch ignores cleanup errors; the [complete Go examples](https://github.com/RevylAI/verify/blob/v0.2.0/go/README.md) handle them. Go has no process-exit handlers. TypeScript's automatic cleanup is best effort, bounded to 15 seconds, and skips signal/error handlers that already have listeners. Always close explicitly: device close acknowledges a stop request; computer close requires terminal state and confirmed release.
+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")
+```
+
+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
+## Platforms
 
-| Platform | Instructions / validations | Commands / files / processes | PNG screenshot | Availability |
-| --- | :---: | :---: | :---: | --- |
-| Web | Yes | — | Yes | Production; selected backend must support web steps |
-| iOS simulator | Yes | — | Yes | Production |
-| Android emulator | Yes | — | Yes | Production |
-| Mac computer | — | Yes | Yes | Staging-only early access; not in production |
-| Linux computer | — | Yes | Yes | Staging-only early access; not in production |
+| 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 |
 
-Computers require enablement for your organization and requested OS, plus approved `REVYL_BACKEND_URL`, matching `REVYL_APP_URL` and credentials. They have a hard 60-minute lifetime from create. Mac supports `init --platform mac`; Linux init is unavailable, so use `open({ platform: 'linux' })` or a config target. See [computers](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/computers.md).
+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.2.0/packages/verify/docs/) · [API](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/api.md) · [CI](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/ci.md) · [Coding agents](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/agents.md)
-- [End-to-end results and limitations](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/end-to-end.md)
-- [Examples](https://github.com/RevylAI/verify/tree/v0.2.0/examples/): [Web store](https://github.com/RevylAI/verify/tree/v0.2.0/examples/web-store/) · [Mobile Settings](https://github.com/RevylAI/verify/tree/v0.2.0/examples/mobile-settings/) · [Mac workspace](https://github.com/RevylAI/verify/tree/v0.2.0/examples/mac-workspace/) · [Go](https://github.com/RevylAI/verify/blob/v0.2.0/go/README.md)
-- [Contributing](https://github.com/RevylAI/verify/blob/v0.2.0/CONTRIBUTING.md) · [Security](https://github.com/RevylAI/verify/blob/v0.2.0/SECURITY.md) · [Releasing](https://github.com/RevylAI/verify/blob/v0.2.0/RELEASING.md)
+- [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`:** computer agent steps and device command/file methods are unavailable. Computers also need staging enablement; web steps need backend support. Check the [platform contract](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/errors.md).
-- **`COMPUTER_LIMIT`:** admission was refused because of queued work or a concurrency limit. Wait for capacity; Verify does not retry creation or stop a definitely refused start.
-- **Blank first screen:** mobile startup makes a bounded, best-effort blank-frame observation, not a rendered/foreground-readiness guarantee. Begin with an instruction that reaches the screen you need. Computer capture retries structured startup screen-not-ready responses for a fixed 30-second window; Linux screenshot retry is tests-only, not proven live.
-- **A report's counters look successful but validation failed:** inspect `effective_status`, `validation_result` and `validations_passed` against `total_validations`, not transport counts. Failed SDK validations throw by default. See [reading the verdict](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/end-to-end.md#reading-the-verdict).
+- **`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/v0.2.0/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;

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>;