complexqa_frontend_core 1.21.4 → 1.21.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "complexqa_frontend_core",
-  "version": "1.21.4",
+  "version": "1.21.6",
   "description": "core of web ",
   "type": "module",
   "exports": {

package/publish/api/file_app_api.js

@@ -0,0 +1,90 @@
+import { ApiAbstractClass } from "./api_abstract_class.js";
+
+
+/**
+ * Main App bridge → File App (tokens, access URLs, listing).
+ *
+ * @see docs/File App Layer/README.MD
+ *
+ * @version			v.1.0 (28/06/2026)
+ */
+export class FileAppApi extends ApiAbstractClass
+{
+	module_prefix = 'file_app';
+	api_prefix    = 'web_api';
+
+
+	/**
+	 * POST /web_api/file_app/issue_access_token
+	 *
+	 * @param {object} payload
+	 *
+	 * @returns {Promise<{payload: object, response: object}>}
+	 */
+	async issue_access_token(payload)
+	{
+		const url      = `/${ this.api_prefix }/${ this.module_prefix }/issue_access_token`;
+		payload        = this.handle_request_payload(payload);
+		let response   = this.api_request(url, payload);
+		response       = this.handle_response(response, false);
+
+		return {
+			response: response,
+			payload : payload,
+		};
+	}
+
+
+	/**
+	 * GET /web_api/file_app/file_access_url?file_uuid=&disposition=
+	 *
+	 * @param {object} payload
+	 *
+	 * @returns {Promise<{payload: object, response: object}>}
+	 */
+	async file_access_url(payload)
+	{
+		const url        = `/${ this.api_prefix }/${ this.module_prefix }/file_access_url`;
+		const prev_method = this.method;
+
+		this.method = 'get';
+
+		payload      = this.handle_request_payload(payload);
+		let response = this.api_request(url, payload);
+		response     = this.handle_response(response, false);
+
+		this.method = prev_method;
+
+		return {
+			response: response,
+			payload : payload,
+		};
+	}
+
+
+	/**
+	 * GET /web_api/file_app/list_files?entity_type=&entity_id=&category=
+	 *
+	 * @param {object} payload
+	 *
+	 * @returns {Promise<{payload: object, response: object}>}
+	 */
+	async list_files(payload)
+	{
+		const url        = `/${ this.api_prefix }/${ this.module_prefix }/list_files`;
+		const prev_method = this.method;
+
+		this.method = 'get';
+
+		payload      = this.handle_request_payload(payload);
+		let response = this.api_request(url, payload);
+		response     = this.handle_response(response, false);
+
+		this.method = prev_method;
+
+		return {
+			response: response,
+			payload : payload,
+		};
+	}
+}

package/publish/api/index.js

@@ -22,6 +22,7 @@ import { ContextOsApi } from "./context/context_os_api.js";
 import { ContextScreenResolutionApi } from "./context/context_screen_resolution_api.js";
 import { BrowserToolsUtilExecutionApi } from "./util/browser_tools_util_execution_api.js";
 import { BrowserToolsScreenshotMultiApi } from "./util/browser_tools_screenshot_multi_api.js";
+import { FileAppApi } from "./file_app_api.js";
 
 /**
  * Обертка над axios
@@ -161,6 +162,7 @@ export class Api
 		this.execution_context            = new ExecutionContextApi(payload);
 		this.browser_tools_util_execution  = new BrowserToolsUtilExecutionApi(payload);
 		this.browser_tools_screenshot_multi = new BrowserToolsScreenshotMultiApi(payload);
+		this.file_app                      = new FileAppApi(payload);
 
 		this.reference = this.bootstrap_reference(payload)
 	}

package/publish/index.js

@@ -1,6 +1,7 @@
 export { Api } from "./api/index.js";
 export { UserService } from './services/UserService.js';
 export { TeamService } from './services/TeamService.js';
+export { FileAppService } from './services/FileAppService.js';
 
 export { typeFOR } from './types/family_service/typeFOR.js';
 export { typeFilter } from './types/family_service/typeFilter.js';
@@ -36,6 +37,15 @@ export { typeUtilExecutionScreenshotMultiScreenshot } from './types/family_utils
 export { typeUtilExecutionScreenshotMultiCaptureError } from './types/family_utils/typeUtilExecutionScreenshotMultiCaptureError.js';
 export { typeUtilExecutionEvent } from './types/family_utils/typeUtilExecutionEvent.js';
 
+export { familyFile } from './types/family_files/familyFile.js';
+export { typeFile } from './types/family_files/typeFile.js';
+export { typeFileScreenshot } from './types/family_files/typeFileScreenshot.js';
+export { typeFileHtml } from './types/family_files/typeFileHtml.js';
+export { typeFilePostman } from './types/family_files/typeFilePostman.js';
+export { typeFileVideo } from './types/family_files/typeFileVideo.js';
+export { typeFileJson } from './types/family_files/typeFileJson.js';
+export { create_type_file_from_wire } from './types/family_files/typeFileFactory.js';
+
 export { typeUser } from './types/family_elements/typeUser.js';
 export { typeTeam } from './types/family_elements/typeTeam.js';
 export { typeTeamMember } from './types/family_elements/typeTeamMember.js';

package/publish/services/FileAppService.js

@@ -0,0 +1,219 @@
+import { abstractService } from "./abstractService.js";
+import { typeFile } from "../types/family_files/typeFile.js";
+import { create_type_file_from_wire } from "../types/family_files/typeFileFactory.js";
+import { ApiException } from "../exceptions/ApiException.js";
+
+
+/**
+ * File App orchestration: bootstrap URL, upload, URL refresh.
+ *
+ * @see docs/File App Layer/README.MD
+ *
+ * @version			v.1.0 (28/06/2026)
+ */
+export class FileAppService extends abstractService
+{
+	static file_app_url = false;
+	static api_service  = false;
+
+
+	/**
+	 * @param {object} options
+	 * @param {string} options.file_app_url
+	 * @param {import('../api/index.js').Api} [options.api_service]
+	 */
+	static bootstrap(options = {})
+	{
+		if (options.file_app_url)
+		{
+			FileAppService.file_app_url = String(options.file_app_url).replace(/\/$/, '');
+		}
+
+		if (options.api_service)
+		{
+			FileAppService.api_service = options.api_service;
+		}
+	}
+
+
+	/**
+	 * @returns {string|false}
+	 */
+	static get_file_app_url()
+	{
+		return FileAppService.file_app_url || false;
+	}
+
+
+	/**
+	 * @returns {import('../api/index.js').Api}
+	 */
+	static #get_api_service()
+	{
+		if (FileAppService.api_service)
+		{
+			return FileAppService.api_service;
+		}
+
+		if (typeof window !== 'undefined' && window.ApiService)
+		{
+			return window.ApiService;
+		}
+
+		throw new Error('FileAppService: ApiService is not bootstrapped');
+	}
+
+
+	/**
+	 * Upload browser File/Blob to File App (token via Main App bridge).
+	 *
+	 * @param {object} payload
+	 * @param {File|Blob} payload.file
+	 * @param {string} payload.entity_type
+	 * @param {number} payload.entity_id
+	 * @param {string} payload.category
+	 * @param {string} [payload.original_name]
+	 *
+	 * @returns {Promise<import('../types/family_files/typeFile.js').typeFile>}
+	 */
+	static async upload_file(payload)
+	{
+		const file = payload?.file;
+
+		if (!file)
+		{
+			throw new Error('FileAppService.upload_file: file is required');
+		}
+
+		const entity_type   = String(payload.entity_type || '');
+		const entity_id     = Number(payload.entity_id);
+		const category      = String(payload.category || '');
+		const mime_type     = file.type || 'application/octet-stream';
+		const size_bytes    = Number(file.size || 0);
+		const original_name = String(payload.original_name || file.name || 'upload');
+		const file_app_url  = FileAppService.get_file_app_url();
+
+		if (!file_app_url)
+		{
+			throw new Error('FileAppService.upload_file: file_app_url is not set');
+		}
+
+		const api = FileAppService.#get_api_service();
+
+		const token_wrap = await api.file_app.issue_access_token({
+			scopes     : [ 'file:upload', 'file:read' ],
+			entity_type,
+			entity_id,
+			size_bytes,
+		});
+
+		const access_token = token_wrap?.response?.access_token;
+
+		if (!access_token)
+		{
+			throw new ApiException({ message: 'File App access token was not issued' });
+		}
+
+		const init_response = await axios.post(`${ file_app_url }/api/v1/uploads`, {
+			category,
+			mime_type,
+			size_bytes,
+			original_name,
+			entity_type,
+			entity_id,
+		}, {
+			headers: {
+				Authorization: `Bearer ${ access_token }`,
+				Accept       : 'application/json',
+			},
+		});
+
+		const init = init_response?.data?.api_data;
+
+		if (!init?.presigned_url || !init?.upload_id)
+		{
+			throw new ApiException({
+				message   : 'File App upload init failed',
+				api_result: init_response?.data,
+			});
+		}
+
+		await axios.put(init.presigned_url, file, {
+			headers: { 'Content-Type': mime_type },
+		});
+
+		const confirm_response = await axios.post(
+			`${ file_app_url }/api/v1/uploads/${ encodeURIComponent(init.upload_id) }/confirm`,
+			{},
+			{
+				headers: {
+					Authorization: `Bearer ${ access_token }`,
+					Accept       : 'application/json',
+				},
+			}
+		);
+
+		const confirmed = confirm_response?.data?.api_data;
+
+		if (!confirmed?.file_uuid)
+		{
+			throw new ApiException({
+				message   : 'File App upload confirm failed',
+				api_result: confirm_response?.data,
+			});
+		}
+
+		const wire = {
+			...confirmed,
+			category   : confirmed.category || category,
+			entity_type: confirmed.entity_type || entity_type,
+			entity_id  : confirmed.entity_id ?? entity_id,
+			mime_type  : confirmed.mime_type || mime_type,
+		};
+
+		const typed = create_type_file_from_wire(wire);
+
+		if (!typed)
+		{
+			throw new ApiException({ message: 'File App upload: invalid wire after confirm' });
+		}
+
+		return typed;
+	}
+
+
+	/**
+	 * Refresh presigned URL via Main App bridge (lazy fallback when details wire expired).
+	 *
+	 * @param {string} file_uuid
+	 * @param {'inline'|'attachment'} [disposition]
+	 *
+	 * @returns {Promise<object>}
+	 */
+	static async refresh_file_access_url(file_uuid, disposition = 'inline')
+	{
+		const api  = FileAppService.#get_api_service();
+		const wrap = await api.file_app.file_access_url({ file_uuid, disposition });
+		const row  = wrap?.response;
+
+		if (!row?.url)
+		{
+			throw new ApiException({ message: 'File access URL was not resolved' });
+		}
+
+		if (disposition === 'attachment')
+		{
+			return {
+				download_url            : row.url,
+				download_url_expires_at : row.expires_at || false,
+				mime_type               : row.mime_type || false,
+			};
+		}
+
+		return {
+			preview_url            : row.url,
+			preview_url_expires_at : row.expires_at || false,
+			mime_type              : row.mime_type || false,
+		};
+	}
+}

package/publish/types/element_translate/typeFile.i18n.js

@@ -0,0 +1,54 @@
+/**
+ * Переводы для typeFile.
+ */
+export const typeFile_i18n = {
+	attribute_name_translate_matrix: {
+		en: {
+			file_uuid               : 'File',
+			category                : 'Category',
+			entity_type             : 'Entity type',
+			entity_id               : 'Entity ID',
+			mime_type               : 'MIME type',
+			original_name           : 'File name',
+			size_bytes              : 'Size (bytes)',
+			preview_url             : 'Preview URL',
+			preview_url_expires_at  : 'Preview URL expires',
+			download_url            : 'Download URL',
+			download_url_expires_at: 'Download URL expires',
+			created_at              : 'Created at',
+		},
+		ru: {
+			file_uuid               : 'Файл',
+			category                : 'Категория',
+			entity_type             : 'Тип сущности',
+			entity_id               : 'ID сущности',
+			mime_type               : 'MIME тип',
+			original_name           : 'Имя файла',
+			size_bytes              : 'Размер (байт)',
+			preview_url             : 'URL превью',
+			preview_url_expires_at  : 'Превью URL до',
+			download_url            : 'URL скачивания',
+			download_url_expires_at : 'Скачивание URL до',
+			created_at              : 'Создано',
+		},
+	},
+
+	enum_value_translate_matrix: {
+		category: {
+			en: {
+				screenshot: 'Screenshot',
+				html      : 'HTML',
+				postman   : 'Postman',
+				video     : 'Video',
+				json      : 'JSON',
+			},
+			ru: {
+				screenshot: 'Скриншот',
+				html      : 'HTML',
+				postman   : 'Postman',
+				video     : 'Видео',
+				json      : 'JSON',
+			},
+		},
+	},
+};

package/publish/types/element_translate/typeFileScreenshot.i18n.js

@@ -0,0 +1,7 @@
+/** Переводы typeFileScreenshot (расширение typeFile). */
+export const typeFileScreenshot_i18n = {
+	attribute_name_translate_matrix: {
+		en: {},
+		ru: {},
+	},
+};

package/publish/types/family_files/familyFile.js

@@ -0,0 +1,23 @@
+import { familyGeneralElement } from "../core/0_familyGeneralElement.js";
+
+
+/**
+ * Базовый family для File App сущностей.
+ *
+ * @see docs/File App Layer/README.MD
+ *
+ * @version			v.1.0 (28/06/2026)
+ */
+export class familyFile extends familyGeneralElement
+{
+	static get_category_values()
+	{
+		return [
+			'screenshot',
+			'html',
+			'postman',
+			'video',
+			'json',
+		];
+	}
+}

package/publish/types/family_files/typeFile.js

@@ -0,0 +1,135 @@
+import { familyFile } from "./familyFile.js";
+import { is_object } from "../../utils/utils.js";
+import { typeFile_i18n } from "../element_translate/typeFile.i18n.js";
+
+
+/**
+ * Базовый тип файла File App (wire + URL helpers).
+ *
+ * @version			v.1.0 (28/06/2026)
+ */
+export class typeFile extends familyFile
+{
+	static ENTITY_UTIL_EXECUTION = 'util_execution';
+
+	file_uuid;
+	category;
+	entity_type;
+	entity_id;
+	mime_type;
+	original_name;
+	size_bytes;
+	preview_url;
+	preview_url_expires_at;
+	download_url;
+	download_url_expires_at;
+	created_at;
+
+	primary_key = 'file_uuid';
+	api_key     = 'file_app';
+
+	structure_scheme = {
+		file_uuid               : 'string | max:64 | require',
+		category                : 'string | enum | require',
+		entity_type             : 'string | max:120 | optional',
+		entity_id               : 'integer | optional',
+		mime_type               : 'string | max:120 | optional',
+		original_name           : 'string | max:255 | optional',
+		size_bytes              : 'integer | optional',
+		preview_url             : 'string | max:2048 | optional',
+		preview_url_expires_at  : 'timestamp | optional',
+		download_url            : 'string | max:2048 | optional',
+		download_url_expires_at : 'timestamp | optional',
+		created_at              : 'timestamp | optional',
+	};
+
+	available_enum_values = {
+		category: familyFile.get_category_values(),
+	};
+
+	enum_value_translate_matrix = typeFile_i18n.enum_value_translate_matrix;
+
+	attribute_name_translate_matrix = typeFile_i18n.attribute_name_translate_matrix;
+
+
+	/**
+	 * @param {object|false|undefined} data
+	 */
+	constructor(data = false)
+	{
+		super();
+
+		if (data && is_object(data))
+		{
+			_.mapObject(data, (value, key) =>
+			{
+				if (this.hasOwnProperty(key))
+				{
+					this [ key ] = value;
+				}
+			});
+		}
+
+		return this;
+	}
+
+
+	/**
+	 * @param {string|false|undefined} expires_at
+	 *
+	 * @returns {boolean}
+	 */
+	static is_url_expired(expires_at)
+	{
+		if (!expires_at)
+		{
+			return true;
+		}
+
+		const expires_ms = Date.parse(expires_at);
+
+		if (Number.isNaN(expires_ms))
+		{
+			return true;
+		}
+
+		return expires_ms <= Date.now();
+	}
+
+
+	/**
+	 * @returns {string|false}
+	 */
+	get_preview_url()
+	{
+		if (!this.preview_url || typeFile.is_url_expired(this.preview_url_expires_at))
+		{
+			return false;
+		}
+
+		return this.preview_url;
+	}
+
+
+	/**
+	 * @returns {string|false}
+	 */
+	get_download_url()
+	{
+		if (!this.download_url || typeFile.is_url_expired(this.download_url_expires_at))
+		{
+			return false;
+		}
+
+		return this.download_url;
+	}
+
+
+	/**
+	 * @returns {boolean}
+	 */
+	needs_url_refresh()
+	{
+		return !this.get_preview_url();
+	}
+}

package/publish/types/family_files/typeFileFactory.js

@@ -0,0 +1,39 @@
+import { is_object } from "../../utils/utils.js";
+import { typeFile } from "./typeFile.js";
+import { typeFileScreenshot } from "./typeFileScreenshot.js";
+import { typeFileHtml } from "./typeFileHtml.js";
+import { typeFilePostman } from "./typeFilePostman.js";
+import { typeFileVideo } from "./typeFileVideo.js";
+import { typeFileJson } from "./typeFileJson.js";
+
+
+/**
+ * @param {object|false|undefined} data
+ *
+ * @returns {typeFile|false}
+ */
+export function create_type_file_from_wire(data)
+{
+	if (!data || !is_object(data))
+	{
+		return false;
+	}
+
+	const category = data.category;
+
+	switch (category)
+	{
+		case typeFileScreenshot.CATEGORY:
+			return new typeFileScreenshot(data);
+		case typeFileHtml.CATEGORY:
+			return new typeFileHtml(data);
+		case typeFilePostman.CATEGORY:
+			return new typeFilePostman(data);
+		case typeFileVideo.CATEGORY:
+			return new typeFileVideo(data);
+		case typeFileJson.CATEGORY:
+			return new typeFileJson(data);
+		default:
+			return new typeFile(data);
+	}
+}

package/publish/types/family_files/typeFileHtml.js

@@ -0,0 +1,10 @@
+import { typeFile } from "./typeFile.js";
+
+
+/** @version v.1.0 (28/06/2026) — stub */
+export class typeFileHtml extends typeFile
+{
+	static CATEGORY = 'html';
+
+	category = typeFileHtml.CATEGORY;
+}

package/publish/types/family_files/typeFileJson.js

@@ -0,0 +1,10 @@
+import { typeFile } from "./typeFile.js";
+
+
+/** @version v.1.0 (28/06/2026) — stub */
+export class typeFileJson extends typeFile
+{
+	static CATEGORY = 'json';
+
+	category = typeFileJson.CATEGORY;
+}

package/publish/types/family_files/typeFilePostman.js

@@ -0,0 +1,10 @@
+import { typeFile } from "./typeFile.js";
+
+
+/** @version v.1.0 (28/06/2026) — stub */
+export class typeFilePostman extends typeFile
+{
+	static CATEGORY = 'postman';
+
+	category = typeFilePostman.CATEGORY;
+}

package/publish/types/family_files/typeFileScreenshot.js

@@ -0,0 +1,39 @@
+import { typeFile } from "./typeFile.js";
+import { typeFileScreenshot_i18n } from "../element_translate/typeFileScreenshot.i18n.js";
+
+
+/**
+ * File App — category screenshot.
+ *
+ * @version			v.1.0 (28/06/2026)
+ */
+export class typeFileScreenshot extends typeFile
+{
+	static CATEGORY = 'screenshot';
+
+	category = typeFileScreenshot.CATEGORY;
+
+	attribute_name_translate_matrix = typeFileScreenshot_i18n.attribute_name_translate_matrix;
+
+
+	/**
+	 * Upload browser File/Blob via FileAppService.
+	 *
+	 * @param {object} payload
+	 * @param {File|Blob} payload.file
+	 * @param {string} payload.entity_type
+	 * @param {number} payload.entity_id
+	 * @param {string} [payload.original_name]
+	 *
+	 * @returns {Promise<typeFileScreenshot>}
+	 */
+	async upload(payload)
+	{
+		const { FileAppService } = await import("../../services/FileAppService.js");
+
+		return FileAppService.upload_file({
+			...payload,
+			category: typeFileScreenshot.CATEGORY,
+		});
+	}
+}

package/publish/types/family_files/typeFileVideo.js

@@ -0,0 +1,10 @@
+import { typeFile } from "./typeFile.js";
+
+
+/** @version v.1.0 (28/06/2026) — stub */
+export class typeFileVideo extends typeFile
+{
+	static CATEGORY = 'video';
+
+	category = typeFileVideo.CATEGORY;
+}

package/publish/types/family_utils/typeUtilExecution.js

@@ -6,6 +6,8 @@ import { typeUtilExecutionScreenshotMultiCapture } from "./typeUtilExecutionScre
 import { typeUtilExecutionScreenshotMultiScreenshot } from "./typeUtilExecutionScreenshotMultiScreenshot.js";
 import { typeUtilExecutionScreenshotMultiCaptureError } from "./typeUtilExecutionScreenshotMultiCaptureError.js";
 import { typeUtilExecutionEvent } from "./typeUtilExecutionEvent.js";
+import { typeFile } from "../family_files/typeFile.js";
+import { create_type_file_from_wire } from "../family_files/typeFileFactory.js";
 
 
 /**
@@ -114,7 +116,10 @@ export class typeUtilExecution extends familyUtil
 	 *   execution: typeUtilExecution,
 	 *   screenshot_multi: typeUtilExecutionScreenshotMulti|null,
 	 *   captures: typeUtilExecutionScreenshotMultiCapture[],
-	 *   screenshots: typeUtilExecutionScreenshotMultiScreenshot[],
+	 *   screenshots: Array<{
+	 *     shot: typeUtilExecutionScreenshotMultiScreenshot,
+	 *     file: import('../family_files/typeFile.js').typeFile|false,
+	 *   }>,
 	 *   capture_errors: typeUtilExecutionScreenshotMultiCaptureError[],
 	 *   events: typeUtilExecutionEvent[],
 	 * }|false}
@@ -135,7 +140,10 @@ export class typeUtilExecution extends familyUtil
 				? data.captures.map((row) => new typeUtilExecutionScreenshotMultiCapture(row))
 				: [],
 			screenshots     : Array.isArray(data.screenshots)
-				? data.screenshots.map((row) => new typeUtilExecutionScreenshotMultiScreenshot(row))
+				? data.screenshots.map((row) => ({
+					shot: new typeUtilExecutionScreenshotMultiScreenshot(row),
+					file: row.file ? create_type_file_from_wire(row.file) : false,
+				}))
 				: [],
 			capture_errors  : Array.isArray(data.capture_errors)
 				? data.capture_errors.map((row) => new typeUtilExecutionScreenshotMultiCaptureError(row))