@applitools/core-nlp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.1.0](https://github.com/Applitools-Dev/sdk/compare/js/core-nlp@0.0.1...js/core-nlp@0.1.0) (2026-09-15)
+
+
+### Features
+
+* NLP authoring (eyes.run) for eyes-playwright via the Eyes NLP service | AD-13296 ([#3936](https://github.com/Applitools-Dev/sdk/issues/3936)) ([c0f81d1](https://github.com/Applitools-Dev/sdk/commit/c0f81d1d3237945001ddf918954ee22a962aea03))
+
+
+### Dependencies
+
+* @applitools/core-base bumped to 1.39.0
+  #### Features
+
+  * NLP authoring (eyes.run) for eyes-playwright via the Eyes NLP service | AD-13296 ([#3936](https://github.com/Applitools-Dev/sdk/issues/3936)) ([c0f81d1](https://github.com/Applitools-Dev/sdk/commit/c0f81d1d3237945001ddf918954ee22a962aea03))

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/account.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeNlpAccount = exports.resolveEyesServerSettings = void 0;
+const core_base_1 = require("@applitools/core-base");
+const utils = __importStar(require("@applitools/utils"));
+const constants_1 = require("./constants");
+/**
+ * Mirrors core's `populateEyesServerSettings`, which lives above core-base and can't be imported
+ * here. Callers comparing two credential sets must both come through this: an unset config value
+ * and the `APPLITOOLS_*` variable it falls back to are the same account.
+ */
+function resolveEyesServerSettings(server = {}) {
+    var _a, _b, _c, _d, _e;
+    const proxyUrl = utils.general.getEnvValue('PROXY_URL');
+    return {
+        eyesServerUrl: (_c = (_b = (_a = server.serverUrl) !== null && _a !== void 0 ? _a : utils.general.getEnvValue('EYES_SERVER_URL')) !== null && _b !== void 0 ? _b : utils.general.getEnvValue('SERVER_URL')) !== null && _c !== void 0 ? _c : constants_1.DEFAULT_EYES_SERVER_URL,
+        apiKey: (_d = server.apiKey) !== null && _d !== void 0 ? _d : utils.general.getEnvValue('API_KEY'),
+        proxy: (_e = server.proxy) !== null && _e !== void 0 ? _e : (proxyUrl ? { url: proxyUrl } : undefined),
+    };
+}
+exports.resolveEyesServerSettings = resolveEyesServerSettings;
+/**
+ * Entitlement is read from renderinfo, where the NLP endpoint appears only when the flag is on.
+ * Goes through core-base's **cached** requests singleton so a caller probing before opening a
+ * session shares that request rather than adding one.
+ *
+ * Never throws and never outlives `timeout`: it gates an optional capability from
+ * latency-sensitive paths, and the request layer retries 5xx/network behind a multi-minute
+ * connection timeout. Actual NLP use still fails loudly later, with a precise message.
+ */
+async function probeNlpAccount(server = {}, { timeout = constants_1.DEFAULT_ACCOUNT_PROBE_TIMEOUT, logger } = {}) {
+    const settings = resolveEyesServerSettings(server);
+    if (!settings.apiKey)
+        return { enabled: false, reason: 'no-api-key' };
+    let timer;
+    const deadline = new Promise(resolve => {
+        var _a;
+        timer = setTimeout(() => resolve({ enabled: false, reason: 'unreachable', message: `account lookup timed out after ${timeout}ms` }), timeout);
+        // Never hold the process open for an optional capability's probe.
+        (_a = timer.unref) === null || _a === void 0 ? void 0 : _a.call(timer);
+    });
+    try {
+        return await Promise.race([lookup(), deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    async function lookup() {
+        var _a;
+        try {
+            const account = await (0, core_base_1.makeCoreRequestsWithCache)({ logger }).getAccountInfo({
+                settings: { eyesServerUrl: settings.eyesServerUrl, apiKey: settings.apiKey, proxy: settings.proxy },
+                logger,
+            });
+            if (account.nlpServer)
+                return { enabled: true };
+            // An explicit `false` is the server's authoritative denial; anything else (entitled but no
+            // endpoint, or a server that never mentions the flag) is an environment gap, not a setting.
+            if (account.nlpEnabled === false)
+                return { enabled: false, reason: 'not-entitled' };
+            return { enabled: false, reason: 'service-unavailable' };
+        }
+        catch (error) {
+            return { enabled: false, reason: 'unreachable', message: (_a = error === null || error === void 0 ? void 0 : error.message) !== null && _a !== void 0 ? _a : String(error) };
+        }
+    }
+}
+exports.probeNlpAccount = probeNlpAccount;

package/dist/ax-provider.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeRemoteAXProvider = void 0;
+const core_base_1 = require("@applitools/core-base");
+const req_1 = require("@applitools/req");
+const account_1 = require("./account");
+/**
+ * `HttpRemoteAXProvider` is injected because it is runtime-only (loaded via `importESM` in nlp.ts).
+ * The service is resolved eagerly so a missing feature flag fails here, before any CDP work.
+ */
+async function makeRemoteAXProvider(HttpRemoteAXProvider, options = {}, { logger } = {}) {
+    const { eyesServerUrl, apiKey, proxy } = (0, account_1.resolveEyesServerSettings)(options);
+    // core-base validates the key only by round-tripping and reading a 401; this fails immediately.
+    if (!apiKey)
+        throw new core_base_1.MissingApiKeyError();
+    const resolver = (0, core_base_1.makeNLPServiceResolver)({ settings: { eyesServerUrl, apiKey, proxy }, logger });
+    const { serviceUrl } = await resolver.getService();
+    // The built-in transport is the global fetch: no proxy awareness, and it calls `.json()` on
+    // whatever comes back. Ours keeps the wire format and adds both.
+    const axClient = proxy ? (0, req_1.makeReq)({ proxy }) : undefined;
+    const axFetch = async ({ url, method, token, body }) => {
+        const request = {
+            method,
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+            body: JSON.stringify(body),
+        };
+        const response = axClient ? await axClient(url, request) : await globalThis.fetch(url, request);
+        return {
+            async json() {
+                var _a;
+                const contentType = (_a = response.headers.get('content-type')) !== null && _a !== void 0 ? _a : undefined;
+                if (!response.ok || !(contentType === null || contentType === void 0 ? void 0 : contentType.includes('json'))) {
+                    throw new core_base_1.NlpServiceRequestError({ url, status: response.status, contentType });
+                }
+                return response.json();
+            },
+        };
+    };
+    return new HttpRemoteAXProvider({
+        url: serviceUrl,
+        // Called per AX request; the resolver re-fetches renderinfo only as the token nears expiry.
+        getAuthToken: async () => (await resolver.getService()).accessToken,
+        fetch: axFetch,
+    });
+}
+exports.makeRemoteAXProvider = makeRemoteAXProvider;

package/dist/constants.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EYES_SERVER_URL = exports.MIN_NODE_VERSION = exports.NLP_WEB_RUNNER = exports.DEFAULT_ACCOUNT_PROBE_TIMEOUT = exports.DEFAULT_FIND_TIMEOUT = exports.NLP_LOG_PREFIX = void 0;
+/** Prefixes every NLP message, so a line is identifiable even where the logger's tags aren't shown. */
+exports.NLP_LOG_PREFIX = '[nlp]';
+exports.DEFAULT_FIND_TIMEOUT = 10000;
+/** The launch-time probe sits on the browser-launch path, so it must fail fast, not just closed. */
+exports.DEFAULT_ACCOUNT_PROBE_TIMEOUT = 10000;
+exports.NLP_WEB_RUNNER = '@applitools/nlp-web-runner';
+/**
+ * Enforced at runtime too: the optional-dependency mechanism keeps the engine off older Node at
+ * install time, but a force-installed setup can smuggle it onto Node < 24, where `import()` may
+ * succeed yet behaviour is undefined.
+ */
+exports.MIN_NODE_VERSION = '24.16.0';
+exports.DEFAULT_EYES_SERVER_URL = 'https://eyesapi.applitools.com';

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NlpStepError = exports.resolveEyesServerSettings = exports.probeNlpAccount = exports.makeNlp = void 0;
+var nlp_1 = require("./nlp");
+Object.defineProperty(exports, "makeNlp", { enumerable: true, get: function () { return nlp_1.makeNlp; } });
+var account_1 = require("./account");
+Object.defineProperty(exports, "probeNlpAccount", { enumerable: true, get: function () { return account_1.probeNlpAccount; } });
+Object.defineProperty(exports, "resolveEyesServerSettings", { enumerable: true, get: function () { return account_1.resolveEyesServerSettings; } });
+// Re-exported so an SDK can recognise a failed NLP step (and re-wrap it in its own user-facing
+// error type) without taking a direct dependency on @applitools/core-base.
+var core_base_1 = require("@applitools/core-base");
+Object.defineProperty(exports, "NlpStepError", { enumerable: true, get: function () { return core_base_1.NlpStepError; } });

package/dist/messages.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.messages = void 0;
+const constants_1 = require("./constants");
+exports.messages = {
+    /** Replaces the raw internal failure, which surfaces as e.g. undici's `Socks5ProxyAgent not found`. */
+    engineUnavailable: (detail) => `NLP is unavailable: eyes.run requires Node >= ${constants_1.MIN_NODE_VERSION} with the optional engine ` +
+        `(${constants_1.NLP_WEB_RUNNER}) installed. (${detail})`,
+    missingApiKey: () => 'NLP requires an API key: set it in the configuration or via APPLITOOLS_API_KEY.',
+    unresolvedCdpTarget: () => 'Could not resolve a CDP connection target for the NLP runner',
+    runAborted: () => 'The NLP run was aborted before it finished, so the instruction did not execute. This usually ' +
+        'means the page navigated away, the browser closed, or the run exceeded its deadline.',
+};

package/dist/nlp.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeNlp = exports.reportStep = void 0;
+const core_base_1 = require("@applitools/core-base");
+const ax_provider_1 = require("./ax-provider");
+const constants_1 = require("./constants");
+const messages_1 = require("./messages");
+// Native dynamic import that survives CommonJS transpilation. @applitools/nlp-web-runner is
+// ESM-only (no `require`/`default` export condition), and the Mocha harness transpiles via SWC
+// targeting CJS, which would down-level a literal `import()` into `require()` and fail to load it.
+// Routing through a Function constructor keeps the call site opaque to SWC/TS so the native
+// `import()` stays.
+const importESM = new Function('specifier', 'return import(specifier)');
+const [MIN_NODE_MAJOR, MIN_NODE_MINOR] = constants_1.MIN_NODE_VERSION.split('.').map(Number);
+function nodeSupportsNlp() {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    return major > MIN_NODE_MAJOR || (major === MIN_NODE_MAJOR && minor >= MIN_NODE_MINOR);
+}
+let modulesPromise;
+async function loadNlpModules() {
+    if (!nodeSupportsNlp()) {
+        throw new Error(messages_1.messages.engineUnavailable(`current Node ${process.versions.node}`));
+    }
+    if (!modulesPromise) {
+        modulesPromise = importESM(constants_1.NLP_WEB_RUNNER)
+            .then(runnerMod => ({
+            makeBrowser: runnerMod.makeBrowser,
+            makeRunner: runnerMod.makeRunner,
+            HttpRemoteAXProvider: runnerMod.HttpRemoteAXProvider,
+        }))
+            .catch(error => {
+            var _a;
+            // Reset the cache on failure so a later call can retry.
+            modulesPromise = undefined;
+            throw new Error(messages_1.messages.engineUnavailable((_a = error === null || error === void 0 ? void 0 : error.message) !== null && _a !== void 0 ? _a : String(error)));
+        });
+    }
+    return modulesPromise;
+}
+function makeNlpLogger(logger) {
+    if (!logger)
+        return undefined;
+    // Forwarded, not pre-joined: the engine logs objects and joining renders them "[object Object]".
+    const write = (...args) => logger.log(constants_1.NLP_LOG_PREFIX, ...args);
+    return { log: write, error: write, trace: write, debug: write };
+}
+/**
+ * `testStep` is carried so a line reads on its own, without matching it back to a call site.
+ * @internal
+ */
+function reportStep(logger, testStep, result) {
+    if (!logger)
+        return;
+    const payload = {
+        testStep,
+        stepSuccessful: result.stepSuccessful,
+        status: result.status,
+    };
+    if (!result.stepSuccessful && result.reason)
+        payload.reason = result.reason;
+    logger.log(constants_1.NLP_LOG_PREFIX, JSON.stringify(payload));
+}
+exports.reportStep = reportStep;
+function makeNlp(adapter, options = {}) {
+    var _a, _b, _c;
+    // Tagged once, so every NLP line is greppable as `(nlp)` in the Eyes log — and the engine's own
+    // diagnostics as `(nlp/engine)`, which is the axis a debug flag used to stand in for.
+    const logger = (_a = options.logger) === null || _a === void 0 ? void 0 : _a.extend({ tags: ['nlp'] });
+    const engineLogger = logger === null || logger === void 0 ? void 0 : logger.extend({ tags: ['engine'] });
+    const findTimeout = (_c = (_b = options.timeouts) === null || _b === void 0 ? void 0 : _b.findTimeout) !== null && _c !== void 0 ? _c : constants_1.DEFAULT_FIND_TIMEOUT;
+    // The browser handle is ours: the runner receives it as `automator` but does not own it,
+    // so every path that created a browser must also close it (createRunner on failure,
+    // dispose() otherwise). Closing is best-effort — the CDP socket may already be gone.
+    let browser;
+    let runnerPromise;
+    async function closeBrowser(instance) {
+        if (!instance)
+            return;
+        try {
+            if (instance.close)
+                await instance.close();
+            else if (instance.dispose)
+                await instance.dispose();
+        }
+        catch {
+            // already closed / connection gone — nothing left to release
+        }
+    }
+    async function createRunner(step) {
+        var _a;
+        // Availability first: these checks do no CDP work, while getCdpTarget() does — an
+        // unsupported-Node user should see the friendly "NLP is unavailable" message (and a
+        // flag-less account the "NLP is not enabled" one) before the adapter probes anything
+        // (on old Node the probe itself can crash with a raw `fetch is not defined`).
+        let modules;
+        let axProvider;
+        try {
+            modules = await loadNlpModules();
+            // AX-tree extraction/description/finding is served by the Eyes NLP AX service; the
+            // service URL and its Bearer token come from the Eyes server's renderinfo endpoint.
+            axProvider = await (0, ax_provider_1.makeRemoteAXProvider)(modules.HttpRemoteAXProvider, options.server, { logger });
+        }
+        catch (error) {
+            throw new core_base_1.NlpStepError(step, { message: (_a = error === null || error === void 0 ? void 0 : error.message) !== null && _a !== void 0 ? _a : String(error) });
+        }
+        const target = await adapter.getCdpTarget();
+        if (!target || Object.keys(target).length === 0) {
+            throw new core_base_1.NlpStepError(step, { message: messages_1.messages.unresolvedCdpTarget() });
+        }
+        const browserInstance = await modules.makeBrowser(target);
+        browser = browserInstance;
+        try {
+            const runnerInstance = await modules.makeRunner({
+                automator: browserInstance,
+                axProvider,
+                timeouts: { findTimeout },
+                logger: makeNlpLogger(engineLogger),
+            });
+            // Diagnostics only — never used to build results; shows which phase the runner is in.
+            runnerInstance.on('statusChanged', event => engineLogger === null || engineLogger === void 0 ? void 0 : engineLogger.log(constants_1.NLP_LOG_PREFIX, `status: ${event.status}`));
+            return runnerInstance;
+        }
+        catch (error) {
+            // The runner never took the browser — close the CDP connection instead of leaking it.
+            browser = undefined;
+            await closeBrowser(browserInstance);
+            throw error;
+        }
+    }
+    function getRunner(step) {
+        // Cache the construction promise (same idiom as modulesPromise), not just the result, so
+        // two concurrent first calls share one browser+runner instead of each building a pair and
+        // leaking the loser. A failed construction resets the cache so a later call can retry.
+        if (!runnerPromise) {
+            runnerPromise = createRunner(step).catch(error => {
+                runnerPromise = undefined;
+                throw error;
+            });
+        }
+        return runnerPromise;
+    }
+    return {
+        async run(step) {
+            var _a;
+            const activeRunner = await getRunner(step);
+            const res = await activeRunner.run(step);
+            if (res.status === 'error') {
+                reportStep(logger, step, { stepSuccessful: false, status: 'error', reason: res.error });
+                throw new core_base_1.NlpStepError(step, { message: res.error, reason: res.error });
+            }
+            // An aborted run never executed the instruction. Falling through would map its (empty)
+            // results to `[]` and hand the caller a successful no-op for work that did not happen.
+            if (res.status === 'aborted') {
+                const reason = messages_1.messages.runAborted();
+                reportStep(logger, step, { stepSuccessful: false, status: 'aborted', reason });
+                throw new core_base_1.NlpStepError(step, { message: reason, reason: 'aborted' });
+            }
+            // Spread, not project: the engine's own fields survive, so a field it adds needs no change
+            // here or downstream. `testStep` is the SDK's stable name for the phrase an action came from
+            // — the engine reports it as `text`, and the whole phrase stands in when it does not.
+            const results = ((_a = res.results) !== null && _a !== void 0 ? _a : []).map(r => {
+                var _a;
+                return ({
+                    ...r,
+                    testStep: (_a = r.text) !== null && _a !== void 0 ? _a : step,
+                    stepSuccessful: r.status !== 'error',
+                });
+            });
+            for (const result of results)
+                reportStep(logger, step, result);
+            return results;
+        },
+        async dispose() {
+            const activeRunnerPromise = runnerPromise;
+            runnerPromise = undefined;
+            const activeBrowser = browser;
+            browser = undefined;
+            const activeRunner = await (activeRunnerPromise === null || activeRunnerPromise === void 0 ? void 0 : activeRunnerPromise.catch(() => undefined));
+            await (activeRunner === null || activeRunner === void 0 ? void 0 : activeRunner.dispose().catch(() => { }));
+            // The runner does not own the browser we created for it — close it too.
+            await closeBrowser(activeBrowser);
+        },
+    };
+}
+exports.makeNlp = makeNlp;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@applitools/core-nlp",
+  "version": "0.1.0",
+  "keywords": [
+    "nlp",
+    "natural language",
+    "chrome devtools protocol",
+    "cdp",
+    "applitools",
+    "eyes",
+    "automation",
+    "testing",
+    "tests"
+  ],
+  "homepage": "https://applitools.com",
+  "bugs": {
+    "url": "https://github.com/applitools/eyes.sdk.javascript1/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/applitools/eyes.sdk.javascript1.git",
+    "directory": "js/packages/core-nlp"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": {
+    "name": "Applitools Team",
+    "email": "team@applitools.com"
+  },
+  "main": "./dist/index.js",
+  "types": "./types/index.d.ts",
+  "files": [
+    "dist",
+    "types"
+  ],
+  "scripts": {
+    "lint": "run --top-level eslint '**/*.ts'",
+    "build": "run --top-level tspc --project ./tsconfig.build.json",
+    "test": "run --top-level mocha './test/**/*.spec.ts' --exit"
+  },
+  "dependencies": {
+    "@applitools/core-base": "1.39.0",
+    "@applitools/logger": "2.3.1",
+    "@applitools/req": "1.11.3",
+    "@applitools/utils": "1.15.2"
+  },
+  "optionalDependencies": {
+    "@applitools/nlp-web-runner": "^5.15.0"
+  },
+  "devDependencies": {
+    "@types/node": "^12.20.55"
+  },
+  "engines": {
+    "node": ">=12.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "lavamoat": {
+    "allowScripts": {
+      "@applitools/core-base>@applitools/image>sharp": false
+    }
+  }
+}

package/types/account.d.ts

@@ -0,0 +1,43 @@
+import type { Logger } from '@applitools/logger';
+import type { NlpServerSettings } from './types';
+export type ResolvedEyesServerSettings = {
+    eyesServerUrl: string;
+    apiKey?: string;
+    proxy?: {
+        url: string;
+        username?: string;
+        password?: string;
+    };
+};
+/**
+ * Mirrors core's `populateEyesServerSettings`, which lives above core-base and can't be imported
+ * here. Callers comparing two credential sets must both come through this: an unset config value
+ * and the `APPLITOOLS_*` variable it falls back to are the same account.
+ */
+export declare function resolveEyesServerSettings(server?: NlpServerSettings): ResolvedEyesServerSettings;
+export type NlpAccountProbe = {
+    enabled: true;
+}
+/**
+ * `not-entitled` — flag off; the organization can enable it. `service-unavailable` — entitled (or
+ * silent) but no endpoint, so nothing the user can change. `unreachable` — lookup failed or
+ * outlived its deadline.
+ */
+ | {
+    enabled: false;
+    reason: 'no-api-key' | 'not-entitled' | 'service-unavailable' | 'unreachable';
+    message?: string;
+};
+/**
+ * Entitlement is read from renderinfo, where the NLP endpoint appears only when the flag is on.
+ * Goes through core-base's **cached** requests singleton so a caller probing before opening a
+ * session shares that request rather than adding one.
+ *
+ * Never throws and never outlives `timeout`: it gates an optional capability from
+ * latency-sensitive paths, and the request layer retries 5xx/network behind a multi-minute
+ * connection timeout. Actual NLP use still fails loudly later, with a precise message.
+ */
+export declare function probeNlpAccount(server?: NlpServerSettings, { timeout, logger }?: {
+    timeout?: number;
+    logger?: Logger;
+}): Promise<NlpAccountProbe>;

package/types/ax-provider.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from '@applitools/logger';
+import type { AXProvider, HttpRemoteAXProviderCtor, NlpServerSettings } from './types';
+/**
+ * `HttpRemoteAXProvider` is injected because it is runtime-only (loaded via `importESM` in nlp.ts).
+ * The service is resolved eagerly so a missing feature flag fails here, before any CDP work.
+ */
+export declare function makeRemoteAXProvider(HttpRemoteAXProvider: HttpRemoteAXProviderCtor, options?: NlpServerSettings, { logger }?: {
+    logger?: Logger;
+}): Promise<AXProvider>;

package/types/constants.d.ts

@@ -0,0 +1,13 @@
+/** Prefixes every NLP message, so a line is identifiable even where the logger's tags aren't shown. */
+export declare const NLP_LOG_PREFIX = "[nlp]";
+export declare const DEFAULT_FIND_TIMEOUT = 10000;
+/** The launch-time probe sits on the browser-launch path, so it must fail fast, not just closed. */
+export declare const DEFAULT_ACCOUNT_PROBE_TIMEOUT = 10000;
+export declare const NLP_WEB_RUNNER = "@applitools/nlp-web-runner";
+/**
+ * Enforced at runtime too: the optional-dependency mechanism keeps the engine off older Node at
+ * install time, but a force-installed setup can smuggle it onto Node < 24, where `import()` may
+ * succeed yet behaviour is undefined.
+ */
+export declare const MIN_NODE_VERSION = "24.16.0";
+export declare const DEFAULT_EYES_SERVER_URL = "https://eyesapi.applitools.com";

package/types/index.d.ts

@@ -0,0 +1,5 @@
+export { makeNlp } from './nlp';
+export { probeNlpAccount, resolveEyesServerSettings } from './account';
+export type { NlpAccountProbe, ResolvedEyesServerSettings } from './account';
+export type { StepResult, NlpAdapter, MakeNlpOptions, NlpServerSettings, Nlp } from './types';
+export { NlpStepError } from '@applitools/core-base';

package/types/messages.d.ts

@@ -0,0 +1,7 @@
+export declare const messages: {
+    /** Replaces the raw internal failure, which surfaces as e.g. undici's `Socks5ProxyAgent not found`. */
+    engineUnavailable: (detail: string) => string;
+    missingApiKey: () => string;
+    unresolvedCdpTarget: () => string;
+    runAborted: () => string;
+};

package/types/nlp.d.ts

@@ -0,0 +1,12 @@
+import type { Logger } from '@applitools/logger';
+import type { MakeNlpOptions, Nlp, NlpAdapter } from './types';
+/**
+ * `testStep` is carried so a line reads on its own, without matching it back to a call site.
+ * @internal
+ */
+export declare function reportStep(logger: Logger | undefined, testStep: string, result: {
+    stepSuccessful: boolean;
+    status: string;
+    reason?: string;
+}): void;
+export declare function makeNlp(adapter: NlpAdapter, options?: MakeNlpOptions): Nlp;

package/types/types.d.ts

@@ -0,0 +1,107 @@
+import type { Logger } from '@applitools/logger';
+/**
+ * Per-action result returned by `run`, one entry per action the engine reported.
+ *
+ * The engine owns this shape: every field it reports is passed through untouched, so fields it
+ * gains (element `info`, …) reach callers without a change here. Two fields are added: `stepSuccessful`,
+ * derived from the engine's `status`, and `testStep`, the SDK's stable name for the phrase an action
+ * came from (the engine reports it as `text`).
+ */
+export type StepResult = {
+    stepSuccessful: boolean;
+    status: string;
+} & Record<string, unknown>;
+/**
+ * The only SDK-specific seam. An adapter bridges the SDK-agnostic orchestrator
+ * to a concrete automation framework by providing the CDP connection target.
+ */
+export interface NlpAdapter {
+    getCdpTarget(): Promise<Record<string, unknown>>;
+}
+/**
+ * Eyes server credentials used to discover the NLP AX service: the orchestrator calls
+ * `GET /api/sessions/renderinfo` with them to obtain the service URL and its auth token
+ * (see ./ax-provider.ts). Every field falls back to the standard environment variables
+ * (`APPLITOOLS_SERVER_URL`, `APPLITOOLS_API_KEY`, `APPLITOOLS_PROXY_URL`).
+ */
+export type NlpServerSettings = {
+    serverUrl?: string;
+    apiKey?: string;
+    proxy?: {
+        url: string;
+        username?: string;
+        password?: string;
+    };
+};
+export interface MakeNlpOptions {
+    /**
+     * The SDK's logger. Every consumer already builds one, so the orchestrator uses that type
+     * directly rather than a structural subset — it needs the `console` channel (always-visible,
+     * user-facing output) and the level-gated `debug` channel, both of which `Logger` guarantees.
+     * SDKs on the `@applitools/eyes` wrapper pass the underlying logger: `eyes.getLogger().getLogger()`.
+     */
+    logger?: Logger;
+    timeouts?: {
+        findTimeout?: number;
+    };
+    server?: NlpServerSettings;
+}
+export interface Nlp {
+    run(step: string): Promise<StepResult[]>;
+    dispose(): Promise<void>;
+}
+export type Browser = {
+    close?(): Promise<void>;
+    dispose?(): Promise<void>;
+};
+export type RunResult = ({
+    status: 'success' | 'aborted';
+} | {
+    status: 'error';
+    error: string;
+}) & {
+    results?: ({
+        status: string;
+    } & Record<string, unknown>)[];
+};
+export type Runner = {
+    run(input: string): Promise<RunResult>;
+    dispose(): Promise<void>;
+    on(type: 'statusChanged', listener: (event: {
+        status: string;
+        previousStatus?: string;
+    }) => void): () => void;
+};
+export type NlpLogger = {
+    log(...args: any[]): void;
+    error(...args: any[]): void;
+    trace(...args: any[]): void;
+    debug(...args: any[]): void;
+};
+export type AXProvider = object;
+export type AXServerRequest = {
+    url: string;
+    method: string;
+    token: string;
+    body: unknown;
+};
+export type AXServerFetch = (request: AXServerRequest) => Promise<{
+    json(): Promise<any>;
+}>;
+export type HttpRemoteAXProviderCtor = new (options: {
+    url: string;
+    getAuthToken: () => string | Promise<string>;
+    fetch?: AXServerFetch;
+}) => AXProvider;
+export type NlpModules = {
+    makeBrowser(options: Record<string, unknown>): Promise<Browser>;
+    makeRunner(options: {
+        automator: Browser;
+        axProvider: AXProvider;
+        timeouts?: {
+            findTimeout?: number;
+        };
+        logger?: NlpLogger;
+    }): Promise<Runner>;
+    HttpRemoteAXProvider: HttpRemoteAXProviderCtor;
+};