itube-specs 0.0.718 → 0.0.720

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "itube-specs",
   "type": "module",
-  "version": "0.0.718",
+  "version": "0.0.720",
   "main": "./nuxt.config.ts",
   "types": "./types/index.d.ts",
   "scripts": {

package/runtime/utils/check-device-width.ts

@@ -13,6 +13,10 @@ function breakpoints(breakpoints: Record<CssBreakpoints, number>) {
     )
 }
 
+/**
+ * Возвращает реактивные флаги isMobile и isTablet на основе переданных breakpoints.
+ * @param projectBreakpoints - набор брейкпоинтов проекта (xs, sm, md, lg, xl) в пикселях
+ */
 export const checkDeviceWidth = (projectBreakpoints: Record<CssBreakpoints, number>) => {
     const isMobile = breakpoints(projectBreakpoints).smaller('sm');
     const isTablet = breakpoints(projectBreakpoints).smaller('md');

package/runtime/utils/compress-image.ts

@@ -1,3 +1,9 @@
+/**
+ * Сжимает изображение до maxSize px по наибольшей стороне и возвращает Blob в формате JPEG.
+ * @param blob - исходное изображение
+ * @param maxSize - максимальный размер стороны в px (по умолчанию 512)
+ * @param quality - качество JPEG от 0 до 1 (по умолчанию 0.8)
+ */
 export const compressImage = (blob: Blob, maxSize = 512, quality = 0.8): Promise<Blob> => {
   return new Promise((resolve, reject) => {
     const img = new Image();

package/runtime/utils/format-date.ts

@@ -1,3 +1,4 @@
+/** Форматирует Unix timestamp (в секундах) в строку вида ДД.ММ.ГГГГ. */
 export function formatDate(seconds: number): string {
   const date = new Date(1000 * seconds);
 

package/runtime/utils/format-number.ts

@@ -1,6 +1,6 @@
 /**
- * Форматирует число в короткий формат 10400 => 10.4K
- * @param {number} number - число
+ * Форматирует число в короткий формат: 10400 → 10.4K.
+ * @param number - исходное число
  */
 
 export function formatNumber (number: number) {

package/runtime/utils/format-time-ago.ts

@@ -1,3 +1,8 @@
+/**
+ * Форматирует Unix timestamp (в секундах) в относительную строку: «сегодня», «вчера», «3 дня назад» и т.д.
+ * @param date - Unix timestamp в секундах
+ * @param t - функция перевода (i18n)
+ */
 export function formatTimeAgo(date: number, t) {
   const pastDate = new Date(date * 1000);
   const now = new Date();

package/runtime/utils/format-time.ts

@@ -1,3 +1,4 @@
+/** Форматирует секунды в строку мм:сс, или чч:мм:сс если есть часы. */
 export function formatTime(seconds: number): string {
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);

package/runtime/utils/get-duration.ts

@@ -1,6 +1,6 @@
 /**
- * Возвращает продолжительность по переданным секундам в формате hh:mm:ss
- * @param {seconds} number - число секунды
+ * Возвращает продолжительность по переданным секундам в формате [чч:]мм:сс.
+ * @param seconds - количество секунд
  */
 export function getDuration (seconds: number) {
   const date = new Date(0);

package/runtime/utils/get-month.ts

@@ -1,6 +1,8 @@
 /**
- * возвращает название месяца по цифре
-  */
+ * Возвращает локализованное название месяца по его номеру (0-based).
+ * @param t - функция перевода (i18n)
+ * @param number - номер месяца от 0 (январь) до 11 (декабрь)
+ */
 export function getMonth(t: (key: string) => string, number?: number) {
   const months = [
     'january',

package/runtime/utils/get-multiple-query.ts

@@ -2,6 +2,13 @@ import type { RouteLocationNormalizedLoaded } from 'vue-router';
 import type { IChipsItem, ISelectItem } from '../../types';
 import { getSelectedQuery } from '../utils/get-selected-query';
 
+/**
+ * Возвращает query-объект для диапазонного фильтра (min/max) на основе текущего маршрута.
+ * @param route - текущий маршрут Vue Router
+ * @param items - список элементов фильтра
+ * @param minKey - ключ минимального значения в query
+ * @param maxKey - ключ максимального значения в query
+ */
 export function getMultipleQuery (
   route: RouteLocationNormalizedLoaded,
   items: ISelectItem[] | IChipsItem[],

package/runtime/utils/get-selected-query.ts

@@ -1,6 +1,7 @@
 import type { RouteLocation } from 'vue-router';
 import type { IChipsItem, ISelectItem } from '../../types';
 
+/** Возвращает значение query выбранного элемента из items, совпадающего с текущим маршрутом. */
 export function getSelectedQuery(route: RouteLocation, items: IChipsItem[] | ISelectItem[]) {
   return items.find(item => item.value === route.query[item.key || ''])?.query;
 }

package/runtime/utils/is-mobile-device.ts

@@ -1,3 +1,4 @@
+/** Возвращает true если userAgent соответствует мобильному устройству. */
 export const isMobileDevice = (userAgent: string) => {
   return /Android|webOS|iPhone|iPad|iPod|BlackBerry|Windows Phone/i.test(userAgent)
 }

package/runtime/utils/normalize-url.ts

@@ -1,3 +1,4 @@
+/** Нормализует URL: убирает page=1, sort=trending, пустые query, приводит к нижнему регистру, заменяет пробелы на дефисы. */
 export function normalizeUrl(to: { path: string; query: Record<string, any> }) {
   let path = to.path
   let query = { ...to.query }

package/runtime/utils/on-backdrop-click.ts

@@ -1,3 +1,4 @@
+/** Вызывает callback если клик пришёл непосредственно по элементу <dialog> (backdrop), а не по его содержимому. */
 export function onBackdropClick(target: HTMLDialogElement, callback: () => void) {
   if (target?.nodeName === 'DIALOG') {
     callback();

package/runtime/utils/scroll-lock.ts

@@ -1,3 +1,4 @@
+/** Возвращает функции lockScroll/unlockScroll для блокировки прокрутки страницы через overflow: hidden. */
 const lockScroll = () => {
   document.body.style.overflow = 'hidden';
 };

package/runtime/utils/server/age.ts

@@ -1,6 +1,7 @@
 import { getCookie } from 'h3';
 import { getClientHeaders } from './get-client-headers';
 
+/** Возвращает true если пользователь находится в регионе где требуется верификация возраста (GB, штат KS). */
 export async function isGeoMatch(event, config) {
     const AGE_VERIFY_REGIONS = ['KS'];
     const AGE_VERIFY_COUNTRIES = ['GB'];
@@ -13,6 +14,7 @@ export async function isGeoMatch(event, config) {
         || AGE_VERIFY_REGIONS.includes(stateCode);
 }
 
+/** Проверяет через API прошёл ли пользователь верификацию возраста по session_id из cookie или контекста. */
 export async function isAgeVerified(event, config) {
     const apiUrl = config.public.apiDomain;
     const sessionId = getCookie(event, 'session_id') || event?.context.sessionId;
@@ -33,6 +35,11 @@ export async function isAgeVerified(event, config) {
     return res.data === true;
 }
 
+/**
+ * Запрашивает у API URL для редиректа на страницу верификации возраста.
+ * @param backPath - путь на который вернуть пользователя после верификации
+ * @returns URL редиректа и countryCode пользователя
+ */
 export async function getAgeValidationUrl(event, backPath: string, config) {
     const sessionId = event.context?.sessionId || getCookie(event, 'session_id');
     const apiUrl = config.public.apiDomain;

package/runtime/utils/server/api-helper.ts

@@ -1,8 +1,12 @@
 import type { NitroFetchOptions } from "nitropack/types";
 
-/** Хелпер для работы с API */
+/** Клиентский хелпер для запросов через BFF (/bff prefix). Автоматически добавляет x-domain заголовок. */
 export class ApiHelper {
-    /** Метод для получения данных */
+    /**
+     * @param path - путь без /bff префикса, например `/videos/list`
+     * @param fetchOptions - стандартные опции $fetch
+     * @param runtimeConfig - useRuntimeConfig() для получения xDomain
+     */
     static async fetch<T>(
         path: string,
         fetchOptions: NitroFetchOptions<string>,

package/runtime/utils/server/get-client-headers.ts

@@ -1,3 +1,7 @@
+/**
+ * Извлекает гео-данные и клиентские параметры из заголовков запроса.
+ * Поддерживает заголовки Cloudflare (cf-ipcountry, cf-region) и кастомные (x-country-code, x-region-code).
+ */
 export function getClientHeaders(event: any) {
   const headers = event.node.req.headers;
 

package/runtime/utils/server/get-url-with-proxied-params.ts

@@ -1,3 +1,4 @@
+/** Копирует query-параметры из текущего запроса (event) в переданный URL. Используется для проксирования запросов с сохранением параметров. */
 export function getUrlWithProxiedParams(url: string, event) {
     const _url = new URL(url);
     _url.search = new URLSearchParams(getQuery(event));

package/runtime/utils/server/parse-api-error.ts

@@ -1,3 +1,7 @@
+/**
+ * Нормализует ошибку API в строку.
+ * Обрабатывает форматы: `data.error`, `error`, строку, массив и объект с вложенными значениями.
+ */
 export function parseApiError(error: any): string {
   const fallback = 'Unknown error occurred.';
 

package/runtime/utils/server/server-api-helper.ts

@@ -2,7 +2,13 @@ import type { H3Event } from "h3";
 import { getHeaders } from "h3";
 import type { FetchOptions } from "ofetch";
 
+/** Серверный хелпер для запросов к внешнему API. Проксирует заголовки клиента и разворачивает `response.data`. */
 export class ServerApiHelper {
+    /**
+     * @param url - полный URL внешнего API
+     * @param event - H3Event для проброса заголовков клиента
+     * @param requestOptions - дополнительные опции fetch (method, body и т.д.)
+     */
     public static async fetch<T>(url: string, event: H3Event, requestOptions?: FetchOptions): Promise<T> {
         try {
             const response = await $fetch<{ data: T }>(url, {

package/runtime/utils/validate-email.ts

@@ -1,3 +1,4 @@
+/** Возвращает true если строка является валидным email-адресом. */
 export function validateEmail(value: string) {
     const re = /^[\w&*+-]+(?:\.[\w&*+-]+)*@(?:[\da-z-]+\.)+[a-z]{2,}$/gi;
     return value?.length !== 0 && re.test(String(value).toLowerCase());

package/runtime/utils/validate-password.ts

@@ -1,3 +1,4 @@
+/** Возвращает true если пароль длиннее 4 символов. */
 export function validatePassword(value: string) {
   return value.length > 4;
 };

package/runtime/utils/validate-phone.ts

@@ -1,3 +1,4 @@
+/** Возвращает true если строка является валидным номером телефона (7–20 цифр, опциональные +, пробелы, скобки и дефисы). */
 export function validatePhone (value: string) {
   const re = /^\+?[0-9\s\-().]{7,20}$/;
   return value?.length !== 0 && re.test(String(value).trim());

package/runtime/utils/validate-username.ts

@@ -1,3 +1,4 @@
+/** Возвращает true если имя пользователя состоит из 2–20 символов (латиница, цифры, _ и -). */
 export function validateUsername (value: string) {
   const re = /^[a-zA-Z0-9_-]{2,20}$/;
   return value.length !== 0 && re.test(String(value).toLowerCase());

package/runtime/utils/video-data-add-model-icon.ts

@@ -1,5 +1,10 @@
 import type { IRawModelCard, IRawVideoData } from '../../types';
 
+/**
+ * Добавляет поле icon из modelsData в каждую модель videoData.models по совпадению guid.
+ * @param videoData - сырые данные видео
+ * @param modelsData - массив карточек моделей с primary_image_url
+ */
 export function videoDataAddModelIcon(videoData: IRawVideoData, modelsData: Array<IRawModelCard>): IRawVideoData {
   const transformedData = { ...videoData };
 

package/runtime/utils/vtt-helper.ts

@@ -4,6 +4,7 @@ export interface IVttItem {
     coords: { x: number; y: number; w: number; h: number };
 }
 
+/** Загружает и парсит VTT-файл с тайм-кодами и координатами спрайтов превью видео. */
 export class VttHelper {
   private readonly vttUrl: string;
   public hasInited: boolean;
@@ -15,6 +16,7 @@ export class VttHelper {
     this.vttData = null;
   }
 
+  /** Загружает и парсит VTT-файл по url из конструктора. Устанавливает hasInited = true после успешной загрузки. */
   async init(): Promise<void> {
     const vttContent: Response = await fetch(this.vttUrl);
 
@@ -71,6 +73,11 @@ export class VttHelper {
     return hh * 3600 + mm * 60 + ss;
   }
 
+  /**
+   * Возвращает координаты спрайта превью для указанного времени воспроизведения.
+   * @param time - время в секундах
+   * @param vttData - данные VTT (по умолчанию загруженные через init)
+   */
   getCoordsByTime(time: number, vttData: Array<IVttItem> | null = this.vttData):
       { x: number; y: number; w: number; h: number } | string {
     if (!this.hasInited || !vttData) {