askui 0.18.1 → 0.19.0

package/dist/cjs/execution/ui-control-client.d.ts

@@ -1,12 +1,34 @@
-import { CustomElementJson } from '../core/model/custom-element-json';
-import { Exec, Executable, FluentFilters, ApiCommands, PC_AND_MODIFIER_KEY } from './dsl';
+import { Exec, Executable, FluentFilters, ApiCommands, PC_AND_MODIFIER_KEY, CommandExecutorContext } from './dsl';
 import { UiControllerClientConnectionState } from './ui-controller-client-connection-state';
 import { Annotation } from '../core/annotation/annotation';
 import { AnnotationRequest } from '../core/model/annotation-result/annotation-interface';
 import { DetectedElement } from '../core/model/annotation-result/detected-element';
 import { ClientArgs } from './ui-controller-client-interface';
 export declare type RelationsForConvenienceMethods = 'nearestTo' | 'leftOf' | 'above' | 'rightOf' | 'below' | 'contains';
+export declare type TextMatchingOption = 'similar' | 'exact' | 'regex';
+export declare type ElementExistsQueryType = 'otherElement' | 'switch' | 'element' | 'container' | 'checkbox' | 'element' | 'button' | 'table' | 'text' | 'icon' | 'image' | 'textfield';
+export interface ElementExistsQueryText {
+    value: string;
+    matching?: TextMatchingOption;
+}
+export interface ElementExistsQueryRelation {
+    type: RelationsForConvenienceMethods;
+    text: string;
+}
+export interface ElementExistsQuery {
+    type: keyof Pick<FluentFilters, ElementExistsQueryType>;
+    text?: ElementExistsQueryText;
+    relation?: ElementExistsQueryRelation;
+}
+export interface ExpectExistenceElement extends ElementExistsQuery {
+    exists: boolean;
+}
+export interface ExpectAllExistResult {
+    allExist: boolean;
+    elements: ExpectExistenceElement[];
+}
 export declare class UiControlClient extends ApiCommands {
+    private workspaceId;
     private executionRuntime;
     private stepReporter;
     private constructor();
@@ -34,8 +56,9 @@ export declare class UiControlClient extends ApiCommands {
     annotateInteractively(): Promise<void>;
     private escapeSeparatorString;
     private buildInstruction;
-    fluentCommandExecutor(instructionString: string, customElementJson?: CustomElementJson[]): Promise<void>;
-    getterExecutor(instruction: string, customElementJson?: CustomElementJson[]): Promise<DetectedElement[]>;
+    private getAIElementsByNames;
+    fluentCommandExecutor(instructionString: string, context?: CommandExecutorContext): Promise<void>;
+    getterExecutor(instruction: string, context?: CommandExecutorContext): Promise<DetectedElement[]>;
     private secretText;
     private getAndResetSecretText;
     /**
@@ -190,8 +213,8 @@ export declare class UiControlClient extends ApiCommands {
      * @param {Object} params - Object containing required `label` property and
      *                          optional `relation` property.
      * @property {string} params.label - The label for the checkbox.
-     * @property {Object} params.relation - Object describing the relationship between
-     *                                      the clicked checkbox and another element.
+     * @property {Object} [params.relation] - Object describing the relationship between
+     *                                        the clicked checkbox and another element.
      * @property {RelationsForConvenienceMethods} params.relation.type - The type of relation.
      */
     clickCheckbox(params: {
@@ -213,7 +236,7 @@ export declare class UiControlClient extends ApiCommands {
      * @param {Object} params - Object containing required `label` property and
      *                          optional `relation` property.
      * @property {string} params.label - The label for the checkbox.
-     * @property {Object} params.relation - Object describing the relationship between
+     * @property {Object} [params.relation] - Object describing the relationship between
      *                                      the clicked checkbox and another element.
      * @property {RelationsForConvenienceMethods} params.relation.type - The type of relation.
      */
@@ -266,41 +289,103 @@ export declare class UiControlClient extends ApiCommands {
     }): Promise<void>;
     /**
      * Click on a specific text.
-     * You can also use a RegEx or match the text exactly by specifyicing the specific flag.
+     * You can also use a RegEx or match the text exactly by specifying the specific flag.
      * Use a relation to find the text in relation to a specific text.
      *
      * **Examples:**
      * ```typescript
      * // Click text that matches exactly
-     * await aui.clickText({text: 'askui', type: 'similar'})
+     * await aui.clickText({text: 'askui', matching: 'similar'})
      *
      * // Click text that contains 'pie' or 'cake' or 'Pie' or 'Cake'
-     * await aui.clickText({text: '.*([Pp]ie|[Cc]ake).*', type: 'regex'})
+     * await aui.clickText({text: '.*([Pp]ie|[Cc]ake).*', matching: 'regex'})
      *
      * // Click the text 'TERMINAL' that is left of the text 'Ports'
      * await aui.clickText({
      *     text: 'TERMINAL',
-     *     type: "exact",
+     *     matching: "exact",
      *     relation: { type: 'leftOf', text: 'PORTS' }
      *   })
      * ```
+     *
      * @param {Object} params - Object containing required `text` property and optional properties
      *                          for regular expression matching and relation.
      * @property {string} params.text - The text to be clicked.
-     * @property {string} params.type - Whether the text is matched using similarity,
-     *                                  exact match or a regular expression.
-     * @property {Object} params.relation - Object describing the relationship between the
-     *                                      clicked text and another element.
+     * @property {string} params.matching - Whether the text is matched using similarity,
+     *                                      exact match or a regular expression.
+     * @property {Object} [params.relation] - Object describing the relationship between the
+     *                                        clicked text and another element.
      * @property {RelationsForConvenienceMethods} params.relation.type - The type of relation.
      * @property {string} params.relation.text - The label or text associated with the
      *                                           related element or state.
      */
     clickText(params: {
         text: string;
-        type: 'similar' | 'exact' | 'regex';
+        matching: TextMatchingOption;
         relation?: {
             type: RelationsForConvenienceMethods;
             text: string;
         };
     }): Promise<void>;
+    private evaluateMatchingProperty;
+    /**
+     * Check if one or multiple elements are detected.
+     *
+     * **Examples:**
+     * ```typescript
+     * await aui.expectAllExist([
+     *   {
+     *     type: 'text',
+     *     text: {
+     *       value: 'Switch to Dark',
+     *       matching: 'similar'
+     *     }
+     *   },
+     * ]);
+     *
+     * // Check for existence of multiple elements
+     * await aui.expectAllExist([
+     *   {
+     *     type: 'textfield',
+     *     relation: {
+     *       type: 'rightOf',
+     *       text: 'Email:'
+     *     }
+     *   },
+     *   {
+     *     type: 'element',
+     *     text: {
+     *       value: 'Switch to Dark'
+     *     }
+     *   },
+     * ]);
+     *
+     * // Validate existence
+     * const exists = await aui.expectAllExist([...]);
+     * exists.allExist // true when every element exists
+     *
+     * // Check which elements do not exist
+     * // with the elements property
+     * const nonExistentElements = exists.elements.filter((e) => e.exists===false)
+     * ```
+     *
+     * @param {ElementExistsQuery[]} query - Objects containing the required property
+     *                                                   'type' and the optional properties
+     *                                                   'text' and 'relation'.
+     * @property {string} query.type - The type of the element: 'otherElement' | 'switch' |
+     *                                 'element' | 'container' | 'checkbox' | 'element' |
+     *                                 'button' | 'table' | 'text' | 'icon' | 'image' | 'textfield'
+     * @property {Object} [query.text] - Object containing value and matching strategy.
+     * @property {string} query.text.value - The text to match for.
+     * @property {string} [query.text.matching] - Whether the text is matched using similarity,
+     *                                            exact match or a regular expression.
+     * @property {Object} [query.relation] - Object describing the relationship between the
+     *                                       clicked text and another element.
+     * @property {RelationsForConvenienceMethods} query.relation.type - The type of relation.
+     * @property {string} query.relation.text - The label or text associated with the
+     *                                          related element or state.
+     * @returns {ExpectAllExistResult.allExist} - If every element exists.
+     * @returns {ExpectAllExistResult.elements} - ExpectExistenceElement[].
+     */
+    expectAllExist(query: ElementExistsQuery[]): Promise<ExpectAllExistResult>;
 }

package/dist/cjs/execution/ui-control-client.js

@@ -8,20 +8,19 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UiControlClient = void 0;
-const ValidationError_1 = __importDefault(require("yup/lib/ValidationError"));
+const yup_1 = require("yup");
 const custom_element_1 = require("../core/model/custom-element");
 const dsl_1 = require("./dsl");
 const annotation_writer_1 = require("../core/annotation/annotation-writer");
 const logger_1 = require("../lib/logger");
 const ui_control_client_dependency_builder_1 = require("./ui-control-client-dependency-builder");
+const ai_element_collection_1 = require("../core/ai-element/ai-element-collection");
 class UiControlClient extends dsl_1.ApiCommands {
-    constructor(executionRuntime, stepReporter) {
+    constructor(workspaceId, executionRuntime, stepReporter) {
         super();
+        this.workspaceId = workspaceId;
         this.executionRuntime = executionRuntime;
         this.stepReporter = stepReporter;
         this.secretText = undefined;
@@ -30,8 +29,8 @@ class UiControlClient extends dsl_1.ApiCommands {
         return __awaiter(this, void 0, void 0, function* () {
             const builder = ui_control_client_dependency_builder_1.UiControlClientDependencyBuilder;
             const clientArgsWithDefaults = yield builder.getClientArgsWithDefaults(clientArgs);
-            const { executionRuntime, stepReporter } = yield builder.build(clientArgsWithDefaults);
-            return new UiControlClient(executionRuntime, stepReporter);
+            const { workspaceId, executionRuntime, stepReporter, } = yield builder.build(clientArgsWithDefaults);
+            return new UiControlClient(workspaceId, executionRuntime, stepReporter);
         });
     }
     /**
@@ -125,9 +124,20 @@ class UiControlClient extends dsl_1.ApiCommands {
             };
         });
     }
-    fluentCommandExecutor(instructionString, customElementJson = []) {
+    getAIElementsByNames(names) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // eslint-disable-next-line max-len
+            const workspaceAIElementCollection = yield ai_element_collection_1.AIElementCollection.collectForWorkspaceId(this.workspaceId);
+            return workspaceAIElementCollection.getByNames(names);
+        });
+    }
+    fluentCommandExecutor(instructionString, context = { customElementsJson: [], aiElementNames: [] }) {
         return __awaiter(this, void 0, void 0, function* () {
-            const instruction = yield this.buildInstruction(instructionString, customElementJson);
+            const aiElements = yield this.getAIElementsByNames(context.aiElementNames);
+            const instruction = yield this.buildInstruction(instructionString, [
+                ...context.customElementsJson,
+                ...aiElements,
+            ]);
             logger_1.logger.debug(instruction);
             try {
                 yield this.stepReporter.resetStep(instruction);
@@ -141,12 +151,16 @@ class UiControlClient extends dsl_1.ApiCommands {
             }
         });
     }
-    getterExecutor(instruction, customElementJson = []) {
+    getterExecutor(instruction, context = { customElementsJson: [], aiElementNames: [] }) {
         return __awaiter(this, void 0, void 0, function* () {
-            const customElements = yield custom_element_1.CustomElement.fromJsonListWithImagePathOrImage(customElementJson);
+            const aiElements = yield this.getAIElementsByNames(context.aiElementNames);
+            const customElements = yield custom_element_1.CustomElement.fromJsonListWithImagePathOrImage(context.customElementsJson);
             const stringWithoutSeparators = this.escapeSeparatorString(instruction);
             logger_1.logger.debug(stringWithoutSeparators);
-            return this.executionRuntime.getDetectedElements(instruction, customElements);
+            return this.executionRuntime.getDetectedElements(instruction, [
+                ...customElements,
+                ...aiElements,
+            ]);
         });
     }
     getAndResetSecretText() {
@@ -331,30 +345,22 @@ class UiControlClient extends dsl_1.ApiCommands {
     }
     // eslint-disable-next-line class-methods-use-this
     evaluateRelation(command, relation, text) {
-        let commando = command;
         switch (relation) {
-            case 'nearestTo':
-                commando = command.nearestTo().text(text);
-                break;
             case 'leftOf':
-                commando = command.leftOf().text(text);
-                break;
+                return command.leftOf().text(text);
             case 'above':
-                commando = command.above().text(text);
-                break;
+                return command.above().text(text);
             case 'rightOf':
-                commando = command.rightOf().text(text);
-                break;
+                return command.rightOf().text(text);
             case 'below':
-                commando = command.below().text(text);
-                break;
+                return command.below().text(text);
             case 'contains':
-                commando = command.contains().text(text);
-                break;
+                return command.contains().text(text);
+            case 'nearestTo':
+                return command.nearestTo().text(text);
             default:
-                throw new ValidationError_1.default('No valid Relation.Type was passed.');
+                throw new yup_1.ValidationError(`'relation' has to be 'nearestTo', 'leftOf', 'above', 'rightOf', 'below' or 'contains' but was '${relation}'`);
         }
-        return commando;
     }
     /**
      * Click a button with a specific label.
@@ -400,8 +406,8 @@ class UiControlClient extends dsl_1.ApiCommands {
      * @param {Object} params - Object containing required `label` property and
      *                          optional `relation` property.
      * @property {string} params.label - The label for the checkbox.
-     * @property {Object} params.relation - Object describing the relationship between
-     *                                      the clicked checkbox and another element.
+     * @property {Object} [params.relation] - Object describing the relationship between
+     *                                        the clicked checkbox and another element.
      * @property {RelationsForConvenienceMethods} params.relation.type - The type of relation.
      */
     clickCheckbox(params) {
@@ -429,7 +435,7 @@ class UiControlClient extends dsl_1.ApiCommands {
      * @param {Object} params - Object containing required `label` property and
      *                          optional `relation` property.
      * @property {string} params.label - The label for the checkbox.
-     * @property {Object} params.relation - Object describing the relationship between
+     * @property {Object} [params.relation] - Object describing the relationship between
      *                                      the clicked checkbox and another element.
      * @property {RelationsForConvenienceMethods} params.relation.type - The type of relation.
      */
@@ -493,31 +499,32 @@ class UiControlClient extends dsl_1.ApiCommands {
     }
     /**
      * Click on a specific text.
-     * You can also use a RegEx or match the text exactly by specifyicing the specific flag.
+     * You can also use a RegEx or match the text exactly by specifying the specific flag.
      * Use a relation to find the text in relation to a specific text.
      *
      * **Examples:**
      * ```typescript
      * // Click text that matches exactly
-     * await aui.clickText({text: 'askui', type: 'similar'})
+     * await aui.clickText({text: 'askui', matching: 'similar'})
      *
      * // Click text that contains 'pie' or 'cake' or 'Pie' or 'Cake'
-     * await aui.clickText({text: '.*([Pp]ie|[Cc]ake).*', type: 'regex'})
+     * await aui.clickText({text: '.*([Pp]ie|[Cc]ake).*', matching: 'regex'})
      *
      * // Click the text 'TERMINAL' that is left of the text 'Ports'
      * await aui.clickText({
      *     text: 'TERMINAL',
-     *     type: "exact",
+     *     matching: "exact",
      *     relation: { type: 'leftOf', text: 'PORTS' }
      *   })
      * ```
+     *
      * @param {Object} params - Object containing required `text` property and optional properties
      *                          for regular expression matching and relation.
      * @property {string} params.text - The text to be clicked.
-     * @property {string} params.type - Whether the text is matched using similarity,
-     *                                  exact match or a regular expression.
-     * @property {Object} params.relation - Object describing the relationship between the
-     *                                      clicked text and another element.
+     * @property {string} params.matching - Whether the text is matched using similarity,
+     *                                      exact match or a regular expression.
+     * @property {Object} [params.relation] - Object describing the relationship between the
+     *                                        clicked text and another element.
      * @property {RelationsForConvenienceMethods} params.relation.type - The type of relation.
      * @property {string} params.relation.text - The label or text associated with the
      *                                           related element or state.
@@ -525,24 +532,107 @@ class UiControlClient extends dsl_1.ApiCommands {
     clickText(params) {
         return __awaiter(this, void 0, void 0, function* () {
             let command = this.click().text();
-            switch (params.type) {
-                case 'similar':
-                    command = command.withText(params.text);
-                    break;
-                case 'exact':
-                    command = command.withExactText(params.text);
-                    break;
-                case 'regex':
-                    command = command.withTextRegex(params.text);
-                    break;
-                default:
-                    throw new ValidationError_1.default('"type" must be "similar", "exact" or "regex"');
-            }
+            command = this.evaluateMatchingProperty(command, { value: params.text, matching: params.matching });
             if (params.relation) {
                 command = this.evaluateRelation(command, params.relation.type, params.relation.text);
             }
             yield command.exec();
         });
     }
+    // eslint-disable-next-line class-methods-use-this
+    evaluateMatchingProperty(command, text) {
+        var _a;
+        switch ((_a = text.matching) !== null && _a !== void 0 ? _a : 'similar') {
+            case 'exact':
+                return command.withExactText(text.value);
+            case 'regex':
+                return command.withTextRegex(text.value);
+            case 'similar':
+                return command.withText(text.value);
+            default:
+                throw new yup_1.ValidationError(`'text.matching' property has to be 'similar', 'exact' or 'regex' but was '${text.matching}'`);
+        }
+    }
+    /**
+     * Check if one or multiple elements are detected.
+     *
+     * **Examples:**
+     * ```typescript
+     * await aui.expectAllExist([
+     *   {
+     *     type: 'text',
+     *     text: {
+     *       value: 'Switch to Dark',
+     *       matching: 'similar'
+     *     }
+     *   },
+     * ]);
+     *
+     * // Check for existence of multiple elements
+     * await aui.expectAllExist([
+     *   {
+     *     type: 'textfield',
+     *     relation: {
+     *       type: 'rightOf',
+     *       text: 'Email:'
+     *     }
+     *   },
+     *   {
+     *     type: 'element',
+     *     text: {
+     *       value: 'Switch to Dark'
+     *     }
+     *   },
+     * ]);
+     *
+     * // Validate existence
+     * const exists = await aui.expectAllExist([...]);
+     * exists.allExist // true when every element exists
+     *
+     * // Check which elements do not exist
+     * // with the elements property
+     * const nonExistentElements = exists.elements.filter((e) => e.exists===false)
+     * ```
+     *
+     * @param {ElementExistsQuery[]} query - Objects containing the required property
+     *                                                   'type' and the optional properties
+     *                                                   'text' and 'relation'.
+     * @property {string} query.type - The type of the element: 'otherElement' | 'switch' |
+     *                                 'element' | 'container' | 'checkbox' | 'element' |
+     *                                 'button' | 'table' | 'text' | 'icon' | 'image' | 'textfield'
+     * @property {Object} [query.text] - Object containing value and matching strategy.
+     * @property {string} query.text.value - The text to match for.
+     * @property {string} [query.text.matching] - Whether the text is matched using similarity,
+     *                                            exact match or a regular expression.
+     * @property {Object} [query.relation] - Object describing the relationship between the
+     *                                       clicked text and another element.
+     * @property {RelationsForConvenienceMethods} query.relation.type - The type of relation.
+     * @property {string} query.relation.text - The label or text associated with the
+     *                                          related element or state.
+     * @returns {ExpectAllExistResult.allExist} - If every element exists.
+     * @returns {ExpectAllExistResult.elements} - ExpectExistenceElement[].
+     */
+    expectAllExist(query) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const elements = yield query.reduce((accumulatorPromise, subquery) => __awaiter(this, void 0, void 0, function* () {
+                const acc = yield accumulatorPromise;
+                const command = this.get()[subquery.type]();
+                let finalCommand = subquery.text !== undefined
+                    ? this.evaluateMatchingProperty(command, subquery.text)
+                    : command;
+                if (subquery.relation) {
+                    finalCommand = this.evaluateRelation(finalCommand, subquery.relation.type, subquery.relation.text);
+                }
+                return [
+                    ...acc,
+                    Object.assign(Object.assign({}, subquery), { exists: (yield finalCommand.exec()).length > 0 }),
+                ];
+            }), Promise.resolve([]));
+            return {
+                elements,
+                allExist: elements.every((el) => el.exists),
+            };
+        });
+    }
 }
 exports.UiControlClient = UiControlClient;

package/dist/cjs/main.d.ts

@@ -1,5 +1,5 @@
 export { UiController } from './lib';
-export { UiControlClient, RelationsForConvenienceMethods } from './execution';
+export * from './execution';
 export { Instruction, Reporter, ReporterConfig, Snapshot, SnapshotDetailLevel, Step, StepStatus, StepStatusEnd, } from './core/reporting';
 export { Annotation } from './core/annotation/annotation';
 export { DetectedElement } from './core/model/annotation-result/detected-element';

package/dist/cjs/main.js

@@ -1,10 +1,19 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLevels = exports.DetectedElement = exports.Annotation = exports.UiControlClient = exports.UiController = void 0;
+exports.LogLevels = exports.DetectedElement = exports.Annotation = exports.UiController = void 0;
 var lib_1 = require("./lib");
 Object.defineProperty(exports, "UiController", { enumerable: true, get: function () { return lib_1.UiController; } });
-var execution_1 = require("./execution");
-Object.defineProperty(exports, "UiControlClient", { enumerable: true, get: function () { return execution_1.UiControlClient; } });
+__exportStar(require("./execution"), exports);
 var annotation_1 = require("./core/annotation/annotation");
 Object.defineProperty(exports, "Annotation", { enumerable: true, get: function () { return annotation_1.Annotation; } });
 var detected_element_1 = require("./core/model/annotation-result/detected-element");

package/dist/cjs/utils/analytics/analytics.d.ts

@@ -1,5 +1,5 @@
 import { AnalyticsInterface } from './analytics-interface';
-import { Context } from '@/execution/context';
+import { Context } from '../../execution/context';
 export declare class Analytics implements AnalyticsInterface {
     private static clientSessionId;
     private clientId;

package/dist/esm/core/ai-element/ai-element-collection.d.ts

@@ -0,0 +1,10 @@
+import { AIElement } from './ai-element';
+import { CustomElementJson } from '../model/custom-element-json';
+export declare class AIElementCollection {
+    private elements;
+    static AI_ELEMENT_FOLDER: string;
+    constructor(elements: AIElement[]);
+    static collectForWorkspaceId(workspaceId: string | undefined): Promise<AIElementCollection>;
+    getByName(name: string): CustomElementJson[];
+    getByNames(names: string[]): CustomElementJson[];
+}

package/dist/esm/core/ai-element/ai-element-collection.js

@@ -0,0 +1,71 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import os from 'os';
+import path from 'path';
+import fs from 'fs-extra';
+import { AIElement } from './ai-element';
+import { logger } from '../../lib';
+import { AIElementError } from './ai-element-error';
+export class AIElementCollection {
+    constructor(elements) {
+        this.elements = elements;
+    }
+    static collectForWorkspaceId(workspaceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            logger.debug(`Collecting AIElements for workspace '${workspaceId}' ...`);
+            if (workspaceId === undefined) {
+                throw new AIElementError("Value of 'workspaceId' must be defined.");
+            }
+            const workspaceAIElementFolder = path.join(AIElementCollection.AI_ELEMENT_FOLDER, workspaceId);
+            if (!(yield fs.pathExists(workspaceAIElementFolder))) {
+                throw new AIElementError(`Missing AIElement folder for workspace '${workspaceId}' at '${workspaceAIElementFolder}'.`);
+            }
+            const files = yield fs.readdir(workspaceAIElementFolder);
+            if (files.length === 0) {
+                throw new AIElementError(`'${workspaceAIElementFolder}' is empty. No AIElement files found for workspace '${workspaceId}'.`);
+            }
+            const aiElements = yield Promise.all(files
+                .filter((file) => path.extname(file) === '.json')
+                .map((file) => __awaiter(this, void 0, void 0, function* () {
+                const jsonFile = path.join(workspaceAIElementFolder, file);
+                const baseName = path.basename(jsonFile, '.json');
+                const pngFile = path.join(workspaceAIElementFolder, `${baseName}.png`);
+                if (yield fs.pathExists(pngFile)) {
+                    const metadata = JSON.parse(yield fs.readFile(jsonFile, 'utf-8'));
+                    return AIElement.fromJson(metadata, pngFile);
+                }
+                return null;
+            })));
+            const validAIElements = aiElements.filter((element) => element !== null);
+            if (validAIElements.length === 0) {
+                throw new AIElementError(`No AIElement files found for workspace '${workspaceId}' at '${workspaceAIElementFolder}'.`);
+            }
+            return new AIElementCollection(validAIElements);
+        });
+    }
+    getByName(name) {
+        if (name === '') {
+            throw new AIElementError("Parameter 'name' must be non-empty. This might be due to corrupted metadata.");
+        }
+        logger.debug(`Getting all CustomElementJson with the name '${name}' ...`);
+        const elements = this.elements.filter((element) => element.hasName(name));
+        if (elements.length === 0) {
+            throw new AIElementError(`No AIElement with the name '${name}' was found.`);
+        }
+        return elements.map((element) => element.toCustomElement());
+    }
+    getByNames(names) {
+        if (names.length === 0) {
+            return [];
+        }
+        return names.flatMap((name) => this.getByName(name));
+    }
+}
+AIElementCollection.AI_ELEMENT_FOLDER = path.join(os.homedir(), '.askui', 'SnippingTool', 'AIElement');

package/dist/esm/core/ai-element/ai-element-error.d.ts

@@ -0,0 +1,2 @@
+export declare class AIElementError extends Error {
+}

package/dist/esm/core/ai-element/ai-element-error.js

@@ -0,0 +1,2 @@
+export class AIElementError extends Error {
+}

package/dist/esm/core/ai-element/ai-element.d.ts

@@ -0,0 +1,27 @@
+import { CustomElementJson } from '../model/custom-element-json';
+interface AIElementJson {
+    version: number;
+    name: string;
+    image?: {
+        mask?: {
+            x: number;
+            y: number;
+        }[];
+    };
+}
+declare class AIElement {
+    name: string;
+    imagePath: string;
+    mask?: {
+        x: number;
+        y: number;
+    }[] | undefined;
+    constructor(name: string, imagePath: string, mask?: {
+        x: number;
+        y: number;
+    }[] | undefined);
+    static fromJson(json: AIElementJson, imagePath: string): AIElement;
+    toCustomElement(): CustomElementJson;
+    hasName(name: string): boolean;
+}
+export { AIElement, AIElementJson };