@revyl/verify 0.0.0-stage → 0.2.0

package/dist/config.js

@@ -0,0 +1,212 @@
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { createJiti } from 'jiti';
+import { VerifyError } from './errors.js';
+import { PACKAGE_NAME } from './version.js';
+export const CONFIG_FILE_NAMES = ['verify.config.ts', 'verify.config.mts', 'verify.config.js', 'verify.config.mjs'];
+export const DEFAULT_STEP_TIMEOUT_MS = 180_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const WEB_URL = /^https:\/\/[^/?#@\s]+(\/[^?#\s]*)?$/;
+const TARGET_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const PLATFORMS = ['web', 'ios', 'android', 'mac', 'linux'];
+export function defineConfig(config) {
+    return config;
+}
+/** The nearest verify.config file in the folder or any folder above it. */
+export function findConfigFile(startDir) {
+    for (let dir = resolve(startDir);; dir = dirname(dir)) {
+        for (const name of CONFIG_FILE_NAMES) {
+            const candidate = resolve(dir, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
+export async function loadConfig(cwd, explicitPath) {
+    const configFile = explicitPath ? resolve(cwd, explicitPath) : findConfigFile(cwd);
+    if (!configFile || !existsSync(configFile)) {
+        throw new VerifyError('CONFIG_NOT_FOUND', explicitPath
+            ? `Config file not found: ${explicitPath}`
+            : `No verify.config.ts in ${cwd} or any folder above it. Run 'npx ${PACKAGE_NAME} init' to create one, or pass a target object to open().`);
+    }
+    const jiti = createJiti(import.meta.url, { moduleCache: false, interopDefault: true });
+    let loaded;
+    try {
+        loaded = await jiti.import(configFile, { default: true });
+    }
+    catch (error) {
+        throw new VerifyError('CONFIG_INVALID', `Could not load ${configFile}: ${error.message}`, { cause: error });
+    }
+    return validateConfig(loaded, configFile);
+}
+export function validateConfig(raw, configFile) {
+    const fail = (path, problem) => {
+        throw new VerifyError('CONFIG_INVALID', `${configFile}: ${path} ${problem}`);
+    };
+    const config = asRecord(raw, 'the default export', fail);
+    rejectUnknownKeys(config, ['targets', 'stepTimeout'], '', fail);
+    const rawTargets = asRecord(config.targets, 'targets', fail);
+    const names = Object.keys(rawTargets);
+    if (names.length === 0)
+        fail('targets', 'must name at least one target, such as { web: { platform: \'web\', ... } }.');
+    const targets = {};
+    for (const name of names) {
+        if (!TARGET_NAME.test(name))
+            fail(`targets.${name}`, 'must be named with 1-64 letters, digits, dots, dashes, or underscores.');
+        targets[name] = parseTarget(rawTargets[name], name, `targets.${name}`, fail);
+    }
+    return {
+        configFile,
+        targets,
+        stepTimeout: integer(config.stepTimeout, 'stepTimeout', 1_000, 3_600_000, DEFAULT_STEP_TIMEOUT_MS, fail),
+    };
+}
+/** Validates a target passed straight to open(); it is named after its platform. */
+export function validateTarget(raw) {
+    const fail = (path, problem) => {
+        throw new VerifyError('INVALID_ARGUMENT', `open(): ${path} ${problem}`);
+    };
+    const platform = asRecord(raw, 'target', fail).platform;
+    return parseTarget(raw, typeof platform === 'string' ? platform : 'target', 'target', fail);
+}
+function parseTarget(raw, name, path, fail) {
+    const target = asRecord(raw, path, fail);
+    const platform = target.platform;
+    if (typeof platform !== 'string' || !PLATFORMS.includes(platform)) {
+        fail(`${path}.platform`, "must be 'web', 'ios', 'android', 'mac', or 'linux'.");
+    }
+    const startTimeout = integer(target.startTimeout, `${path}.startTimeout`, 10_000, 1_800_000, 600_000, fail);
+    if (platform === 'mac' || platform === 'linux') {
+        rejectUnknownKeys(target, ['platform', 'startTimeout'], path, fail);
+        return { name, startTimeout, platform };
+    }
+    const common = {
+        name,
+        startTimeout,
+        idleTimeoutSeconds: integer(target.idleTimeoutSeconds, `${path}.idleTimeoutSeconds`, 60, 3_600, 600, fail),
+    };
+    const app = asRecord(target.app, `${path}.app`, fail);
+    if (platform === 'web') {
+        rejectUnknownKeys(target, ['platform', 'app', 'viewport', 'signIn', 'startTimeout', 'idleTimeoutSeconds'], path, fail);
+        rejectUnknownKeys(app, ['appId', 'url', 'buildId', 'branch'], `${path}.app`, fail);
+        uuid(app.appId, `${path}.app.appId`, true, fail);
+        uuid(app.buildId, `${path}.app.buildId`, false, fail);
+        if (app.url !== undefined && (typeof app.url !== 'string' || app.url.length > 2048 || !WEB_URL.test(app.url))) {
+            fail(`${path}.app.url`, 'must be a public HTTPS URL without credentials, query, or fragment. Revyl cannot reach localhost.');
+        }
+        if (app.url !== undefined && app.buildId !== undefined)
+            fail(`${path}.app`, 'takes url or buildId, not both.');
+        optionalString(app.branch, `${path}.app.branch`, 255, fail);
+        if (app.branch !== undefined && app.buildId !== undefined)
+            fail(`${path}.app`, 'takes branch or buildId, not both.');
+        let viewport;
+        if (target.viewport !== undefined) {
+            const raw = asRecord(target.viewport, `${path}.viewport`, fail);
+            rejectUnknownKeys(raw, ['width', 'height', 'deviceScaleFactor'], `${path}.viewport`, fail);
+            viewport = {
+                width: integer(raw.width, `${path}.viewport.width`, 320, 3840, undefined, fail),
+                height: integer(raw.height, `${path}.viewport.height`, 240, 2160, undefined, fail),
+            };
+            if (raw.deviceScaleFactor !== undefined) {
+                const factor = raw.deviceScaleFactor;
+                if (typeof factor !== 'number' || !(factor >= 1 && factor <= 3))
+                    fail(`${path}.viewport.deviceScaleFactor`, 'must be from 1 to 3.');
+                viewport.deviceScaleFactor = factor;
+            }
+        }
+        let signIn;
+        if (target.signIn !== undefined) {
+            const raw = asRecord(target.signIn, `${path}.signIn`, fail);
+            rejectUnknownKeys(raw, ['path', 'secret', 'persona'], `${path}.signIn`, fail);
+            if (typeof raw.path !== 'string' || !/^\/(?!\/)[^?#\\\s]{0,511}$/.test(raw.path)) {
+                fail(`${path}.signIn.path`, 'must be a path starting with one / and no query, fragment, or whitespace.');
+            }
+            if (typeof raw.secret !== 'string' || raw.secret.trim() === '') {
+                fail(`${path}.signIn.secret`, 'must name an organization secret launch variable (its name, never its value).');
+            }
+            if (raw.persona !== undefined && (typeof raw.persona !== 'string' || !/^[a-z0-9_-]{1,32}$/.test(raw.persona))) {
+                fail(`${path}.signIn.persona`, 'must match [a-z0-9_-]{1,32}.');
+            }
+            signIn = { path: raw.path, secret: raw.secret, ...(raw.persona ? { persona: raw.persona } : {}) };
+        }
+        return {
+            ...common,
+            platform: 'web',
+            app: {
+                appId: app.appId,
+                ...(app.url !== undefined ? { url: app.url } : {}),
+                ...(app.buildId !== undefined ? { buildId: app.buildId } : {}),
+                ...(app.branch !== undefined ? { branch: app.branch } : {}),
+            },
+            ...(viewport ? { viewport } : {}),
+            ...(signIn ? { signIn } : {}),
+        };
+    }
+    rejectUnknownKeys(target, ['platform', 'app', 'device', 'startTimeout', 'idleTimeoutSeconds'], path, fail);
+    rejectUnknownKeys(app, ['appId', 'buildId', 'artifactUrl', 'bundleId'], `${path}.app`, fail);
+    uuid(app.appId, `${path}.app.appId`, false, fail);
+    uuid(app.buildId, `${path}.app.buildId`, false, fail);
+    optionalString(app.bundleId, `${path}.app.bundleId`, 255, fail);
+    if (app.artifactUrl !== undefined && (typeof app.artifactUrl !== 'string' || !/^https:\/\//.test(app.artifactUrl))) {
+        fail(`${path}.app.artifactUrl`, 'must be an HTTPS URL.');
+    }
+    const sources = [app.appId, app.buildId, app.artifactUrl, app.bundleId].filter((value) => value !== undefined).length;
+    if (sources !== 1) {
+        fail(`${path}.app`, 'takes exactly one of appId, buildId, or artifactUrl to install an app, or bundleId to open one already on the device.');
+    }
+    let device;
+    if (target.device !== undefined) {
+        const raw = asRecord(target.device, `${path}.device`, fail);
+        rejectUnknownKeys(raw, ['model', 'osVersion'], `${path}.device`, fail);
+        optionalString(raw.model, `${path}.device.model`, 128, fail);
+        optionalString(raw.osVersion, `${path}.device.osVersion`, 64, fail);
+        device = {
+            ...(raw.model !== undefined ? { model: raw.model } : {}),
+            ...(raw.osVersion !== undefined ? { osVersion: raw.osVersion } : {}),
+        };
+    }
+    return {
+        ...common,
+        platform: platform,
+        app: {
+            ...(app.appId !== undefined ? { appId: app.appId } : {}),
+            ...(app.buildId !== undefined ? { buildId: app.buildId } : {}),
+            ...(app.artifactUrl !== undefined ? { artifactUrl: app.artifactUrl } : {}),
+            ...(app.bundleId !== undefined ? { bundleId: app.bundleId } : {}),
+        },
+        ...(device ? { device } : {}),
+    };
+}
+function asRecord(raw, path, fail) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        fail(path, 'must be an object.');
+    return raw;
+}
+function rejectUnknownKeys(record, allowed, path, fail) {
+    for (const key of Object.keys(record)) {
+        if (!allowed.includes(key))
+            fail(path ? `${path}.${key}` : key, `is not a known option. Known: ${allowed.join(', ')}.`);
+    }
+}
+function integer(raw, path, min, max, fallback, fail) {
+    if (raw === undefined && fallback !== undefined)
+        return fallback;
+    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < min || raw > max)
+        fail(path, `must be an integer from ${min} to ${max}.`);
+    return raw;
+}
+function uuid(raw, path, required, fail) {
+    if (raw === undefined && !required)
+        return;
+    if (typeof raw !== 'string' || !UUID.test(raw)) {
+        fail(path, `${required ? 'is required and ' : ''}must be a Revyl id (a UUID); copy it from the app's page in Revyl.`);
+    }
+}
+function optionalString(raw, path, maxLength, fail) {
+    if (raw === undefined)
+        return;
+    if (typeof raw !== 'string' || raw.trim() === '' || raw.length > maxLength)
+        fail(path, `must be a non-empty string of at most ${maxLength} characters.`);
+}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export type VerifyErrorCode = 'INVALID_ARGUMENT' | 'CONFIG_NOT_FOUND' | 'CONFIG_INVALID' | 'AUTH_MISSING' | 'AUTH_REJECTED' | 'API_ERROR' | 'SESSION_START_FAILED' | 'SESSION_ENDED' | 'SESSION_BUSY' | 'COMPUTER_LIMIT' | 'NOT_AVAILABLE_ON_PLATFORM' | 'ACTION_FAILED' | 'ACTION_UNCERTAIN' | 'INSTRUCTION_FAILED' | 'VALIDATION_FAILED' | 'STEP_FAILED' | 'COMMAND_FAILED' | 'NOT_FOUND' | 'ACCESS_DENIED' | 'TIMEOUT';
+export declare class VerifyError extends Error {
+    readonly code: VerifyErrorCode;
+    constructor(code: VerifyErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function isVerifyError(error: unknown): error is VerifyError;
+export declare function errorMessage(error: unknown): string;

package/dist/errors.js

@@ -0,0 +1,14 @@
+export class VerifyError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'VerifyError';
+        this.code = code;
+    }
+}
+export function isVerifyError(error) {
+    return error instanceof Error && typeof error.code === 'string' && error.name === 'VerifyError';
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { open } from './open.js';
+export type { OpenOptions } from './open.js';
+export type { Session, StepOptions, StepResult, StepType, ValidationOptions, OperationOptions, ExecOptions, ExecResult, FileStat, ComputerProcess, ComputerRecording } from './session.js';
+export { defineConfig } from './config.js';
+export type { MobileAppConfig, MobileTargetConfig, ComputerTargetConfig, TargetConfig, VerifyConfig, WebAppConfig, WebTargetConfig } from './config.js';
+export type { Platform, ComputerPlatform, MobilePlatform } from './api/types.js';
+export { VerifyError, isVerifyError } from './errors.js';
+export type { VerifyErrorCode } from './errors.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { open } from './open.js';
+export { defineConfig } from './config.js';
+export { VerifyError, isVerifyError } from './errors.js';

package/dist/open.d.ts

@@ -0,0 +1,13 @@
+import { type TargetConfig } from './config.js';
+import { type Session } from './session.js';
+export interface OpenOptions {
+    /** The config file to read target names from. Defaults to the nearest verify.config.ts at or above the current folder. */
+    config?: string;
+    /** Where progress lines go: the session link and each step's outcome. Defaults to stderr; false turns them off. */
+    log?: false | ((line: string) => void);
+}
+/**
+ * Starts a Revyl cloud browser, device, or computer. Mobile first-screen readiness is best-effort.
+ * Pass a target name from verify.config.ts, such as open('web'), or a target object.
+ */
+export declare function open(target: string | TargetConfig, options?: OpenOptions): Promise<Session>;

package/dist/open.js

@@ -0,0 +1,33 @@
+import { RevylClient } from './api/client.js';
+import { missingCredentialsMessage, resolveCredentials } from './auth.js';
+import { DEFAULT_STEP_TIMEOUT_MS, loadConfig, validateTarget } from './config.js';
+import { VerifyError } from './errors.js';
+import { DeviceSession } from './session.js';
+import { ComputerSession } from './computer-session.js';
+/**
+ * Starts a Revyl cloud browser, device, or computer. Mobile first-screen readiness is best-effort.
+ * Pass a target name from verify.config.ts, such as open('web'), or a target object.
+ */
+export async function open(target, options = {}) {
+    let resolved;
+    let stepTimeout = DEFAULT_STEP_TIMEOUT_MS;
+    if (typeof target === 'string') {
+        const config = await loadConfig(process.cwd(), options.config);
+        resolved = config.targets[target];
+        if (!resolved) {
+            throw new VerifyError('INVALID_ARGUMENT', `open('${target}'): ${config.configFile} has no target named "${target}". Targets: ${Object.keys(config.targets).join(', ')}.`);
+        }
+        stepTimeout = config.stepTimeout;
+    }
+    else {
+        resolved = validateTarget(target);
+    }
+    const credentials = await resolveCredentials();
+    if (!credentials)
+        throw new VerifyError('AUTH_MISSING', missingCredentialsMessage());
+    const log = options.log === false ? undefined : (options.log ?? ((line) => void process.stderr.write(`[verify] ${line}\n`)));
+    const client = new RevylClient({ token: credentials.token });
+    if (resolved.platform === 'mac' || resolved.platform === 'linux')
+        return ComputerSession.start(client, resolved, { stepTimeout, log });
+    return DeviceSession.start(client, resolved, { stepTimeout, log });
+}

package/dist/screen-readiness.d.ts

@@ -0,0 +1 @@
+export declare function screenHasContent(bytes: Uint8Array): boolean | undefined;

package/dist/screen-readiness.js

@@ -0,0 +1,27 @@
+import { PNG } from 'pngjs';
+export function screenHasContent(bytes) {
+    if (bytes.length < 24 || bytes.length > 16 * 1024 * 1024)
+        return undefined;
+    const header = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const width = header.readUInt32BE(16);
+    const height = header.readUInt32BE(20);
+    if (width === 0 || height === 0 || width * height > 16_000_000)
+        return undefined;
+    try {
+        const { data } = PNG.sync.read(header);
+        const left = Math.floor(width / 10);
+        const top = Math.floor(height / 10);
+        const first = (top * width + left) * 4;
+        for (let y = top; y < Math.ceil(height * 0.9); y += 1) {
+            for (let x = left; x < Math.ceil(width * 0.9); x += 1) {
+                const offset = (y * width + x) * 4;
+                if (data[offset] !== data[first] || data[offset + 1] !== data[first + 1] || data[offset + 2] !== data[first + 2])
+                    return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,153 @@
+import { RevylClient } from './api/client.js';
+import type { LiveStepType, Platform } from './api/types.js';
+import type { ResolvedDeviceTarget } from './config.js';
+export type StepType = LiveStepType;
+/** The outcome of one instruction or validation, as Revyl's agent reported it. */
+export interface StepResult {
+    type: StepType;
+    text: string;
+    passed: boolean;
+    /** Revyl's explanation, when it gave one. */
+    reason?: string;
+    durationMs: number;
+}
+export interface StepOptions {
+    /** Milliseconds before the step is cancelled on Revyl. Defaults to stepTimeout from the config, or 180000. */
+    timeout?: number;
+}
+export interface ValidationOptions extends StepOptions {
+    /** Return a failed result instead of throwing VALIDATION_FAILED. */
+    soft?: boolean;
+}
+export interface OperationOptions {
+    /** Milliseconds Revyl lets the operation run on the computer, up to 300000. Defaults to 30000. */
+    timeout?: number;
+}
+export interface ExecOptions extends OperationOptions {
+    /** Throw COMMAND_FAILED when the command exits non-zero. Defaults to true; false returns the result instead. */
+    check?: boolean;
+    /** Bytes sent to the command's standard input. */
+    stdin?: string | Uint8Array;
+}
+/** The outcome of a command run on a computer. Revyl keeps the first 1 MiB of stdout and stderr together. */
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface FileStat {
+    kind: 'file' | 'directory';
+    size: number;
+}
+/** A process a command on this computer started. Its id is Revyl's handle, not a PID. */
+export interface ComputerProcess {
+    id: string;
+    state: 'running' | 'exited';
+    exitCode?: number;
+}
+export interface ComputerRecording {
+    url: string;
+    durationSeconds?: number;
+    startedAt?: Date;
+}
+/**
+ * One live Revyl session: a cloud browser, an iOS or Android device, or a computer.
+ * A call the session's platform does not offer throws NOT_AVAILABLE_ON_PLATFORM.
+ */
+export interface Session {
+    readonly platform: Platform;
+    /** The target name: its key in verify.config.ts, or the platform for a target passed inline. */
+    readonly target: string;
+    /** Revyl's session id. */
+    readonly id: string;
+    /** The live view of the session in Revyl, and its recording and report once it ends. */
+    readonly viewerUrl: string;
+    /** Every instruction and validation run on this session, in order. */
+    readonly steps: StepResult[];
+    readonly closed: boolean;
+    readonly expiresAt?: Date;
+    recording(): Promise<ComputerRecording | null>;
+    /** Asks Revyl's agent to do something on the app. Browsers and devices only. */
+    instruction(text: string, options?: StepOptions): Promise<StepResult>;
+    /** Asks Revyl's agent whether something holds on screen. Browsers and devices only. */
+    validation(text: string, options?: ValidationOptions): Promise<StepResult>;
+    /** A PNG of the screen right now, also written to path when given. */
+    screenshot(options?: {
+        path?: string;
+    }): Promise<Uint8Array>;
+    /** Runs a program with its arguments, not a shell line. Computers only. */
+    exec(argv: string[], options?: ExecOptions): Promise<ExecResult>;
+    /** Up to the first 1 MiB of a file, by a path relative to the computer's workspace. Computers only. */
+    readFile(path: string, options?: OperationOptions): Promise<Buffer>;
+    /** Writes up to 64 KiB to a file, by a path relative to the computer's workspace. Computers only. */
+    writeFile(path: string, data: string | Uint8Array, options?: OperationOptions): Promise<void>;
+    /** Whether a path is a file or a directory, and its size. Computers only. */
+    stat(path: string, options?: OperationOptions): Promise<FileStat>;
+    /** The processes commands on this computer started. Computers only. */
+    processes(options?: OperationOptions): Promise<ComputerProcess[]>;
+    /** Stops a process from processes(). Computers only. */
+    terminate(processId: string, options?: OperationOptions): Promise<void>;
+    /** Stops the session on Revyl. Safe to call more than once. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export interface SessionOptions {
+    stepTimeout: number;
+    log: ((line: string) => void) | undefined;
+}
+/** A Revyl cloud browser or iOS or Android device. */
+export declare class DeviceSession implements Session {
+    private readonly client;
+    private readonly options;
+    readonly platform: Platform;
+    /** The target name: its key in verify.config.ts, or the platform for a target passed inline. */
+    readonly target: string;
+    /** Revyl's session id. */
+    readonly id: string;
+    /** The live view of the session in Revyl, and its recording and report once it ends. */
+    readonly viewerUrl: string;
+    /** Every instruction and validation run on this session, in order. */
+    readonly steps: StepResult[];
+    private workflowRunId;
+    private closePromise;
+    private stepRunning;
+    private constructor();
+    static start(client: RevylClient, target: ResolvedDeviceTarget, options: SessionOptions): Promise<DeviceSession>;
+    get closed(): boolean;
+    /** Asks Revyl's agent to do something on the app, such as "add the first product to the cart". Throws INSTRUCTION_FAILED when it cannot. */
+    instruction(text: string, options?: StepOptions): Promise<StepResult>;
+    /**
+     * Asks Revyl's agent whether something holds on screen, such as "the cart shows 2 items". Throws VALIDATION_FAILED when it does not,
+     * unless soft is set, and STEP_FAILED when Revyl could not reach a verdict.
+     */
+    validation(text: string, options?: ValidationOptions): Promise<StepResult>;
+    /** A PNG of the screen right now, also written to path when given. */
+    screenshot(options?: {
+        path?: string;
+    }): Promise<Uint8Array>;
+    exec(): Promise<ExecResult>;
+    recording(): Promise<never>;
+    readFile(): Promise<Buffer>;
+    writeFile(): Promise<void>;
+    stat(): Promise<FileStat>;
+    processes(): Promise<ComputerProcess[]>;
+    terminate(): Promise<void>;
+    /** Stops the session on Revyl. Safe to call more than once. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    private step;
+    private runStep;
+    private launch;
+    private waitForScreenContent;
+    private log;
+    private computerOnly;
+    private worker;
+    private workerError;
+    private untilReady;
+    private waitForWebReady;
+    private waitForDeviceReady;
+}
+export declare function pngSize(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;