@applitools/eyes-results 0.2.0

package/types/api/compare-step.d.ts

@@ -0,0 +1,52 @@
+import { type FetchLike } from './polling.js';
+import type { ImageRecord } from './selector-mapping.js';
+import type { ImageMatchSettings } from '../sessions/match.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface CompareStepOptions {
+    baseUrl: string;
+    accountId: string;
+    keys: ApiKeyProvider;
+}
+export interface CompareStepBody {
+    matchSettings: ImageMatchSettings;
+    image1: ImageRecord;
+    image2: ImageRecord;
+    sessionId: string;
+    batchId: string;
+    runningSessionId: string;
+    stepIndex: number;
+}
+export interface CompareDiffRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    diffDescriptions?: unknown[];
+}
+export interface CompareStepResult {
+    isMatch: boolean;
+    image1Size: {
+        width: number;
+        height: number;
+    };
+    image1: CompareDiffRect[];
+    image2Size: {
+        width: number;
+        height: number;
+    };
+    image2: CompareDiffRect[];
+    [key: string]: unknown;
+}
+/**
+ * Recomputes a step's visual diff against arbitrary match settings/regions — the same
+ * comparison the dashboard's own region editor uses for a live preview, confirmed live to
+ * accept both a `{domSelector}` region (resolved against both images' own DOM, since
+ * `useDom`/`hasDom` are true) and a plain `{left,top,width,height}` region. `image1`/`image2`
+ * in the response are a genuine two-way diff — rects in each image's own coordinate space,
+ * not a single shared list — mirroring the request's own `image1`/`image2` sides.
+ *
+ * Confirmed live to be sometimes synchronous (200) and sometimes an async job (202 +
+ * `Location`) depending on whether the exact payload was already computed — `getJsonResult`
+ * handles both transparently.
+ */
+export declare function compareStep(body: CompareStepBody, options: CompareStepOptions, fetchImpl?: FetchLike): Promise<CompareStepResult>;

package/types/api/diff-fetch.d.ts

@@ -0,0 +1,21 @@
+import { type FetchLike } from './polling.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface FetchStepDiffOptions {
+    baseUrl: string;
+    batchId: string;
+    sessionId: string;
+    stepIndex: number;
+    accountId: string;
+    keys: ApiKeyProvider;
+}
+export interface StepDiffResult {
+    image1: any[];
+    image2: any[];
+}
+/**
+ * The cheap, already-computed two-way diff for one step, straight off the dashboard's own
+ * `GET .../diff` endpoint — used whenever nothing about the step's effective match settings
+ * differs from what the test actually ran with (see `eyes-inspect`'s `fetchDiffRects`, this
+ * function's only caller, for when the more expensive `compareStep` path is needed instead).
+ */
+export declare function fetchStepDiff(options: FetchStepDiffOptions, fetchImpl?: FetchLike): Promise<StepDiffResult>;

package/types/api/dom-diff.d.ts

@@ -0,0 +1,53 @@
+import type { Fetch } from '@applitools/req';
+import { type FsCacheDeps } from './fs-cache.js';
+import { type ReqResultsLogger } from './req-results.js';
+import type { DomAlignment } from '../sessions/dom.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export declare const DOM_DIFF_PATH = "/api/images/dom/diff";
+export interface FetchDomDiffDeps extends FsCacheDeps {
+    /** Test seam — swaps the configured req's network layer, never its behavior. */
+    fetch?: Fetch;
+    logger?: ReqResultsLogger;
+}
+export declare const defaultFetchDomDiffDeps: FetchDomDiffDeps;
+export type DomDiffResult = {
+    status: 'ready';
+    alignment: DomAlignment;
+} | {
+    status: 'running';
+    taskId: string;
+};
+/**
+ * Fetches (or reads from cache) the alignment of two DOM snapshots, computed server-side. The
+ * request carries the two domIds alone — the server resolves them against its own snapshot
+ * storage, so no DOM travels either way — and a ready result is the compact `{matches, diff}`
+ * alignment: `matches` is what lets a caller extract one node's own diff afterwards
+ * (`sessions/dom`'s `extractNodeDiff`) without paying for a second alignment of the same pair.
+ * Cropping to an area (`filterDiffToArea`), excluding non-visual entries
+ * (`excludeNonVisualNodeDiffs`) and serializing (`serializeDiff`) all stay with the caller.
+ *
+ * No client-side polling: a 202 submit is probed once via `getTaskStatus`; if the task is still
+ * running, the taskId is returned and the caller decides when to check again
+ * (`checkDomDiffTask`). A direct 200 with the alignment body also parses — forward tolerance for
+ * a server answering an already-computed pair synchronously; the current backend always answers
+ * 202 (its async-task framework has no synchronous arm).
+ *
+ * Content-addressed cache, keyed on the two domIds alone — both are already immutable, unlike an
+ * area or a step's match settings, so one ready alignment is reused across every caller of that
+ * pair. A `running` outcome is never cached.
+ *
+ * Every alignment is shape-checked at this boundary before it is returned or cached — see
+ * `assertDomAlignment`.
+ */
+export declare function fetchDomDiff(baseUrl: string, baselineDomId: string, checkpointDomId: string, keys: ApiKeyProvider, deps?: FetchDomDiffDeps): Promise<DomDiffResult>;
+/**
+ * The caller's re-check for a `running` `fetchDomDiff` — one `getTaskStatus` probe, with a ready
+ * alignment landing in the same domId-pair cache a direct fetch would have written, so later
+ * calls for the pair stay cache hits regardless of which path produced the alignment.
+ *
+ * Cache-first, like `fetchDomDiff`: the pair may already be ready on disk (an earlier probe, or
+ * any other caller of the same pair, landed it), and a cached pair must win even when the taskId
+ * in hand has since expired — so a re-check with a stale taskId never fails on a result that's
+ * already here.
+ */
+export declare function checkDomDiffTask(baseUrl: string, taskId: string, baselineDomId: string, checkpointDomId: string, keys: ApiKeyProvider, deps?: FetchDomDiffDeps): Promise<DomDiffResult>;

package/types/api/dom-fetch.d.ts

@@ -0,0 +1,29 @@
+import type { Fetch } from '@applitools/req';
+import { type FsCacheDeps } from './fs-cache.js';
+import { type ReqResultsLogger } from './req-results.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+import type { PrunedDom } from '../sessions/dom.js';
+export declare const PRUNED_DOM_PATH: (domId: string) => string;
+export interface FetchPrunedDomOptions {
+    baseUrl: string;
+    domId: string;
+    keys: ApiKeyProvider;
+}
+export interface FetchPrunedDomDeps extends FsCacheDeps {
+    /** Test seam — swaps the configured req's network layer, never its behavior. */
+    fetch?: Fetch;
+    logger?: ReqResultsLogger;
+}
+export declare const defaultFetchPrunedDomDeps: FetchPrunedDomDeps;
+/**
+ * Fetches (or reads from cache) an Applitools DOM snapshot already pruned server-side: URLs
+ * normalized, node ids assigned, metadata fields and whitespace-only text nodes gone. Same
+ * `eyes-<domId>` cache entry a client-side pruner writes, so entries stay valid either way.
+ * Takes no `area` — cropping is a separate, uncached step (`sessions/dom`'s `getDomArea`).
+ *
+ * The 200 body may be a gzip payload (a gzip *body*, not `Content-Encoding` — which the
+ * transport already undoes transparently), so it's gunzipped when it is one and parsed as-is
+ * when it isn't. Any non-200 throws via the configured req's expected-status hook, carrying the
+ * request name, status, and response body.
+ */
+export declare function fetchPrunedDom(options: FetchPrunedDomOptions, deps?: FetchPrunedDomDeps): Promise<PrunedDom>;

package/types/api/find-regions.d.ts

@@ -0,0 +1,26 @@
+import { type FetchLike } from './polling.js';
+import type { ImageRecord } from './selector-mapping.js';
+import type { Region } from '../sessions/regions.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface FindRegionsOptions {
+    baseUrl: string;
+    accountId: string;
+    keys: ApiKeyProvider;
+}
+/**
+ * Searches every one of `targets` for each of `regions` — regions defined against
+ * `sourceImage`'s own DOM or, since `domSelector` is optional, its raw rectangle — and returns
+ * a map keyed by each target's `ImageRecord.id`. A target with no match at all is still present
+ * in the map, with an empty array (its key is never omitted). When several regions are searched
+ * at once, a target's array holds only the ones actually found there — there is no positional
+ * correspondence to `regions`, so a caller distinguishes which one matched by comparing
+ * `domSelector` back against the region it sent (both confirmed live: a single-region miss
+ * comes back as `[]`; a two-region call with one hit and one miss comes back with exactly one
+ * entry, the hit).
+ *
+ * Confirmed live to be an async job: the initial POST returns 202 with a `Location` header
+ * to a status URL; polling that returns 201, but the result itself lives at a *second*,
+ * separate URL given by that 201 response's own `Location` header — `getJsonResult`/
+ * `pollUntilResult` (`./polling.js`) handle this double-redirect.
+ */
+export declare function findRegionsInImages(sourceImage: ImageRecord, regions: Region[], targets: ImageRecord[], options: FindRegionsOptions, fetchImpl?: FetchLike, sleepFn?: (ms: number) => Promise<void>): Promise<Record<string, Region[]>>;

package/types/api/fs-cache.d.ts

@@ -0,0 +1,12 @@
+export interface FsCacheDeps {
+    readFile: (path: string) => string | null;
+    writeFile: (path: string, contents: string) => void;
+    cacheDir: string;
+}
+export declare const defaultFsCacheDeps: FsCacheDeps;
+/**
+ * Builds a content-addressed cache file path, sanitizing `key` the same way the
+ * repo's existing cache-file naming already does (only `~`/`,` need escaping —
+ * these characters can appear in Applitools image/dom ids and are not filesystem-safe).
+ */
+export declare function cacheFilePath(deps: FsCacheDeps, prefix: string, key: string, ext?: string): string;

package/types/api/gzip.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
+import { Buffer } from 'buffer';
+/** Promisified zlib.gunzip. Rejects if the input isn't valid gzip data — callers decide the fallback. */
+export declare function gunzip(buffer: Buffer): Promise<Buffer>;

package/types/api/image-fetch.d.ts

@@ -0,0 +1,29 @@
+/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
+import { Buffer } from 'buffer';
+import { type FetchLike } from './polling.js';
+import type { Rect } from '../geometry/geometry.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface FetchCheckpointImageOptions {
+    baseUrl: string;
+    batchId: string;
+    sessionId: string;
+    stepIndex: number;
+    accountId: string;
+    keys: ApiKeyProvider;
+    area?: Rect;
+}
+/**
+ * A step's checkpoint screenshot, as a raw PNG buffer — a binary response, so this calls `fetch`
+ * directly rather than through `postJson`/`getJson` (which assume JSON), the one documented
+ * exception among `api/`'s REST wrappers.
+ */
+export declare function fetchCheckpointImage(options: FetchCheckpointImageOptions, fetchImpl?: FetchLike): Promise<Buffer>;
+export interface FetchImageByIdOptions {
+    baseUrl: string;
+    imageId: string;
+    keys: ApiKeyProvider;
+    area?: Rect;
+}
+/** A baseline or checkpoint screenshot by its own image id, as a raw PNG buffer — same binary-response exception as `fetchCheckpointImage`. */
+export declare function fetchImageById(options: FetchImageByIdOptions, fetchImpl?: FetchLike): Promise<Buffer>;

package/types/api/polling.d.ts

@@ -0,0 +1,41 @@
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * The older api modules' transport seam — a fresh `makeReqResults` instance per invocation, the
+ * DOM-diff flow's conventions (standard retry policy, explicit request/connection timeouts). The
+ * full retry budget every request gets is guaranteed by `makeReqResults` itself
+ * (`isolateRetryPerRequest`), not by this per-invocation build; building here keeps one shape
+ * across the package and scopes the resolved server URL to the request it came from.
+ * These modules bake the apiKey into their URLs themselves, so it is read back out of the URL
+ * here rather than threaded separately; no `expected` statuses are passed, so the instance's
+ * unexpected-status hook stays inert and the modules' own status checks remain in charge. Only
+ * how a single request executes lives here: the task flow (202/Location → status → result),
+ * JSON parsing, and error wording all stay above it.
+ */
+export declare const reqTransport: FetchLike;
+/** POST a JSON body. */
+export declare function postJson(url: string, body: unknown, fetchImpl?: FetchLike): Promise<Response>;
+/** GET and parse a JSON response, throwing a descriptive error on a non-ok status. */
+export declare function getJson(url: string, fetchImpl?: FetchLike): Promise<any>;
+/**
+ * Polls a job-status URL until it reports done, then fetches and returns the job's result.
+ * Confirmed live against the real API — for every async endpoint checked so far (`images/find`,
+ * `sessions/batches/{batchId}/updates`), not just the ones that produce a real payload — a
+ * `201` isn't itself the result: it carries its *own* `Location` header (distinct from the
+ * original 202's) pointing at a separate result URL, which resolves with either a real JSON
+ * body (`images/find`) or an empty one (`updates`, `save`, etc. — a 204). Both are handled
+ * uniformly here; a caller with nothing to do with the result just ignores the return value.
+ * 200 = still running (wait and retry), anything else on the status poll = error.
+ */
+export declare function pollUntilResult(statusUrl: string, apiKey: string, fetchImpl?: FetchLike, sleepFn?: (ms: number) => Promise<void>): Promise<any>;
+/**
+ * Handles the Eyes dashboard's async-job response convention end to end: a `202` with a
+ * `Location` header means the job is running and is polled via `pollUntilResult` through to
+ * its actual result; a plain ok response is parsed as JSON directly (tolerating an empty
+ * body). One function for every endpoint, whether or not its result is ever read — a caller
+ * that only cares that the call succeeded (e.g. `accept`/`reject`/`save`) just discards the
+ * return value instead of needing a separate "no result expected" variant.
+ *
+ * `requestUrl` backs up `response.url` as the base for a relative Location: `response.url` is
+ * '' under req's HTTP/2 rewrap, so callers pass the URL they requested.
+ */
+export declare function getJsonResult(response: Response, apiKey: string, fetchImpl?: FetchLike, sleepFn?: (ms: number) => Promise<void>, requestUrl?: string): Promise<any>;

package/types/api/req-results.d.ts

@@ -0,0 +1,37 @@
+import { type Fetch, type Options, type Req } from '@applitools/req';
+export interface ReqResultsLogger {
+    log(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export interface ReqResultsOptions extends Options {
+    /** Response statuses the caller treats as business results; any other status throws. */
+    expected?: number | number[];
+    /** Names the request in thrown errors. */
+    name?: string;
+    logger?: ReqResultsLogger;
+}
+export interface MakeReqResultsOptions {
+    serverUrl: string;
+    /** Baked into every request as the `apiKey` query parameter — the convention all eyes-results endpoints use. */
+    apiKey: string;
+    /** Test seam — swaps the instance's network layer, never its behavior. */
+    fetch?: Fetch;
+    logger?: ReqResultsLogger;
+}
+/**
+ * Builds a configured `req` — core-base's `makeReqEyes` concept adapted to this package: the
+ * instance owns the server URL, the `apiKey` query parameter, the transient-retry policy, and the
+ * `expected`-status convention above, so api functions take the configured req plus business
+ * parameters and never thread baseUrl/apiKey/transport themselves. Flat options on purpose: an api
+ * function's own deps spread straight in — `makeReqResults({serverUrl, apiKey, ...deps})`.
+ *
+ * **Build one per call, not one per module.** Every call site here does (`api/dom-diff.ts`,
+ * `api/dom-fetch.ts`, `api/tasks.ts`, `api/polling.ts`'s `reqTransport`), because req's retry
+ * counter lives on the retry object the instance carries — see `isolateRetryPerRequest` above for
+ * what that costs a long-lived instance. That hook is what actually guarantees the budget is
+ * per-request, so hoisting an instance is safe rather than silently degrading; per-call
+ * construction stays the convention because it also keeps the apiKey and server URL scoped to the
+ * flow that resolved them. `test/api/req-results.test.ts`'s "retry isolation" suite makes several
+ * calls through a single instance and pins both properties.
+ */
+export declare function makeReqResults({ serverUrl, apiKey, fetch, logger }: MakeReqResultsOptions): Req<ReqResultsOptions>;

package/types/api/same-diff-as.d.ts

@@ -0,0 +1,38 @@
+import { type FetchLike } from './polling.js';
+import type { ImageMatchSettings } from '../sessions/match.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface SameDiffAsOptions {
+    baseUrl: string;
+    accountId: string;
+    keys: ApiKeyProvider;
+}
+export interface SameDiffAsStep {
+    batchId: string;
+    sessionId: string;
+    stepIndex: number;
+    image1: string;
+    image2: string;
+    matchSettings: ImageMatchSettings;
+}
+export interface SameDiffAsBody {
+    reference: SameDiffAsStep;
+    steps: SameDiffAsStep[];
+}
+/**
+ * Given a reference step and a candidate list of other steps, returns which of `steps` actually
+ * have the same diff as `reference` — the real target steps an accept/reject decision should
+ * propagate to, as opposed to every step a scenario-name match happened to include. `image1`/
+ * `image2` here are plain baseline/checkpoint image id strings, not full `ImageRecord` objects
+ * (unlike `compareStep`'s own request shape) — each entry (including `reference`) carries its
+ * own step's `matchSettings`, never another step's.
+ *
+ * Confirmed live: an async job (202 + Location), same as every other endpoint in this file.
+ * **The result is `number[]` — zero-based indices into the request's own `steps` array, e.g.
+ * `[0, 1]` meaning `steps[0]` and `steps[1]` both matched — never step objects, and never
+ * `{sessionId, stepIndex}` identifiers.** A caller must resolve each index back against its own
+ * original `steps`/candidate array; the response carries nothing else to identify a match by.
+ * When nothing in `steps` matches `reference`, the job's own result is `204 No Content` — an
+ * empty body, which `getJsonResult` parses as `undefined` — normalized here to `[]` so callers
+ * can always assume an array.
+ */
+export declare function findSameDiffSteps(body: SameDiffAsBody, options: SameDiffAsOptions, fetchImpl?: FetchLike): Promise<number[]>;

package/types/api/selector-mapping.d.ts

@@ -0,0 +1,28 @@
+import { type FetchLike } from './polling.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface ImageRecord {
+    id: string;
+    domId: string;
+    size: {
+        width: number;
+        height: number;
+    };
+    hasDom: boolean;
+    location: {
+        x: number;
+        y: number;
+    };
+    rectangle: string;
+}
+export interface GetCompatibleSelectorsOptions {
+    baseUrl: string;
+    accountId: string;
+    keys: ApiKeyProvider;
+}
+/**
+ * Maps each of `selectors` from `image1`'s DOM to its structurally-equivalent selector on
+ * `image2`'s DOM — e.g. translating a region's domSelector from a baseline to a checkpoint,
+ * or the reverse. Returns one entry per input selector, in the same order; an entry is
+ * `null` when no compatible element exists on `image2`.
+ */
+export declare function getCompatibleSelectors(options: GetCompatibleSelectorsOptions, image1: ImageRecord, image2: ImageRecord, selectors: string[], fetchImpl?: FetchLike): Promise<(string | null)[]>;

package/types/api/session-fetch.d.ts

@@ -0,0 +1,34 @@
+import { type FetchLike } from './polling.js';
+import { type SimplifiedSession, type SessionStep } from '../sessions/session.js';
+import { type BatchInfo } from '../sessions/batch.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface SessionUrlOptions {
+    baseUrl: string;
+    batchId: string;
+    accountId: string;
+    keys: ApiKeyProvider;
+}
+/** Fetches the raw Eyes session API response — no shaping. */
+export declare function fetchRawSession(options: SessionUrlOptions & {
+    sessionId: string;
+}, fetchImpl?: FetchLike): Promise<any>;
+/** Fetches a session and shapes it via `sessions/session`'s `simplifySession`. */
+export declare function fetchSession(options: SessionUrlOptions & {
+    sessionId: string;
+}, fetchImpl?: FetchLike): Promise<SimplifiedSession & {
+    steps: SessionStep[];
+}>;
+/**
+ * Fetches the raw list of sessions in a batch — no shaping.
+ * Normalizes the response shape: the Eyes API returns either a bare array or `{ sessions: [...] }`.
+ */
+export declare function fetchRawBatchSessions(options: SessionUrlOptions, fetchImpl?: FetchLike): Promise<any[]>;
+/**
+ * Fetches the raw batch entity itself (name, timing, and — the reason this exists —
+ * its server-maintained aggregate counts, shaped by `sessions/batch`'s `toBatchStats` —
+ * see `BatchInfo` there) — a different endpoint from `fetchRawBatchSessions`, which lists
+ * the batch's individual sessions. This aggregate is eventually consistent: it can lag
+ * behind a resolve/save call by several seconds, unlike a session list (or anything derived
+ * from one), which is always current.
+ */
+export declare function fetchBatchInfo(options: SessionUrlOptions, fetchImpl?: FetchLike): Promise<BatchInfo>;

package/types/api/session-history-fetch.d.ts

@@ -0,0 +1,56 @@
+import { type FetchLike } from './polling.js';
+import { type FsCacheDeps } from './fs-cache.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface SessionHistoryEnv {
+    hostingApp: string | null;
+    os: string | null;
+    displaySize: {
+        width: number;
+        height: number;
+    } | null;
+}
+/**
+ * Builds the `where=` filter clauses for a session-history query. Each clause's payload is a
+ * plain UTF-8 string, base64-encoded — not `encodeURIComponent(JSON.stringify(...))` — and
+ * `IsViewport` in particular is a custom `{width:N,height:N}` literal (unquoted keys, not
+ * valid JSON), confirmed by decoding a real sample URL. Returns only the clauses for fields
+ * actually present in `env`, `&&`-joined; a caller further `encodeURIComponent`s the whole
+ * result when building the request URL — this returns the raw (unencoded) filter text.
+ */
+export declare function buildSessionHistoryEnvFilter(env: SessionHistoryEnv): string;
+export interface SessionHistoryOptions {
+    baseUrl: string;
+    scenarioId: string;
+    accountId: string;
+    keys: ApiKeyProvider;
+    env: SessionHistoryEnv;
+    ranAtOrBefore: string;
+    count: number;
+}
+export interface FetchSessionHistoryDeps extends FsCacheDeps {
+    fetchImpl: FetchLike;
+    sleepFn?: (ms: number) => Promise<void>;
+}
+export declare const defaultFetchSessionHistoryDeps: FetchSessionHistoryDeps;
+/**
+ * Fetches (or reads from cache) a page of a scenario's historic sessions matching `env`, at or
+ * before `ranAtOrBefore`. Confirmed live as an async-job endpoint (a `202` with a `Location`
+ * status-poll header, same convention as `images/get-compatible-selectors` in
+ * `selector-mapping.ts` — there a POST initiates it, here a plain GET does), so this goes
+ * through `getJsonResult`, not `getJson` (which assumes a synchronous body).
+ *
+ * Named for what it returns — a session history — not for `scenarioId`, which is only one of
+ * several inputs (alongside `env`) narrowing which sessions come back; the endpoint itself is
+ * scoped by scenario, but the result is a plain list of full raw sessions, not scenario-level
+ * aggregate data.
+ *
+ * Cached indefinitely, keyed by a hash of every input that affects the result — unlike a
+ * session/batch fetch (deliberately never cached elsewhere in `api/`, since those can change),
+ * a `ranAtOrBefore`-pinned query against the past is immutable once made.
+ *
+ * Confirmed live: the response is `{ "sessions": [...] }`, each entry a full raw session
+ * object (the same shape `fetchRawSession` returns) — but a bare-array response is still
+ * normalized defensively, mirroring `fetchRawBatchSessions`, in case an edge case omits the
+ * wrapper.
+ */
+export declare function fetchSessionHistory(options: SessionHistoryOptions, deps?: FetchSessionHistoryDeps): Promise<any[]>;

package/types/api/session-updates.d.ts

@@ -0,0 +1,26 @@
+import { type FetchLike } from './polling.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface BatchScopeOptions {
+    baseUrl: string;
+    batchId: string;
+    accountId: string;
+    keys: ApiKeyProvider;
+}
+/**
+ * POSTs a batch of per-session step updates (accept/reject decisions, region changes) in one
+ * call — confirmed live to accept multiple sessions at once, one entry per session id.
+ */
+export declare function postStepUpdates(options: BatchScopeOptions, stepUpdatesBySession: Map<string, any[]>, fetchImpl?: FetchLike): Promise<void>;
+/** Commits every pending accept/reject/region change in the batch to the baseline. The endpoint returns nothing useful to the caller — a resolved promise signals success. */
+export declare function saveBaselines(options: BatchScopeOptions, fetchImpl?: FetchLike): Promise<void>;
+export interface RestoreBaselineOptions {
+    baseUrl: string;
+    accountId: string;
+    baselineId: string;
+    baselineRev: string;
+    keys: ApiKeyProvider;
+}
+/** Reverts a session's shared baseline object to the revision it originally ran against. */
+export declare function restoreBaseline(options: RestoreBaselineOptions, fetchImpl?: FetchLike): Promise<void>;
+/** Clears every given session's pending (unsaved) accept/reject/region resolution back to unresolved — a no-op, not an error, for a session with nothing pending. */
+export declare function resetBatchSessions(options: BatchScopeOptions, sessionIds: string[], fetchImpl?: FetchLike): Promise<void>;

package/types/api/tasks.d.ts

@@ -0,0 +1,33 @@
+import { type MakeReqResultsOptions } from './req-results.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export declare const TASK_STATUS_PATH: (taskId: string) => string;
+export declare const TASK_RESULT_PATH: (taskId: string) => string;
+export type TaskDeps = Pick<MakeReqResultsOptions, 'fetch' | 'logger'>;
+/** Extracts the taskId out of a submit response's `Location` (`/api/tasks/{taskId}/status`). */
+export declare function taskIdFromLocation(location: string): string;
+export type TaskStatus<T> = {
+    status: 'running';
+    taskId: string;
+} | {
+    status: 'ready';
+    result: T;
+};
+/**
+ * One probe of a task's status — no client-side polling loop: `running` hands the taskId back so
+ * the caller decides when (and whether) to check again; `201` means done, and the result the
+ * response's `Location` points at is fetched and returned in the same call, so a ready task never
+ * costs the caller a second round trip. `404` (unknown or expired task) is terminal and throws
+ * with the contract's own wording. A *rejected* task also finishes as `201` here — its rejection
+ * surfaces as `503` on the result fetch (TasksController puts it there, not on status); transient
+ * transport failures are the configured req's standard retry policy, not handled here.
+ */
+export declare function getTaskStatus<T = any>(baseUrl: string, taskId: string, keys: ApiKeyProvider, deps?: TaskDeps): Promise<TaskStatus<T>>;
+/**
+ * Fetches a finished task's result and parses it as JSON. The response is gzipped on the wire
+ * when the request advertises `Accept-Encoding` — the transport negotiates and decompresses that
+ * transparently, so no explicit gunzip step exists here (unlike endpoints that return a gzip
+ * *body*, e.g. `fetchPrunedDom`). `503` is the result endpoint's "task rejected" — terminal by
+ * the task contract (and excluded from the retry policy for exactly that reason), thrown with
+ * the contract's own wording.
+ */
+export declare function fetchTaskResult(baseUrl: string, resultUrl: string, keys: ApiKeyProvider, deps?: TaskDeps): Promise<any>;

package/types/api/url-parsing.d.ts

@@ -0,0 +1,20 @@
+export interface ParsedApplitoolsUrl {
+    baseUrl: string;
+    batchId: string;
+    sessionId: string | null;
+    accountId: string;
+}
+/**
+ * Parses an Applitools dashboard URL (session or batch) into its components.
+ * Does not require a sessionId to be present — use parseSessionUrl/parseBatchUrl
+ * for callers that need to enforce one shape or the other.
+ */
+export declare function parseApplitoolsUrl(url: string): ParsedApplitoolsUrl;
+/** Throws if the URL doesn't include a sessionId segment (i.e. it's a batch-only URL). */
+export declare function parseSessionUrl(url: string): ParsedApplitoolsUrl & {
+    sessionId: string;
+};
+/** Batch-scoped: parses the batchId/accountId and always forces sessionId to null, ignoring any session segment. */
+export declare function parseBatchUrl(url: string): ParsedApplitoolsUrl & {
+    sessionId: null;
+};

package/types/common/common.d.ts

@@ -0,0 +1,2 @@
+export * from './region-mapping.js';
+export * from './diff-rects.js';

package/types/common/diff-rects.d.ts

@@ -0,0 +1,39 @@
+import { defaultFsCacheDeps, compareStep, fetchStepDiff } from '../api/api.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+import { type Rect } from '../geometry/geometry.js';
+export interface FetchRawDiffsDeps {
+    fetchStepDiff: typeof fetchStepDiff;
+    compareStep: typeof compareStep;
+    readFile: typeof defaultFsCacheDeps.readFile;
+    writeFile: typeof defaultFsCacheDeps.writeFile;
+}
+export declare const defaultFetchRawDiffsDeps: FetchRawDiffsDeps;
+/**
+ * The two-way visual diff for one step — `image1` in the baseline image's own coordinate
+ * space, `image2` in the checkpoint's, exactly mirroring both the plain `GET .../diff`
+ * endpoint's and `compareStep`'s own response shape. When the step's resolution state is
+ * unchanged from the original test run (`appOutputResolution[stepIndex].isChanged` is not
+ * `true`), the cheap `GET .../diff` endpoint is used as-is — nothing about the step's
+ * effective match settings differs from what the test already ran with. Otherwise, the step's
+ * current effective regions are folded into a fresh `compareStep` request so the returned diff
+ * reflects any region added since the test ran — that (more expensive) result is cached on
+ * disk, keyed by a hash of the full request body, so repeated calls against the same resolved
+ * state don't repeatedly hit the endpoint.
+ *
+ * Takes an already-fetched `rawSession` rather than fetching its own — `batchId`/`sessionId`
+ * are read straight off it (`rawSession.batchId`/`rawSession.id`), so a caller that already has
+ * the raw session in hand (e.g. for its own domId lookups) never pays for a second fetch just
+ * to hand this function a `url` it would otherwise re-resolve into the same session itself.
+ *
+ * `matchSettings` comes straight from `getEffectiveMatchSettings` — the raw session's own
+ * scalars/regions, shaped directly into the request format, with no baseline/checkpoint
+ * pairing and no healing: that shaping only exists for diagnostic region output (which needs
+ * both sides shown, healing in whichever one the raw session doesn't encode), never for a
+ * compare request. Re-deriving "accepted ⇒ checkpoint, else baseline" here would duplicate
+ * logic the raw session's own `annotations` field already resolves — and healing in the other
+ * side would cost an extra network round trip per region for nothing a compare request needs.
+ */
+export declare function fetchRawDiffs(rawSession: any, stepIndex: number, baseUrl: string, accountId: string, keys: ApiKeyProvider, deps?: FetchRawDiffsDeps): Promise<{
+    image1: Rect[];
+    image2: Rect[];
+}>;

package/types/common/region-mapping.d.ts

@@ -0,0 +1,26 @@
+import { getCompatibleSelectors } from '../api/api.js';
+import { type RegionPair } from '../sessions/regions.js';
+import type { ApiKeyProvider } from '../lib/api-key-provider.js';
+export interface MapAnchoredRegionsDeps {
+    baseUrl: string;
+    accountId: string;
+    keys: ApiKeyProvider;
+    fetchDomForSide: (rawSession: any, stepIndex: number, side: 'baseline' | 'checkpoint', baseUrl: string) => Promise<any>;
+    getCompatibleSelectors: typeof getCompatibleSelectors;
+}
+/**
+ * Maps every `anchored` pair's `domSelector` to the other side via one batched
+ * get-compatible-selectors call, resolving each mapped selector's accurate rect locally
+ * against that side's DOM (the API only returns the mapped selector, never a rect). Falls
+ * back to treating every selector as unmapped if the batch call itself fails for some reason
+ * other than a bad input selector (`sessions`'s own `checkRegions` already filters those out).
+ * Mutates each pair's missing side in place. Returns whether anything was attempted (i.e.
+ * `anchored` was non-empty and both sides have an image to map between).
+ *
+ * Lives here, not in `atoms/sessions` (where the rest of the region-healing pipeline this composes
+ * into — `checkRegions`/`clearStaleSelectors`/`healNonAnchoredRegionsBySourceRect` — lives):
+ * this is the one step of that pipeline that actually calls the network (`getCompatibleSelectors`),
+ * and `atoms` must never depend on `api`/`common` (so it can't reference `ApiKeyProvider` or make
+ * network calls) — the orchestration belongs in `common`, which depends on both instead.
+ */
+export declare function mapAnchoredRegionsBySelector(rawSession: any, stepIndex: number, anchored: RegionPair[], deps: MapAnchoredRegionsDeps): Promise<boolean>;