@revyl/verify 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## Unreleased
+
+- 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.
+
+## 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.
+- 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
+
+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.
+- 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.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+<h1 align="center">Verify</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <em>Cloud browsers, mobile devices and computers from TypeScript and Go.</em>
+</p>
+
+<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>
+
+---
+
+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.
+
+## For coding agents
+
+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.
+
+```bash
+npm install --save-dev @revyl/verify
+npx @revyl/verify init --platform ios
+revyl auth login
+npx @revyl/verify whoami
+```
+
+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.
+
+## Install
+
+### npm
+
+Use Node.js ≥22.18:
+
+```bash
+npm install --save-dev @revyl/verify
+```
+
+### Go
+
+Use Go ≥1.26.9 in an existing Go module:
+
+```bash
+go get github.com/RevylAI/verify/go@main
+```
+
+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.
+
+## Authenticate
+
+Both SDKs use this credential order:
+
+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`.
+
+An expired access token can fall back to its stored API key. Set environment keys through a secret manager, or sign in interactively:
+
+```bash
+revyl auth login
+```
+
+See [configuration](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/configuration.md) for credential and endpoint options.
+
+## Quick Start
+
+### TypeScript
+
+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.
+
+```ts
+import { open } from '@revyl/verify';
+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 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).
+
+### Go
+
+Inside a function returning `error`, with a bounded `ctx` and imports for `context`, `time`, and `verify "github.com/RevylAI/verify/go"`:
+
+```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)
+}()
+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
+```
+
+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.
+
+### 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 |
+
+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).
+
+## 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)
+
+## 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).
+
+## License
+
+[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.2.0/LICENSE).

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security
+
+## Reporting a vulnerability
+
+Email **support@revyl.ai** with the subject “Verify security report”. Do not open a public issue for a vulnerability or include API keys, session tokens, customer data, or screenshots containing sensitive information. Share a minimal reproduction with placeholders and affected versions; arrange a private channel before sending sensitive evidence.
+
+The maintainers review reports and coordinate fixes and disclosure. No response-time commitment is promised. Before the first release, report against the current source revision; afterward, security fixes target the latest published version.
+
+## Safe use
+
+Verify starts paid remote sessions and can act on your application. Use test accounts and non-production data, explicitly authorize each workload, and close sessions in `finally`. Automatic shutdown is best effort and cannot run after a forced kill. Keep credentials in environment variables or the Revyl CLI credential store, not in source or config. Step descriptions are sent to Revyl and printed to stderr by default; do not embed private credentials or customer data in them. Treat screenshots and session reports as potentially sensitive.
+
+Only install the package name documented in the README. The unscoped npm package named `verify` is unrelated; outside an installation, use `npx @revyl/verify`, not `npx verify`.

package/dist/api/client.d.ts

@@ -0,0 +1,63 @@
+import { VerifyError } 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";
+/** Sent on every request so Revyl can attribute sessions that Verify starts. */
+export declare const CLIENT_HEADER_VALUE = "verify";
+export interface RevylClientOptions {
+    token: string;
+    backendUrl?: string;
+    fetch?: typeof fetch;
+    requestTimeoutMs?: number;
+}
+export interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | string[] | undefined>;
+    timeoutMs?: number;
+    retry?: boolean;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+export interface RawResponse {
+    status: number;
+    headers: Headers;
+    body: Uint8Array;
+}
+export declare class RevylClient {
+    readonly backendUrl: string;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    constructor(options: RevylClientOptions);
+    send(method: 'GET' | 'POST', path: string, options?: RequestOptions): Promise<RawResponse>;
+    json<T>(method: 'GET' | 'POST', path: string, options?: RequestOptions): Promise<T>;
+    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>;
+    cancelDevice(workflowRunId: string): Promise<unknown>;
+    getApp(appId: string, signal?: AbortSignal): Promise<AppResponse>;
+    registerWebUrlBuild(appId: string, request: {
+        url: string;
+        branch_name?: string;
+    }, signal?: AbortSignal): Promise<BuildResponse>;
+    latestWebBuild(appId: string, branch: {
+        branchId?: string;
+        branchName?: string;
+    }, signal?: AbortSignal): Promise<BuildResponse | undefined>;
+    whoAmI(): Promise<WhoAmI>;
+    worker(workflowRunId: string, action: string, options: {
+        method: 'GET' | 'POST';
+        body?: unknown;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        retry?: boolean;
+    }): Promise<RawResponse>;
+    private sendOnce;
+}
+export declare function appUrl(): string;
+export declare function sessionViewerUrl(sessionId: string, kind?: 'computer'): 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;

package/dist/api/client.js

@@ -0,0 +1,201 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { VerifyError, errorMessage } from '../errors.js';
+import { VERSION } from '../version.js';
+export const DEFAULT_BACKEND_URL = 'https://backend.revyl.ai';
+export const DEFAULT_APP_URL = 'https://app.revyl.ai';
+/** Sent on every request so Revyl can attribute sessions that Verify starts. */
+export const CLIENT_HEADER_VALUE = 'verify';
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const RETRY_DELAYS_MS = [500, 1500];
+const RETRYABLE_STATUSES = new Set([502, 503, 504]);
+export class RevylClient {
+    backendUrl;
+    token;
+    fetchImpl;
+    requestTimeoutMs;
+    constructor(options) {
+        this.token = options.token;
+        this.backendUrl = validateBackendUrl(options.backendUrl ?? process.env.REVYL_BACKEND_URL ?? DEFAULT_BACKEND_URL);
+        this.fetchImpl = options.fetch ?? fetch;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    }
+    async send(method, path, options = {}) {
+        const url = new URL(path, this.backendUrl);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value === undefined)
+                continue;
+            for (const item of Array.isArray(value) ? value : [value])
+                url.searchParams.append(key, item);
+        }
+        const retry = options.retry ?? method === 'GET';
+        const attempts = retry ? RETRY_DELAYS_MS.length + 1 : 1;
+        for (let attempt = 1;; attempt += 1) {
+            const outcome = await this.sendOnce(method, url, options);
+            const retryable = outcome instanceof Error || RETRYABLE_STATUSES.has(outcome.status);
+            if (!retryable || attempt >= attempts || options.signal?.aborted) {
+                if (outcome instanceof Error)
+                    throw outcome;
+                return outcome;
+            }
+            await delay(RETRY_DELAYS_MS[attempt - 1] ?? 1500, undefined, { signal: options.signal }).catch(() => undefined);
+        }
+    }
+    async json(method, path, options = {}) {
+        const response = await this.send(method, path, options);
+        if (response.status < 200 || response.status >= 300)
+            throw apiError(method, path, response);
+        return parseJson(response, `${method} ${path}`);
+    }
+    startDevice(request, signal) {
+        return this.json('POST', '/api/v1/execution/start_device', { body: request, retry: false, timeoutMs: 120_000, signal });
+    }
+    getDeviceSession(sessionId, signal) {
+        return this.json('GET', `/api/v1/execution/device-sessions/${encodeURIComponent(sessionId)}`, { signal });
+    }
+    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 });
+    }
+    cancelDevice(workflowRunId) {
+        return this.json('POST', `/api/v1/execution/device/status/cancel/${encodeURIComponent(workflowRunId)}`, { retry: true });
+    }
+    getApp(appId, signal) {
+        return this.json('GET', `/api/v1/apps/${encodeURIComponent(appId)}`, { signal });
+    }
+    registerWebUrlBuild(appId, request, signal) {
+        return this.json('POST', `/api/v1/apps/${encodeURIComponent(appId)}/builds/external`, { body: request, retry: true, signal });
+    }
+    async latestWebBuild(appId, branch, signal) {
+        const page = await this.json('GET', `/api/v1/apps/${encodeURIComponent(appId)}/builds`, {
+            query: {
+                artifact_kinds: ['web_external', 'web_bundle'],
+                branch_id: branch.branchId,
+                branch_name: branch.branchName,
+                include_jobs: 'false',
+                page: '1',
+                page_size: '1',
+            },
+            signal,
+        });
+        return page.items[0];
+    }
+    whoAmI() {
+        return this.json('GET', '/api/v1/entity/users/get_user_uuid');
+    }
+    worker(workflowRunId, action, options) {
+        const path = `/api/v1/execution/device-proxy/${encodeURIComponent(workflowRunId)}/${action}`;
+        return this.send(options.method, path, {
+            body: options.body,
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            retry: options.retry ?? false,
+            headers: { 'X-Revyl-Agent': 'Verify' },
+        });
+    }
+    async sendOnce(method, url, options) {
+        const timeout = AbortSignal.timeout(options.timeoutMs ?? this.requestTimeoutMs);
+        const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            'User-Agent': `revyl-verify/${VERSION} node/${process.versions.node}`,
+            'X-Revyl-Client': CLIENT_HEADER_VALUE,
+            Accept: 'application/json',
+            ...options.headers,
+        };
+        if (options.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        try {
+            const response = await this.fetchImpl(url, {
+                method,
+                headers,
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                redirect: 'error',
+                signal,
+            });
+            return { status: response.status, headers: response.headers, body: new Uint8Array(await response.arrayBuffer()) };
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                return new VerifyError('TIMEOUT', `Revyl request ${method} ${url.pathname} ran past its caller's deadline.`, { cause: error });
+            }
+            if (timeout.aborted) {
+                return new VerifyError('TIMEOUT', `Revyl request ${method} ${url.pathname} got no response within ${options.timeoutMs ?? this.requestTimeoutMs} ms.`, { cause: error });
+            }
+            return new VerifyError('API_ERROR', `Could not reach Revyl at ${url.origin}: ${errorMessage(error)}`, { cause: error });
+        }
+    }
+}
+export function appUrl() {
+    return (process.env.REVYL_APP_URL ?? DEFAULT_APP_URL).replace(/\/+$/, '');
+}
+export function sessionViewerUrl(sessionId, kind) {
+    return `${appUrl()}/sessions/${encodeURIComponent(sessionId)}${kind ? `?kind=${kind}` : ''}`;
+}
+export function parseJson(response, what) {
+    try {
+        return JSON.parse(new TextDecoder().decode(response.body));
+    }
+    catch (error) {
+        throw new VerifyError('API_ERROR', `Revyl returned a response to ${what} that is not JSON (HTTP ${response.status}).`, {
+            cause: error,
+        });
+    }
+}
+export function responseDetail(response) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(response.body));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    const detail = record.detail ?? record.message ?? record.error;
+    if (typeof detail === 'string')
+        return detail.slice(0, 500);
+    if (Array.isArray(detail)) {
+        return detail
+            .map((item) => (typeof item === 'object' && item !== null && 'msg' in item ? String(item.msg) : String(item)))
+            .join('; ')
+            .slice(0, 500);
+    }
+    return undefined;
+}
+export function responseErrorCode(response) {
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(response.body));
+        return typeof parsed.error === 'string' ? parsed.error : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function apiError(method, path, response) {
+    const detail = 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('API_ERROR', `Revyl request ${method} ${path} failed with HTTP ${response.status}${suffix}`);
+}
+function validateBackendUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new VerifyError('CONFIG_INVALID', 'REVYL_BACKEND_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).');
+    }
+    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.');
+    }
+    return url.origin;
+}