@applitools/eyes-results 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/Applitools-Dev/sdk/compare/js/eyes-results@0.1.0...js/eyes-results@0.2.0) (2026-08-23)
+
+
+### Features
+
+* new SDK package to query eyes results  | AD-15678 ([#4103](https://github.com/Applitools-Dev/sdk/issues/4103)) ([0f97e26](https://github.com/Applitools-Dev/sdk/commit/0f97e26c1be602a7b1dc9db158077c4cd6382c17))

package/LICENSE

@@ -0,0 +1,26 @@
+-  -
+SDK LICENSE AGREEMENT
+IMPORTANT - PLEASE READ CAREFULLY THE TERMS OF THIS LICENSE AGREEMENT (“AGREEMENT”). BY INSTALLING, ACCESSING AND/OR USING THE SOFTWARE (AS DEFINED BELOW), YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT YOU, OR THE COMPANY YOU REPRESENT, (“YOU” OR “LICENSEE”) ARE ENTERING INTO A LEGAL AGREEMENT WITH APPLITOOLS LTD. AND ITS AFFILIATES (“APPLITOOLS”), AND HAVE UNDERSTOOD AND AGREE TO COMPLY WITH, AND BE LEGALLY BOUND BY, THE TERMS AND CONDITIONS OF THIS AGREEMENT. YOU HEREBY WAIVE ANY RIGHTS OR REQUIREMENTS UNDER ANY LAWS OR REGULATIONS IN ANY JURISDICTION WHICH REQUIRE AN ORIGINAL (NON-ELECTRONIC) SIGNATURE OR DELIVERY OR RETENTION OF NON-ELECTRONIC RECORDS, TO THE EXTENT PERMITTED UNDER APPLICABLE LAW. 
+THE SOFTWARE MAY BE USED SOLELY FOR YOUR PERSONAL, NON-COMMERCIAL PURPOSES. FOR COMMERCIAL PURPOSES PLEASE CONTACT THE REGIONAL APPLITOOLS BUSINESS REPRESENTATIVE. 
+1. Definitions. For purposes of this Agreement, the following capitalized terms shall have the following meaning:
+   1. “Documentation” means the user’s guides and technical manuals delivered by Applitools to Licensee.
+   2.  “Feedback” means suggestions, comments or feedback (whether orally or in writing) with respect to the Software.
+   3. “Intellectual Property Rights” means all intangible legal rights, titles and interests evidenced by or embodied in all: (i) inventions (regardless of patentability and whether or not reduced to practice), improvements thereto, patents, patent applications, patent disclosures, together with all reissuances, continuations, continuations in part, revisions, extensions and reexaminations thereof; (ii) trademarks, service marks, trade dress, logos, trade names, corporate names, together with translations, adaptations, derivations and combinations thereof, including goodwill associated therewith, and applications, registrations, and renewals in connection therewith; (iii) any work of authorship, regardless of copyrightable, copyrightable works, copyrights (including moral rights), and applications, registrations and renewals in connection therewith; (iv) mask works and applications, registrations and renewals in connection therewith; (v) trade secrets and Confidential Information; and (vi) other proprietary rights and any other similar rights, in each case on a worldwide basis, and copies and tangible embodiments thereof, in whatever form or medium.
+   4. “License” means the right to use the Software pursuant to Section ‎2.1 to this Agreement.
+   5.  “Software” means Applitools’ software development kit software in object or source code version, Documentation and any updates and upgrade thereto (to the extent delivered).
+1. License
+   1. Grant of License. Subject to the terms and conditions of this Agreement, Applitools grants You, during the Term, a personal, non-exclusive, non-sublicensable, non-transferable, revocable license to: (i) use the Software solely for Your own personal (non-commercial) use and (ii) use and display Applitools’ Marks solely for the purpose of publicizing or advertising that You are using the Software. 
+   2. Documentation. Applitools may make available Documentation to Licensee for Licensee to use solely in connection with Licensee’s use of the Software during the term of this Agreement. Licensee may print or copy the Documentation as needed for its own purposes provided that all copyright notices are included therein. The Documentation shall be considered the Confidential Information of Applitools. 
+   1. Reservation of Rights; Use Restrictions. Other than the rights explicitly granted in this Agreement, Licensee shall have no other rights, express or implied, in the Software. Without limiting the generality of the foregoing, Licensee agrees and undertakes not to: (i) allow any third party to use the Software in any manner, including but not limited to, sell, lease, sublicense or distribute the Software, or any part thereof; (ii) modify, revise, or alter the Software or reverse engineer, decompile, disassemble or otherwise reduce to human-perceivable form the Software’s source code; (iii) copy or allow copies of the Software to be made; (iv) remove, alter or obscure any proprietary notice or identification, including copyright, trademark, patent or other notices, contained in or displayed on or via the Software; (v) use the Software to violate any applicable laws, rules or regulations, or for any unlawful, harmful, irresponsible, or inappropriate purpose, or in any manner that breaches this Agreement, and/or (vi) represent that it possesses any proprietary interest in the Software.
+   1. Third Party Software. Licensee acknowledges and agrees that any third party software (“Third Party Software”) that provided with the Software is provided under the terms of the license attached/linked thereto or, if no such license is attached, such Third Party Software is provided for free and on “AS IS” basis. Applitools is not liable for any losses or damages which may occur resulting from the use of any Third Party Software. Applitools does not possess any proprietary interest in such Third Party Software. 
+   1. Open Source Licenses. The Software includes certain open source code software and materials (as shall be listed in the documentation of the Software) (“Open Source Software”) that are subject to their respective open source licenses (“Open Source Licenses”). Such Open Source Licenses contain a list of conditions with respect to warranty, copyright policy and other provisions. By executing this Agreement, Licensee undertakes to strictly comply with the terms and condition of the Open Source Licenses, as may be amended from time to time. In order to comply with the Open Source Licenses, Licensee shall read the respective licenses or notices, such list of Open Source Licenses may be amended from time to time by Applitools, at its sole discretion. In the event of any inconsistencies or conflicting provisions between the provisions of the Open Source Licenses and the provisions of this Agreement, the provisions of the Open Source Licenses shall prevail. Without derogating from the generality of the foregoing, it is clarified that any Open Source Software is provided on an “AS IS” basis, without indemnity or warranty of any kind, whether express or implied. For clarity, the representations and warranties set forth in Section ‎4 hereunder shall not apply to any Open Source Software.
+1. Title & Ownership. APPLITOOLS DOES NOT SELL OR TRANSFER TITLE IN THE SOFTWARE, OR ANY PART THEREOF, TO LICENSEE. The Documentation, Software (excluding any Open Source Software and Third Party Software therein which are owned by their respective licensors) and/or any copies thereof, including without limitation any derivative works made (regardless of whether such derivative works were made and/or developed pursuant to the request and/or specifications of Licensee, and irrespective of any support and/or assistance Applitools may, will or had received from Licensee, or any third party on its behalf, with respect thereto), as well as any updates or upgrades thereto, if provided to Applitools pursuant to this Agreement, shall remain Applitools’ sole and exclusive property. All Intellectual Property Rights evidenced by or embodied in and/or attached/connected/related to the Software, or part thereof, are and shall be owned solely and exclusively by Applitools. Nothing in this Agreement shall constitute a waiver of Applitools’ Intellectual Property Rights under any law, or be in any way construed or interpreted as such. It is further agreed that to the extent Licensee provides Applitools with Feedback, Licensee acknowledges that any and all rights, including Intellectual Property Rights in such Feedback shall belong exclusively to Applitools and Licensee hereby irrevocably and unconditionally transfers and assigns to Applitools all intellectual property rights in such Feedback and waives any and all moral rights that Licensee may have in respect thereto. It is further understood that use of Feedback, if any, may be made by Applitools at its sole discretion, and that Applitools in no way shall be obliged to make use of any kind of the Feedback or part thereof. 
+1. Warranty. Applitools warrants that to its knowledge it has the right to grant the license under this Agreement. Applitools’ sole liability for any breach of this warranty or any other warranty under this Agreement shall be, at Applitools’ sole discretion: (i) to replace or repair the Software or the applicable portion thereof; or (ii) to terminate this Agreement.
+2. Warranty Exclusions. The warranties set forth in Section ‎4 are contingent upon Licensee’s proper use of the Software, and shall not apply to damage caused by abuse, misuse, alteration, neglect or unauthorized repair or installation, or by the use or attempted use of Software other than that supplied and supported by Applitools. Applitools will use reasonable commercial efforts to repair or replace the Software or the applicable portion thereof, pursuant to the foregoing warranty within thirty (30) days of being so notified.
+1. Warranty Disclaimers. AS BETWEEN LICENSEE AND APPLITOOLS, EXCEPT AS SET IN SECTION ‎4, THE SOFTWARE IS PROVIDED ON AN “AS IS” AND “AS AVAILABLE” BASIS WITHOUT WARRANTIES OF ANY KIND INCLUDING, WITHOUT LIMITATION, REPRESENTATIONS, WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR INTENDED OR PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, THAT THE SOFTWARE WILL MEET LICENSEE’S REQUIREMENTS OR EXPECTATIONS OR WILL ACHIEVE ANY SPECIFIC RESULTS AND THOSE ARISING BY STATUTE OR FROM A COURSE OF DEALING OR USAGE OF TRADE. Applicable law may not allow the exclusion of certain warranties, so to that extent such exclusions may not apply.
+1. High Risk Activities. You acknowledge that the Software is not fault tolerant and is not designed, manufactured, or intended for use or resale as on-line control equipment in hazardous or high risk environments and activities requiring fail-safe performance (such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines and/or devices, or weapons systems) in which the failure of the Software could lead directly to death, personal injury, or severe physical or environmental damage, and You agree not to use or allow the use of the Software or any portion thereof for, or in connection with, any such environment or activity.
+1. Indemnify. You agree that Applitools shall have no liability whatsoever for any use made of the Software by You or any third party. You hereby agree to defend, indemnify and hold harmless Applitools and its affiliates and their respective officers, directors, agents and employees from any and all claims, damages, liabilities, costs, and expenses (including attorney’s fees) arising from claims related to Your use of the Software as well as from Your failure to comply with this Agreement.
+1. Limitation of Liability. UNDER NO CIRCUMSTANCES SHALL APPLITOOLS AND/OR ITS AFFILIATES BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF DATA, REVENUE, BUSINESS OR REPUTATION, THAT ARISES UNDER OR IN CONNECTION WITH THIS AGREEMENT, OR THAT RESULTS FROM THE USE OF, OR THE INABILITY TO USE, THE SOFTWARE. APPLITOOLS’S TOTAL AGGREGATE LIABILITY FOR ANY AND ALL DIRECT DAMAGES AND LOSSES THAT ARISE UNDER OR IN CONNECTION WITH THIS AGREEMENT SHALL NOT IN ANY CIRCUMSTANCE EXCEED THE AMOUNT OF 100.00 (ONE HUNDRED) UNITED STATES DOLLARS. THE FOREGOING LIMITATIONS AND EXCLUSIONS IN THIS SECTION ‎7 SHALL APPLY: (I) EVEN IF APPLITOOLS HAS BEEN ADVISED OF THE POSSIBILITY OF ANY DAMAGES OR LOSSES; (II) EVEN IF ANY REMEDY SET FORTH HEREIN FAILS OF ITS ESSENTIAL PURPOSE; AND (III) REGARDLESS OF THE BASIS OR THEORY OF LIABILITY.
+1. Export Laws. Licensee agrees to comply fully with all U.S., EU, Israeli, and all applicable export laws and regulations to ensure that neither the Software nor any technical data related thereto are exported or re-exported directly or indirectly in violation of, or used for any purposes prohibited by, such laws and regulations. For clarity, and without derogating from Section ‎11 below, in case of any change of any applicable law, policy or regulation, which might affect Applitools’ business, Applitools will have the right to terminate this Agreement and the license granted hereunder and the Licensee shall have no claims regarding such termination. 
+1. Term and Termination. This Agreement shall continue until terminated as set forth in this section (the “Term”). You may terminate this Agreement at any time by removing the Software from Your system and destroying all copies of the Software and Documentation relating to the Software. Unauthorized copying of the Software or otherwise failing to comply with this Agreement will result in automatic immediate termination of this Agreement and will make available to Applitools legal remedies. Applitools reserves the right to terminate this Agreement and the License at any time and without notice. Upon termination of this Agreement, the License will terminate and You: (i) will cease any and all rights to use the Software, and (ii) will remove the Software from all hard drives, networks and other storage media and destroy all copies of the Software in your possession or under your control. The provisions of Sections ‎2.3, ‎2.4, ‎2.5, ‎6, ‎7, ‎8, ‎9, 10, ‎11 and ‎12 shall survive the termination, expiration or other ending of this Agreement.
+1. Miscellaneous. This Agreement represents the complete agreement concerning the Software between You and Applitools and supersedes all prior agreements and representations between You and Applitools. If any provision of this Agreement is held to be unenforceable for any reason, such provision shall be reformed only to the extent necessary to make it enforceable. Any waiver of any provision of this Agreement will be effective only if in writing and signed by Applitools. This Agreement is personal to You and may not be assigned or transferred for any reason whatsoever without the consent of Applitools and any action or conduct in violation of the foregoing shall be void and without effect. Applitools expressly reserves the right to assign this Agreement and to delegate any of its obligations hereunder. This Agreement are governed by and construed under the laws of the State of Israel, excluding its conflicts of law rules. You expressly agree that the exclusive jurisdiction for any claim or action arising out of or relating to this Agreement shall be the courts located in Tel Aviv, Israel, and You further agree and submit to the exercise of personal jurisdiction of such courts for the purpose of litigating any such claim or action. In any action or proceeding to enforce rights under this Agreement, the prevailing party shall be entitled to recover costs and attorneys’ fees.

package/dist/api/api.js

@@ -0,0 +1,17 @@
+export * from './url-parsing.js';
+export * from './polling.js';
+export * from './req-results.js';
+export * from './tasks.js';
+export * from './fs-cache.js';
+export * from './gzip.js';
+export * from './dom-fetch.js';
+export * from './dom-diff.js';
+export * from './image-fetch.js';
+export * from './session-fetch.js';
+export * from './selector-mapping.js';
+export * from './diff-fetch.js';
+export * from './session-updates.js';
+export * from './find-regions.js';
+export * from './session-history-fetch.js';
+export * from './compare-step.js';
+export * from './same-diff-as.js';

package/dist/api/compare-step.js

@@ -0,0 +1,20 @@
+import { postJson, getJsonResult, reqTransport } from './polling.js';
+/**
+ * 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 async function compareStep(body, options, fetchImpl = reqTransport) {
+    const { baseUrl, accountId, keys } = options;
+    const apiKey = keys.getReadKey();
+    const url = `${baseUrl}/api/images/compare?accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const response = await postJson(url, body, fetchImpl);
+    return getJsonResult(response, apiKey, fetchImpl, undefined, url);
+}

package/dist/api/diff-fetch.js

@@ -0,0 +1,13 @@
+import { getJson, reqTransport } from './polling.js';
+/**
+ * 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 async function fetchStepDiff(options, fetchImpl = reqTransport) {
+    const { baseUrl, batchId, sessionId, stepIndex, accountId, keys } = options;
+    const url = `${baseUrl}/api/sessions/batches/${batchId}/${sessionId}/${stepIndex}/diff?accountId=${accountId}&apiKey=${encodeURIComponent(keys.getReadKey())}`;
+    const data = await getJson(url, fetchImpl);
+    return { image1: data.image1 ?? [], image2: data.image2 ?? [] };
+}

package/dist/api/dom-diff.js

@@ -0,0 +1,139 @@
+import * as crypto from 'crypto';
+import { defaultFsCacheDeps, cacheFilePath } from './fs-cache.js';
+import { makeReqResults } from './req-results.js';
+import { getTaskStatus, taskIdFromLocation, TASK_RESULT_PATH } from './tasks.js';
+export const DOM_DIFF_PATH = '/api/images/dom/diff';
+export const defaultFetchDomDiffDeps = {
+    ...defaultFsCacheDeps,
+};
+/**
+ * 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 async function fetchDomDiff(baseUrl, baselineDomId, checkpointDomId, keys, deps = defaultFetchDomDiffDeps) {
+    const cachePath = domDiffCachePath(baselineDomId, checkpointDomId, deps);
+    const cached = readCachedAlignment(cachePath, deps);
+    if (cached)
+        return { status: 'ready', alignment: cached };
+    const req = makeReqResults({ serverUrl: baseUrl, apiKey: keys.getReadKey(), ...deps });
+    const response = await req(DOM_DIFF_PATH, {
+        name: 'fetchDomDiff',
+        query: { baselineDomId, checkpointDomId },
+        expected: [200, 202],
+    });
+    if (response.status === 202) {
+        const location = response.headers.get('Location');
+        if (!location)
+            throw new Error('DOM diff task started (202) but no status Location header was returned');
+        const taskId = taskIdFromLocation(location);
+        const task = await getTaskStatus(baseUrl, taskId, keys, deps);
+        return cacheIfReady(task, taskId, cachePath, deps);
+    }
+    const alignment = assertDomAlignment(await response.json(), DOM_DIFF_PATH, response.status);
+    deps.writeFile(cachePath, JSON.stringify(alignment));
+    return { status: 'ready', alignment };
+}
+/**
+ * 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 async function checkDomDiffTask(baseUrl, taskId, baselineDomId, checkpointDomId, keys, deps = defaultFetchDomDiffDeps) {
+    const cachePath = domDiffCachePath(baselineDomId, checkpointDomId, deps);
+    const cached = readCachedAlignment(cachePath, deps);
+    if (cached)
+        return { status: 'ready', alignment: cached };
+    const task = await getTaskStatus(baseUrl, taskId, keys, deps);
+    return cacheIfReady(task, taskId, cachePath, deps);
+}
+function domDiffCachePath(baselineDomId, checkpointDomId, deps) {
+    const cacheKey = crypto.createHash('sha256').update(`${baselineDomId}:${checkpointDomId}`).digest('hex').slice(0, 16);
+    return cacheFilePath(deps, 'eyes-dom-diff', cacheKey, 'json');
+}
+function cacheIfReady(task, taskId, cachePath, deps) {
+    if (task.status === 'running')
+        return task;
+    const alignment = assertDomAlignment(task.result, TASK_RESULT_PATH(taskId), 200);
+    deps.writeFile(cachePath, JSON.stringify(alignment));
+    return { status: 'ready', alignment };
+}
+/**
+ * Reads a cached alignment, treating an unusable entry (unparseable, or not alignment-shaped) as a
+ * miss rather than a failure: the cache is content-addressed and reproducible, so re-fetching the
+ * pair and overwriting is always safe — whereas the alternative is a truncated or old-shape file
+ * (an interrupted write, a pre-`assertDomAlignment` cache) failing every future call for that pair
+ * forever, since the entry has no TTL and nothing else would ever replace it.
+ */
+function readCachedAlignment(cachePath, deps) {
+    const cached = deps.readFile(cachePath);
+    if (cached === null)
+        return null;
+    try {
+        const parsed = JSON.parse(cached);
+        return isDomAlignment(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isDomAlignment(value) {
+    const candidate = value;
+    return (typeof candidate === 'object' &&
+        candidate !== null &&
+        typeof candidate.matches === 'object' &&
+        candidate.matches !== null &&
+        // An array is a `typeof 'object'` too, and `matches` is looked up by nodeId — every lookup in an
+        // array misses, so `{matches: [], diff: []}` would cache as a permanently valid-looking
+        // alignment that answers `found: false` for every node instead of failing here.
+        !Array.isArray(candidate.matches) &&
+        Array.isArray(candidate.diff));
+}
+/**
+ * Guards the one cast that asserts the wire shape. The backend's aligner is a byte-identical port
+ * of the client engine this package used to carry, and these types were verified field-for-field
+ * against its own fixture suite, so a healthy server can't produce anything else — but the pair
+ * cache has no TTL, so a single `null`, `{}` or old-shape 200 that got through would be persisted
+ * and then returned as a ready alignment for good, not just for this run. Worse, it surfaces far
+ * from here: `extractNodeDiff` opens with `targetNodeId in alignment.matches`, so a bad value
+ * becomes `TypeError: Cannot use 'in' operator` inside `sessions/dom.ts` with nothing naming the
+ * endpoint that produced it. Checking the two fields every consumer reads keeps such a response
+ * out of the cache and names the endpoint and status in the failure instead.
+ */
+function assertDomAlignment(value, endpoint, status) {
+    if (!isDomAlignment(value)) {
+        throw new Error(`${endpoint} (${status}) did not return a DOM alignment — expected an object with ` +
+            `\`matches\` and \`diff\`, got ${preview(value)}`);
+    }
+    return value;
+}
+/** A bounded rendering of an unexpected body — enough to recognize it in a log, never the whole
+ * response (an old-shape alignment would be megabytes). */
+function preview(value) {
+    if (value === undefined)
+        return 'undefined';
+    const json = JSON.stringify(value) ?? String(value);
+    return json.length > 200 ? `${json.slice(0, 200)}…` : json;
+}

package/dist/api/dom-fetch.js

@@ -0,0 +1,39 @@
+import { Buffer } from 'buffer';
+import { defaultFsCacheDeps, cacheFilePath } from './fs-cache.js';
+import { gunzip } from './gzip.js';
+import { makeReqResults } from './req-results.js';
+export const PRUNED_DOM_PATH = (domId) => `/api/images/dom/${domId}/pruned`;
+export const defaultFetchPrunedDomDeps = {
+    ...defaultFsCacheDeps,
+};
+/**
+ * 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 async function fetchPrunedDom(options, deps = defaultFetchPrunedDomDeps) {
+    const { baseUrl, domId, keys } = options;
+    const cachePath = cacheFilePath(deps, 'eyes', domId, 'json');
+    const cached = deps.readFile(cachePath);
+    if (cached !== null)
+        return JSON.parse(cached);
+    const req = makeReqResults({ serverUrl: baseUrl, apiKey: keys.getReadKey(), ...deps });
+    const response = await req(PRUNED_DOM_PATH(domId), { name: 'fetchPrunedDom', expected: 200 });
+    const buffer = Buffer.from(await response.arrayBuffer());
+    let text;
+    try {
+        text = (await gunzip(buffer)).toString('utf8');
+    }
+    catch {
+        text = buffer.toString('utf8'); // not a gzip body — already plain (or transport-decompressed)
+    }
+    const prunedDom = JSON.parse(text);
+    deps.writeFile(cachePath, JSON.stringify(prunedDom));
+    return prunedDom;
+}

package/dist/api/find-regions.js

@@ -0,0 +1,24 @@
+import { postJson, getJsonResult, reqTransport } from './polling.js';
+/**
+ * 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 async function findRegionsInImages(sourceImage, regions, targets, options, fetchImpl = reqTransport, sleepFn) {
+    const { baseUrl, accountId, keys } = options;
+    const apiKey = keys.getReadKey();
+    const url = `${baseUrl}/api/images/find?firstOnly=false&accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const response = await postJson(url, { sourceImage, regions, targets }, fetchImpl);
+    return getJsonResult(response, apiKey, fetchImpl, sleepFn, url);
+}

package/dist/api/fs-cache.js

@@ -0,0 +1,19 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+export const defaultFsCacheDeps = {
+    readFile: p => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null),
+    writeFile: (p, contents) => fs.writeFileSync(p, contents),
+    cacheDir: os.tmpdir(),
+};
+/**
+ * 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 function cacheFilePath(deps, prefix, key, ext = 'json') {
+    const safeKey = key.replace(/[~,]/g, '_');
+    // path.posix.join (not path.join) so the result is deterministic across platforms —
+    // Node's fs APIs accept forward slashes on Windows too.
+    return path.posix.join(deps.cacheDir, `${prefix}-${safeKey}.${ext}`);
+}

package/dist/api/gzip.js

@@ -0,0 +1,12 @@
+import * as zlib from 'zlib';
+/** Promisified zlib.gunzip. Rejects if the input isn't valid gzip data — callers decide the fallback. */
+export function gunzip(buffer) {
+    return new Promise((resolve, reject) => {
+        zlib.gunzip(buffer, (err, result) => {
+            if (err)
+                reject(err);
+            else
+                resolve(result);
+        });
+    });
+}

package/dist/api/image-fetch.js

@@ -0,0 +1,31 @@
+import { Buffer } from 'buffer';
+import { reqTransport } from './polling.js';
+/**
+ * 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 async function fetchCheckpointImage(options, fetchImpl = reqTransport) {
+    const { baseUrl, batchId, sessionId, stepIndex, accountId, keys, area } = options;
+    const apiStepIndex = stepIndex + 1; // images/checkpoint uses 1-based step index (matches UI URL /steps/N convention)
+    const path = area
+        ? `/api/sessions/batches/${batchId}/${sessionId}/steps/${apiStepIndex}/images/checkpoint.clip(${area.left};${area.top};${area.width};${area.height})`
+        : `/api/sessions/batches/${batchId}/${sessionId}/steps/${apiStepIndex}/images/checkpoint`;
+    const url = `${baseUrl}${path}?accountId=${accountId}&apiKey=${encodeURIComponent(keys.getReadKey())}`;
+    const response = await fetchImpl(url);
+    if (!response.ok)
+        throw new Error(`Failed to fetch checkpoint image: ${response.status} ${response.statusText}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+/** A baseline or checkpoint screenshot by its own image id, as a raw PNG buffer — same binary-response exception as `fetchCheckpointImage`. */
+export async function fetchImageById(options, fetchImpl = reqTransport) {
+    const { baseUrl, imageId, keys, area } = options;
+    let path = `/api/images/${imageId}`;
+    if (area)
+        path += `.clip(${area.left};${area.top};${area.width};${area.height})`;
+    const url = `${baseUrl}${path}?apiKey=${encodeURIComponent(keys.getReadKey())}`;
+    const response = await fetchImpl(url);
+    if (!response.ok)
+        throw new Error(`Failed to fetch image: ${response.status} ${response.statusText}`);
+    return Buffer.from(await response.arrayBuffer());
+}

package/dist/api/polling.js

@@ -0,0 +1,117 @@
+import { makeReqResults } from './req-results.js';
+/**
+ * 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 const reqTransport = (url, init) => {
+    const { origin, searchParams } = new URL(url);
+    const req = makeReqResults({ serverUrl: origin, apiKey: searchParams.get('apiKey') ?? '' });
+    return req(url, (init ?? {}));
+};
+/** POST a JSON body. */
+export async function postJson(url, body, fetchImpl = reqTransport) {
+    return fetchImpl(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+}
+/** GET and parse a JSON response, throwing a descriptive error on a non-ok status. */
+export async function getJson(url, fetchImpl = reqTransport) {
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`Request failed: ${response.status} ${response.statusText}${text ? ` — ${text}` : ''}`);
+    }
+    return response.json();
+}
+/**
+ * A `Location` header may legally be relative (RFC 9110) and Node's fetch rejects relative URLs,
+ * so resolve it against the URL of the request that produced it. An absolute location needs no
+ * base; a relative one without a base is unusable — fail here, naming the value, rather than as
+ * an opaque invalid-URL error from the fetch that would have consumed it.
+ */
+function resolveLocation(location, base) {
+    if (base)
+        return new URL(location, base).toString();
+    if (URL.canParse(location))
+        return location;
+    throw new Error(`Cannot resolve relative Location header "${location}" — no request URL to resolve it against`);
+}
+/** Parses a response body as JSON, tolerating an empty body (e.g. a 204) by returning `undefined` instead of throwing on `JSON.parse('')`. */
+async function parseJsonBody(response) {
+    const text = await response.text();
+    return text ? JSON.parse(text) : undefined;
+}
+/**
+ * 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 async function pollUntilResult(statusUrl, apiKey, fetchImpl = reqTransport, sleepFn = ms => new Promise(resolve => setTimeout(resolve, ms))) {
+    const maxAttempts = 60;
+    for (let i = 0; i < maxAttempts; i++) {
+        const sep = statusUrl.includes('?') ? '&' : '?';
+        const response = await fetchImpl(`${statusUrl}${sep}apiKey=${encodeURIComponent(apiKey)}`);
+        if (response.status === 200) {
+            await sleepFn(1000);
+            continue;
+        }
+        if (response.status === 201) {
+            const location = response.headers.get('Location');
+            if (!location) {
+                throw new Error('Job finished (201) but no result Location header was returned');
+            }
+            // `response.url` is the post-redirect URL when populated, but is '' under req's HTTP/2
+            // rewrap — fall back to the URL this poll actually requested.
+            const resultUrl = resolveLocation(location, response.url || statusUrl);
+            const resultSep = resultUrl.includes('?') ? '&' : '?';
+            const resultResponse = await fetchImpl(`${resultUrl}${resultSep}apiKey=${encodeURIComponent(apiKey)}`);
+            if (!resultResponse.ok) {
+                const text = await resultResponse.text().catch(() => '');
+                throw new Error(`Failed to fetch job result: ${resultResponse.status} ${resultResponse.statusText}${text ? ` — ${text}` : ''}`);
+            }
+            return parseJsonBody(resultResponse);
+        }
+        throw new Error(`Unexpected poll status: ${response.status} ${response.statusText}`);
+    }
+    throw new Error('Polling timed out after 60 attempts');
+}
+/**
+ * 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 async function getJsonResult(response, apiKey, fetchImpl = reqTransport, sleepFn, requestUrl) {
+    if (response.status === 202) {
+        const location = response.headers.get('Location');
+        if (!location) {
+            throw new Error('Job started (202) but no status Location header was returned');
+        }
+        return pollUntilResult(resolveLocation(location, response.url || requestUrl), apiKey, fetchImpl, sleepFn);
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`Request failed: ${response.status} ${response.statusText}${text ? ` — ${text}` : ''}`);
+    }
+    return parseJsonBody(response);
+}

package/dist/api/req-results.js

@@ -0,0 +1,77 @@
+import { makeReq } from '@applitools/req';
+// Same convention as core-base's reqEyes: `expected` is enforced by an afterResponse hook, so
+// call sites branch only on the statuses that carry meaning for them.
+function handleUnexpectedResponse() {
+    return {
+        async afterResponse({ request, response, options }) {
+            const expected = options?.expected;
+            if (expected === undefined)
+                return;
+            if (Array.isArray(expected) ? expected.includes(response.status) : expected === response.status)
+                return;
+            const body = await response
+                .clone()
+                .text()
+                .catch(() => '');
+            const message = `Request "${options?.name ?? request.url}" failed due to unexpected status ` +
+                `${response.statusText}(${response.status})${body ? ` and body "${body}"` : ''}`;
+            options?.logger?.error(message);
+            throw new Error(message);
+        },
+    };
+}
+// req counts retries by mutating `attempt` on the very `Retry` object it was handed, and never
+// resets it: `mergeOptions` rebuilds the retry *array* per request, but `[].concat(obj)` copies the
+// element reference, so one literal shared across requests is one budget shared across requests —
+// after `limit` cumulative retries every later request is silently fire-once, and before that a
+// fresh request's first backoff is read from the climbed index (3200 ms instead of 200 ms).
+// `afterOptionsMerged` runs once per request on that request's own merged options, so replacing the
+// retry entries with fresh copies there makes the budget per-request no matter how long the
+// instance that carries the policy lives.
+function isolateRetryPerRequest() {
+    return {
+        afterOptionsMerged({ options }) {
+            if (!options.retry)
+                return;
+            const retries = Array.isArray(options.retry) ? options.retry : [options.retry];
+            return { ...options, retry: retries.map(retry => ({ ...retry, attempt: undefined })) };
+        },
+    };
+}
+/**
+ * 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 function makeReqResults({ serverUrl, apiKey, fetch, logger }) {
+    return makeReq({
+        baseUrl: serverUrl,
+        query: { apiKey },
+        retry: {
+            limit: 5,
+            timeout: [200, 400, 800, 1600, 3200],
+            // 500/503 deliberately excluded: on a task-status probe they are terminal contract signals
+            // (503 = task rejected), not transient blips — they must surface immediately.
+            statuses: [429, 502, 504],
+            codes: ['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN', 'ENOTFOUND'],
+        },
+        // core-base reqEyes's defaults. Callers cap attempts, not wall-clock, so a stalled request
+        // needs its own timeout to not hang forever.
+        requestTimeout: 30000,
+        connectionTimeout: 300000,
+        hooks: [isolateRetryPerRequest(), handleUnexpectedResponse()],
+        fetch,
+        logger,
+    });
+}

package/dist/api/same-diff-as.js

@@ -0,0 +1,25 @@
+import { postJson, getJsonResult, reqTransport } from './polling.js';
+/**
+ * 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 async function findSameDiffSteps(body, options, fetchImpl = reqTransport) {
+    const { baseUrl, accountId, keys } = options;
+    const apiKey = keys.getReadKey();
+    const url = `${baseUrl}/api/sessions/steps/samediffas?accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const response = await postJson(url, body, fetchImpl);
+    return (await getJsonResult(response, apiKey, fetchImpl, undefined, url)) ?? [];
+}

package/dist/api/selector-mapping.js

@@ -0,0 +1,15 @@
+import { postJson, getJsonResult, reqTransport } from './polling.js';
+/**
+ * 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 async function getCompatibleSelectors(options, image1, image2, selectors, fetchImpl = reqTransport) {
+    const { baseUrl, accountId, keys } = options;
+    const apiKey = keys.getReadKey();
+    const url = `${baseUrl}/api/images/get-compatible-selectors?accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const response = await postJson(url, { image1, image2, selectors }, fetchImpl);
+    const data = await getJsonResult(response, apiKey, fetchImpl, undefined, url);
+    return data.selectors;
+}