@media-engine/core 0.1.0

package/dist/engine/engine.js

@@ -0,0 +1,1007 @@
+import { MediaEngineError, ProviderError, toProviderFailure } from "../errors/index.js";
+import { DefaultMergeStrategy } from "../merge/index.js";
+import { ProviderRegistry } from "../providers/index.js";
+// Top-level public external ID shortcuts supported by engine queries.
+// Верхнеуровневые публичные сокращения внешних ID, поддерживаемые query движка.
+const EXTERNAL_ID_SHORTCUTS = [
+    "imdb",
+    "tmdb",
+    "kinopoisk",
+    "shikimori",
+    "myAnimeList",
+    "aniList",
+];
+const SEARCH_ID_ENRICHMENT_LIMIT = 6;
+const SEARCH_ID_ENRICHMENT_TIMEOUT_MS = 1_500;
+const SEARCH_DETAILS_POSTER_ENRICHMENT_LIMIT = 3;
+const SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS = 1_500;
+const SEARCH_FALLBACK_MIN_TOKENS = 3;
+const SEARCH_FALLBACK_MIN_LAST_TOKEN_LENGTH = 4;
+const SEARCH_JOINED_FALLBACK_MIN_LENGTH = 6;
+const SEARCH_JOINED_FALLBACK_MAX_LENGTH = 8;
+const SEARCH_JOINED_FALLBACK_MIN_PART_LENGTH = 3;
+const MAX_SEARCH_LIMIT = 100;
+const MAX_PROVIDER_SEARCH_LIMIT = 100;
+const EXPIRING_AVAILABILITY_CACHE_SAFETY_MS = 1_000;
+// Main entry point for using Media Engine core.
+// Главная точка входа для использования Media Engine core.
+export class MediaEngine {
+    registry;
+    streamingProviders;
+    cache;
+    mergeStrategy;
+    timeoutMs;
+    providerTimeouts;
+    debug;
+    constructor(options = {}) {
+        this.registry = new ProviderRegistry(options.providers ?? []);
+        this.streamingProviders = validateStreamingProviders(options.streamingProviders ?? []);
+        this.cache = options.cache;
+        this.mergeStrategy = options.mergeStrategy ?? new DefaultMergeStrategy();
+        this.timeoutMs = options.timeoutMs;
+        this.providerTimeouts = { ...options.providerTimeouts };
+        this.debug = options.debug ?? false;
+    }
+    // Returns safe registered provider metadata without provider internals.
+    // Возвращает безопасные метаданные зарегистрированных провайдеров без внутренних данных.
+    getProviders() {
+        return this.registry.getProviders();
+    }
+    // Returns safe registered streaming provider metadata without provider internals.
+    // Возвращает безопасные метаданные streaming-провайдеров без внутренних данных.
+    getStreamingProviders() {
+        return this.streamingProviders.map((provider) => ({
+            name: provider.name,
+            version: provider.version,
+            kind: provider.kind,
+            capabilities: {
+                mediaTypes: [...provider.capabilities.mediaTypes],
+                lookup: {
+                    byTitle: provider.capabilities.lookup.byTitle,
+                    byExternalIds: [...provider.capabilities.lookup.byExternalIds],
+                    byEpisode: provider.capabilities.lookup.byEpisode,
+                },
+                features: provider.capabilities.features ? [...provider.capabilities.features] : undefined,
+            },
+        }));
+    }
+    // Searches media through selected providers and merges normalized results.
+    // Ищет медиа через выбранных провайдеров и объединяет нормализованные результаты.
+    async search(query) {
+        const startedAt = Date.now();
+        const normalizedQuery = normalizeSearchQuery(query);
+        validateSearchQuery(normalizedQuery);
+        const searchLanguage = normalizedQuery.language ?? inferTitleLanguage(normalizedQuery.title);
+        const cacheKey = createSearchCacheKey(normalizedQuery);
+        const cached = await this.cache?.get(cacheKey);
+        if (cached) {
+            return {
+                ...cached,
+                query: normalizedQuery,
+                meta: {
+                    ...cached.meta,
+                    cached: true,
+                    tookMs: elapsedSince(startedAt),
+                },
+            };
+        }
+        const providers = this.registry.selectSearchProviders(normalizedQuery);
+        const requested = providers.map((provider) => provider.name);
+        const successful = [];
+        const failed = [];
+        const warnings = [];
+        const providerResults = [];
+        const providerTimings = [];
+        let outcomes = await Promise.all(providers.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(normalizedQuery), {
+            debug: this.debug,
+            language: searchLanguage,
+            timeoutMs: this.getProviderTimeoutMs(provider.name),
+        })));
+        if (outcomes.length > 0 && outcomes.every((outcome) => outcome.failure)) {
+            outcomes = await retryFailedSearchProviders(providers, outcomes, normalizedQuery, {
+                debug: this.debug,
+                language: searchLanguage,
+                getTimeoutMs: (providerName) => this.getProviderTimeoutMs(providerName),
+            });
+        }
+        for (const outcome of outcomes) {
+            providerTimings.push(outcome.timing);
+            if (outcome.failure) {
+                failed.push(outcome.failure);
+            }
+            else {
+                successful.push(outcome.provider);
+                providerResults.push(...outcome.results);
+            }
+        }
+        if (providers.length > 0 && successful.length === 0 && failed.length > 0) {
+            throw new MediaEngineError({
+                code: "PROVIDER_ERROR",
+                message: "All search providers failed.",
+                cause: { failed },
+            });
+        }
+        let results = this.mergeStrategy.mergeSearchResults(providerResults, {
+            query: normalizedQuery,
+            language: searchLanguage,
+            debug: this.debug,
+            warnings,
+            includeIrrelevantSearchResults: true,
+        });
+        const fallbackQuery = createSearchFallbackQuery(normalizedQuery);
+        const hasRelevantResults = fallbackQuery
+            ? this.mergeStrategy.mergeSearchResults(providerResults, {
+                query: normalizedQuery,
+                language: searchLanguage,
+                debug: this.debug,
+            }).length > 0
+            : true;
+        if (fallbackQuery && !hasRelevantResults) {
+            const fallbackOutcomes = await Promise.all(providers.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(fallbackQuery), {
+                debug: this.debug,
+                language: searchLanguage,
+                timeoutMs: this.getProviderTimeoutMs(provider.name),
+            })));
+            appendUniqueSearchResults(providerResults, fallbackOutcomes.flatMap((outcome) => (outcome.failure ? [] : outcome.results)));
+            results = this.mergeStrategy.mergeSearchResults(providerResults, {
+                query: normalizedQuery,
+                language: searchLanguage,
+                debug: this.debug,
+                warnings,
+                includeIrrelevantSearchResults: true,
+            });
+        }
+        const excludedPosterProviders = new Set(failed.map((failure) => failure.provider));
+        const posterEnrichmentPromise = Promise.all(results
+            .slice(0, SEARCH_DETAILS_POSTER_ENRICHMENT_LIMIT)
+            .filter((result) => hasExternalIds(result.item.ids))
+            .map(async (result) => ({
+            ids: result.item.ids,
+            poster: await this.loadSearchPoster(result.item.type, result.item.ids, searchLanguage, excludedPosterProviders).catch(() => undefined),
+        })));
+        const enrichmentResultsPromise = Promise.all(results
+            .slice(0, SEARCH_ID_ENRICHMENT_LIMIT)
+            .filter((result) => needsSearchEnrichment(result.item) && hasExternalIds(result.item.ids))
+            .map(async (result) => {
+            const existingProviders = new Set(result.sources.map((source) => source.provider));
+            const enrichmentType = result.item.type === "anime" ? undefined : result.item.type;
+            const enrichmentProvider = this.registry
+                .selectSearchProviders({ ids: result.item.ids, type: enrichmentType })
+                .find((provider) => !existingProviders.has(provider.name));
+            if (!enrichmentProvider) {
+                return [];
+            }
+            const providerTimeoutMs = this.getProviderTimeoutMs(enrichmentProvider.name);
+            const enrichmentTimeoutMs = providerTimeoutMs === undefined
+                ? SEARCH_ID_ENRICHMENT_TIMEOUT_MS
+                : Math.min(providerTimeoutMs, SEARCH_ID_ENRICHMENT_TIMEOUT_MS);
+            const outcome = await callTimedProviderSearch(enrichmentProvider, {
+                ids: result.item.ids,
+                type: enrichmentType,
+                limit: 1,
+                language: searchLanguage,
+            }, {
+                debug: this.debug,
+                language: searchLanguage,
+                timeoutMs: enrichmentTimeoutMs,
+            });
+            return outcome.failure ? [] : outcome.results;
+        }));
+        const [enrichmentResults, posterEnrichments] = await Promise.all([
+            enrichmentResultsPromise,
+            posterEnrichmentPromise,
+        ]);
+        const flattenedEnrichmentResults = enrichmentResults.flat();
+        if (flattenedEnrichmentResults.length > 0) {
+            providerResults.push(...flattenedEnrichmentResults);
+        }
+        if (this.mergeStrategy instanceof DefaultMergeStrategy ||
+            flattenedEnrichmentResults.length > 0) {
+            results = this.mergeStrategy.mergeSearchResults(providerResults, {
+                query: normalizedQuery,
+                language: searchLanguage,
+                debug: this.debug,
+                warnings,
+            });
+        }
+        const posterEnrichedResults = results.map((result) => {
+            const poster = posterEnrichments.find((enrichment) => enrichment.poster && hasSharedExternalId(result.item.ids, enrichment.ids))?.poster;
+            return poster ? { ...result, item: { ...result.item, poster } } : result;
+        });
+        const limitedResults = normalizedQuery.limit === undefined
+            ? posterEnrichedResults
+            : posterEnrichedResults.slice(0, normalizedQuery.limit);
+        const response = {
+            query: normalizedQuery,
+            results: limitedResults,
+            meta: createResponseMeta({
+                requested,
+                successful,
+                failed,
+                warnings,
+                cached: false,
+                tookMs: elapsedSince(startedAt),
+                debug: this.debug,
+                timings: providerTimings,
+            }),
+        };
+        await this.cache?.set(cacheKey, response);
+        return response;
+    }
+    // Loads media details through selected providers and merges normalized results.
+    // Загружает детали медиа через выбранных провайдеров и объединяет нормализованные результаты.
+    async getDetails(query) {
+        const startedAt = Date.now();
+        const normalizedQuery = normalizeDetailsQuery(query);
+        validateDetailsQuery(normalizedQuery);
+        const cacheKey = createDetailsCacheKey(normalizedQuery);
+        const cached = await this.cache?.get(cacheKey);
+        if (cached) {
+            return {
+                ...cached,
+                query: normalizedQuery,
+                meta: {
+                    ...cached.meta,
+                    cached: true,
+                    tookMs: elapsedSince(startedAt),
+                },
+            };
+        }
+        const providers = this.registry.selectDetailsProviders(normalizedQuery);
+        const requested = providers.map((provider) => provider.name);
+        const successful = [];
+        const failed = [];
+        const warnings = [];
+        const providerResults = [];
+        const providerTimings = [];
+        const outcomes = await Promise.all(providers.map((provider) => callTimedProviderDetails(provider, normalizedQuery, {
+            debug: this.debug,
+            language: normalizedQuery.language,
+            timeoutMs: this.getProviderTimeoutMs(provider.name),
+        })));
+        for (const outcome of outcomes) {
+            providerTimings.push(outcome.timing);
+            if (outcome.failure) {
+                failed.push(outcome.failure);
+            }
+            else {
+                successful.push(outcome.provider);
+                if (outcome.result) {
+                    providerResults.push(outcome.result);
+                }
+            }
+        }
+        if (providers.length > 0 && successful.length === 0 && failed.length > 0) {
+            throw new MediaEngineError({
+                code: "PROVIDER_ERROR",
+                message: "All details providers failed.",
+                cause: { failed },
+            });
+        }
+        const details = this.mergeStrategy.mergeDetails(providerResults, {
+            query: normalizedQuery,
+            language: normalizedQuery.language,
+            debug: this.debug,
+            warnings,
+        });
+        const response = {
+            query: normalizedQuery,
+            details,
+            meta: createResponseMeta({
+                requested,
+                successful,
+                failed,
+                warnings,
+                cached: false,
+                tookMs: elapsedSince(startedAt),
+                debug: this.debug,
+                timings: providerTimings,
+            }),
+        };
+        await this.cache?.set(cacheKey, response);
+        return response;
+    }
+    // Loads normalized player and stream availability through streaming providers.
+    // Загружает нормализованную доступность player и stream через streaming-провайдеры.
+    async getAvailability(query) {
+        const startedAt = Date.now();
+        const normalizedQuery = normalizeStreamQuery(query);
+        validateStreamQuery(normalizedQuery);
+        const cacheKey = createAvailabilityCacheKey(normalizedQuery);
+        const cached = await this.cache?.get(cacheKey);
+        if (cached) {
+            return {
+                ...cached,
+                query: normalizedQuery,
+                meta: cached.meta
+                    ? {
+                        ...cached.meta,
+                        cached: true,
+                        tookMs: elapsedSince(startedAt),
+                    }
+                    : undefined,
+            };
+        }
+        const providers = selectStreamingProviders(this.streamingProviders, normalizedQuery);
+        const requested = providers.map((provider) => provider.name);
+        const successful = [];
+        const failed = [];
+        const providerResults = [];
+        const providerTimings = [];
+        const outcomes = await Promise.all(providers.map((provider) => callTimedProviderAvailability(provider, normalizedQuery, {
+            debug: this.debug,
+            language: normalizedQuery.language,
+            timeoutMs: this.getProviderTimeoutMs(provider.name),
+        })));
+        for (const outcome of outcomes) {
+            providerTimings.push(outcome.timing);
+            if (outcome.failure) {
+                failed.push(outcome.failure);
+            }
+            else if (outcome.result) {
+                successful.push(outcome.provider);
+                providerResults.push(outcome.result);
+            }
+        }
+        if (providers.length > 0 && providerResults.length === 0 && failed.length > 0) {
+            throw new MediaEngineError({
+                code: "PROVIDER_ERROR",
+                message: "All streaming providers failed.",
+                cause: { failed },
+            });
+        }
+        const availability = mergeAvailabilityResults(normalizedQuery, providerResults);
+        availability.meta = createResponseMeta({
+            requested,
+            successful,
+            failed,
+            warnings: [],
+            cached: false,
+            tookMs: elapsedSince(startedAt),
+            debug: this.debug,
+            timings: providerTimings,
+        });
+        await this.cache?.set(cacheKey, availability, createAvailabilityCacheOptions(availability));
+        return availability;
+    }
+    // Gives future engine methods access to the registered providers.
+    // Дает будущим методам движка доступ к зарегистрированным провайдерам.
+    get providerRegistry() {
+        return this.registry;
+    }
+    // Gives future engine methods access to the optional cache.
+    // Дает будущим методам движка доступ к опциональному cache.
+    get engineCache() {
+        return this.cache;
+    }
+    // Gives future engine methods access to the configured merge strategy.
+    // Дает будущим методам движка доступ к настроенной стратегии объединения.
+    get engineMergeStrategy() {
+        return this.mergeStrategy;
+    }
+    // Gives future engine methods access to the configured timeout.
+    // Дает будущим методам движка доступ к настроенному timeout.
+    get engineTimeoutMs() {
+        return this.timeoutMs;
+    }
+    // Resolves a provider override without allowing it to exceed the global boundary.
+    // Выбирает override провайдера, не позволяя ему превысить глобальную границу.
+    getProviderTimeoutMs(providerName) {
+        const providerTimeoutMs = this.providerTimeouts[providerName];
+        if (providerTimeoutMs === undefined) {
+            return this.timeoutMs;
+        }
+        return this.timeoutMs === undefined
+            ? providerTimeoutMs
+            : Math.min(this.timeoutMs, providerTimeoutMs);
+    }
+    // Loads only the canonical poster needed by search without blocking on a full details request.
+    // Загружает только канонический постер для search, не блокируя полный details-запрос.
+    async loadSearchPoster(type, ids, language, excludedProviders) {
+        if (!hasExternalIds(ids)) {
+            return undefined;
+        }
+        const query = { type, ids, language };
+        const providers = this.registry
+            .selectDetailsProviders(query)
+            .filter((provider) => !excludedProviders.has(provider.name));
+        const outcomes = await Promise.all(providers.map((provider) => {
+            const providerTimeoutMs = this.getProviderTimeoutMs(provider.name);
+            return callTimedProviderDetails(provider, query, {
+                debug: this.debug,
+                language,
+                timeoutMs: providerTimeoutMs === undefined
+                    ? SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS
+                    : Math.min(providerTimeoutMs, SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS),
+            });
+        }));
+        const providerResults = outcomes.flatMap((outcome) => outcome.failure || !outcome.result ? [] : [outcome.result]);
+        return this.mergeStrategy.mergeDetails(providerResults, {
+            query,
+            language,
+            debug: this.debug,
+            warnings: [],
+        })?.poster;
+    }
+    // Gives future engine methods access to the debug flag.
+    // Дает будущим методам движка доступ к debug-флагу.
+    get engineDebug() {
+        return this.debug;
+    }
+}
+// Enriches compact catalog hits when follow-up cards would otherwise choose different metadata.
+// Обогащает compact catalog hits, чтобы search и details не выбирали разные metadata.
+function needsSearchEnrichment(item) {
+    return !item.ratings?.length || !item.description?.trim() || !item.poster;
+}
+// Validates streaming providers and rejects duplicate public names.
+// Проверяет streaming-провайдеры и отклоняет дубли публичных имен.
+function validateStreamingProviders(providers) {
+    const names = new Set();
+    for (const provider of providers) {
+        const name = provider.name.trim();
+        if (!name) {
+            throw new Error("Streaming provider name is required.");
+        }
+        if (name !== provider.name) {
+            throw new Error(`Streaming provider name "${provider.name}" must not include leading or trailing whitespace.`);
+        }
+        if (names.has(name)) {
+            throw new Error(`Streaming provider "${name}" is already registered.`);
+        }
+        names.add(name);
+    }
+    return [...providers];
+}
+// Normalizes top-level external ID shortcuts into the ids object.
+// Нормализует верхнеуровневые сокращения внешних ID в объект ids.
+function normalizeSearchQuery(query) {
+    const ids = { ...(query.ids ?? {}) };
+    for (const key of EXTERNAL_ID_SHORTCUTS) {
+        const value = query[key];
+        if (value) {
+            ids[key] = value;
+        }
+    }
+    return {
+        ...query,
+        title: query.title?.trim(),
+        ids: hasExternalIds(ids) ? ids : undefined,
+    };
+}
+// Infers a provider lookup language only when the caller did not specify one.
+// Определяет язык provider lookup только если caller не передал его явно.
+function inferTitleLanguage(title) {
+    if (!title)
+        return undefined;
+    if (/[а-яё]/iu.test(title))
+        return "ru";
+    if (/[\u3040-\u30ff\u3400-\u9fff]/u.test(title))
+        return "ja";
+    return /[a-z]/iu.test(title) ? "en" : undefined;
+}
+// Normalizes top-level external ID shortcuts into a details ids object.
+// Нормализует верхнеуровневые сокращения внешних ID в объект ids для details.
+function normalizeDetailsQuery(query) {
+    const ids = { ...(query.ids ?? {}) };
+    for (const key of EXTERNAL_ID_SHORTCUTS) {
+        const value = query[key];
+        if (value) {
+            ids[key] = value;
+        }
+    }
+    return {
+        ...query,
+        ids: hasExternalIds(ids) ? ids : undefined,
+    };
+}
+// Normalizes top-level external ID shortcuts into a streaming ids object.
+// Нормализует верхнеуровневые сокращения внешних ID в объект ids для streaming.
+function normalizeStreamQuery(query) {
+    const queryWithShortcuts = query;
+    const ids = { ...(query.ids ?? {}) };
+    const providers = query.providers?.map((provider) => provider.trim()).filter(Boolean);
+    const language = query.language?.trim();
+    for (const key of EXTERNAL_ID_SHORTCUTS) {
+        const value = queryWithShortcuts[key];
+        if (value) {
+            ids[key] = value;
+        }
+    }
+    return {
+        ...query,
+        title: query.title?.trim(),
+        ...(hasExternalIds(ids) ? { ids } : {}),
+        ...(providers && providers.length > 0 ? { providers } : {}),
+        ...(language ? { language } : {}),
+    };
+}
+// Validates that a search query has at least one supported lookup input.
+// Проверяет, что search query содержит хотя бы один поддерживаемый вход для поиска.
+function validateSearchQuery(query) {
+    if (query.limit !== undefined &&
+        (!Number.isInteger(query.limit) || query.limit < 0 || query.limit > MAX_SEARCH_LIMIT)) {
+        throw new MediaEngineError({
+            code: "INVALID_QUERY",
+            message: `Search query limit must be an integer between 0 and ${MAX_SEARCH_LIMIT}.`,
+        });
+    }
+    if (query.title || hasExternalIds(query.ids)) {
+        return;
+    }
+    throw new MediaEngineError({
+        code: "INVALID_QUERY",
+        message: "Search query must include title or external ids.",
+    });
+}
+// Validates that a details query has at least one supported lookup input.
+// Проверяет, что details query содержит хотя бы один поддерживаемый вход для поиска.
+function validateDetailsQuery(query) {
+    if (query.id?.trim() || hasExternalIds(query.ids)) {
+        return;
+    }
+    throw new MediaEngineError({
+        code: "INVALID_QUERY",
+        message: "Details query must include id or external ids.",
+    });
+}
+// Validates that a streaming query can identify a media item or episode.
+// Проверяет, что streaming query может определить медиа или эпизод.
+function validateStreamQuery(query) {
+    if (!query.type) {
+        throw new MediaEngineError({
+            code: "INVALID_QUERY",
+            message: "Stream query type is required.",
+        });
+    }
+    if ([query.year, query.seasonNumber, query.episodeNumber, query.absoluteEpisodeNumber].some((value) => value !== undefined && (!Number.isInteger(value) || value < 0))) {
+        throw new MediaEngineError({
+            code: "INVALID_QUERY",
+            message: "Stream query numeric fields must be non-negative integers.",
+        });
+    }
+    if (query.title || hasExternalIds(query.ids)) {
+        return;
+    }
+    throw new MediaEngineError({
+        code: "INVALID_QUERY",
+        message: "Stream query must include title or external ids.",
+    });
+}
+// Selects streaming providers that can answer the normalized stream query.
+// Выбирает streaming-провайдеры, которые могут ответить на нормализованный stream query.
+function selectStreamingProviders(providers, query) {
+    return providers.filter((provider) => {
+        if (query.providers && !query.providers.includes(provider.name)) {
+            return false;
+        }
+        if (!provider.capabilities.mediaTypes.includes(query.type)) {
+            return false;
+        }
+        if (hasEpisodeQuery(query) && !provider.capabilities.lookup.byEpisode) {
+            return false;
+        }
+        return (Boolean(query.title && provider.capabilities.lookup.byTitle) ||
+            hasSupportedExternalId(query.ids, provider.capabilities.lookup.byExternalIds));
+    });
+}
+// Gives providers enough candidates so the engine can rank before applying the public limit.
+// Дает провайдерам достаточно кандидатов, чтобы движок ранжировал до применения публичного limit.
+function createProviderSearchQuery(query) {
+    if (query.limit === undefined || query.limit === 0) {
+        return query;
+    }
+    return {
+        ...query,
+        limit: getProviderSearchLimit(query),
+    };
+}
+// Retries only transient failures when every selected search provider failed together.
+// Повторяет только временные ошибки, когда одновременно упали все выбранные search-провайдеры.
+async function retryFailedSearchProviders(providers, outcomes, query, context) {
+    return Promise.all(outcomes.map(async (outcome, index) => {
+        const provider = providers[index];
+        if (!provider || !outcome.failure?.retryable) {
+            return outcome;
+        }
+        return callTimedProviderSearch(provider, createProviderSearchQuery(query), {
+            debug: context.debug,
+            language: context.language,
+            timeoutMs: context.getTimeoutMs(provider.name),
+        });
+    }));
+}
+// Broadens an empty typo search or separates one likely joined compound title.
+// Расширяет пустой поиск с опечаткой или разделяет вероятно слитное составное название.
+function createSearchFallbackQuery(query) {
+    if (!query.title || hasExternalIds(query.ids)) {
+        return undefined;
+    }
+    const title = query.title.trim();
+    const tokens = title.split(/\s+/);
+    const lastToken = tokens.at(-1);
+    if (tokens.length >= SEARCH_FALLBACK_MIN_TOKENS &&
+        lastToken &&
+        lastToken.length >= SEARCH_FALLBACK_MIN_LAST_TOKEN_LENGTH) {
+        return {
+            ...query,
+            title: tokens.slice(0, -1).join(" "),
+        };
+    }
+    const characters = [...title];
+    if (tokens.length !== 1 ||
+        characters.length < SEARCH_JOINED_FALLBACK_MIN_LENGTH ||
+        characters.length > SEARCH_JOINED_FALLBACK_MAX_LENGTH ||
+        !/^\p{Script=Cyrillic}+$/u.test(title)) {
+        return undefined;
+    }
+    const splitIndex = Math.floor(characters.length / 2);
+    if (splitIndex < SEARCH_JOINED_FALLBACK_MIN_PART_LENGTH ||
+        characters.length - splitIndex < SEARCH_JOINED_FALLBACK_MIN_PART_LENGTH) {
+        return undefined;
+    }
+    return {
+        ...query,
+        title: `${characters.slice(0, splitIndex).join("")} ${characters.slice(splitIndex).join("")}`,
+    };
+}
+// Adds fallback discoveries without duplicating the same provider item and its attribution.
+// Добавляет fallback-результаты без дублирования item и атрибуции одного провайдера.
+function appendUniqueSearchResults(target, candidates) {
+    for (const candidate of candidates) {
+        const isDuplicate = target.some((existing) => existing.provider === candidate.provider &&
+            existing.item.type === candidate.item.type &&
+            existing.item.id === candidate.item.id);
+        if (!isDuplicate) {
+            target.push(candidate);
+        }
+    }
+}
+// Expands broad short queries more because final ranking needs enough cross-provider candidates.
+// Расширяет короткие широкие запросы сильнее, потому что финальному ranking нужны кандидаты разных провайдеров.
+function getProviderSearchLimit(query) {
+    if (isBroadShortTitleSearch(query)) {
+        return Math.min(MAX_PROVIDER_SEARCH_LIMIT, Math.max(query.limit * 10, 50));
+    }
+    return Math.min(MAX_PROVIDER_SEARCH_LIMIT, Math.max(query.limit * 5, 10));
+}
+// Detects searches like "one" or "game" where popular canonical results may be deeper.
+// Определяет поиски вроде "one" или "game", где популярные канонические результаты могут быть глубже.
+function isBroadShortTitleSearch(query) {
+    if (query.type || hasExternalIds(query.ids)) {
+        return false;
+    }
+    const normalizedTitle = query.title?.trim().replace(/\s+/g, " ") ?? "";
+    return (normalizedTitle.length > 0 && normalizedTitle.length <= 4 && !normalizedTitle.includes(" "));
+}
+// Calls one search provider and returns normalized timing/failure metadata.
+// Вызывает один search-провайдер и возвращает нормализованные timing/failure метаданные.
+async function callTimedProviderSearch(provider, query, context) {
+    const startedAt = Date.now();
+    try {
+        const results = await callProviderSearch(provider, query, context);
+        return {
+            provider: provider.name,
+            timing: {
+                provider: provider.name,
+                status: "success",
+                tookMs: elapsedSince(startedAt),
+            },
+            results,
+        };
+    }
+    catch (error) {
+        return {
+            provider: provider.name,
+            timing: {
+                provider: provider.name,
+                status: "failed",
+                tookMs: elapsedSince(startedAt),
+            },
+            results: [],
+            failure: toProviderFailure(provider.name, error),
+        };
+    }
+}
+// Calls one details provider and returns normalized timing/failure metadata.
+// Вызывает один details-провайдер и возвращает нормализованные timing/failure метаданные.
+async function callTimedProviderDetails(provider, query, context) {
+    const startedAt = Date.now();
+    try {
+        const result = await callProviderDetails(provider, query, context);
+        return {
+            provider: provider.name,
+            timing: {
+                provider: provider.name,
+                status: "success",
+                tookMs: elapsedSince(startedAt),
+            },
+            result,
+        };
+    }
+    catch (error) {
+        return {
+            provider: provider.name,
+            timing: {
+                provider: provider.name,
+                status: "failed",
+                tookMs: elapsedSince(startedAt),
+            },
+            result: null,
+            failure: toProviderFailure(provider.name, error),
+        };
+    }
+}
+// Calls one streaming provider and returns normalized timing/failure metadata.
+// Вызывает один streaming-провайдер и возвращает нормализованные timing/failure метаданные.
+async function callTimedProviderAvailability(provider, query, context) {
+    const startedAt = Date.now();
+    try {
+        const result = await callProviderAvailability(provider, query, context);
+        return {
+            provider: provider.name,
+            timing: {
+                provider: provider.name,
+                status: "success",
+                tookMs: elapsedSince(startedAt),
+            },
+            result,
+        };
+    }
+    catch (error) {
+        return {
+            provider: provider.name,
+            timing: {
+                provider: provider.name,
+                status: "failed",
+                tookMs: elapsedSince(startedAt),
+            },
+            result: null,
+            failure: toProviderFailure(provider.name, error),
+        };
+    }
+}
+// Calls one provider search method with timeout and abort signal support.
+// Вызывает search одного провайдера с поддержкой timeout и abort signal.
+async function callProviderSearch(provider, query, context) {
+    return withProviderTimeout(provider.name, context, (controller) => provider.search(query, {
+        signal: controller.signal,
+        timeoutMs: context.timeoutMs,
+        debug: context.debug,
+        language: context.language,
+    }));
+}
+// Calls one provider details method with timeout and abort signal support.
+// Вызывает getDetails одного провайдера с поддержкой timeout и abort signal.
+async function callProviderDetails(provider, query, context) {
+    if (!provider.getDetails) {
+        return null;
+    }
+    return withProviderTimeout(provider.name, context, (controller) => provider.getDetails(query, {
+        signal: controller.signal,
+        timeoutMs: context.timeoutMs,
+        debug: context.debug,
+        language: context.language,
+    }));
+}
+// Calls one streaming provider with timeout and abort signal support.
+// Вызывает один streaming-провайдер с поддержкой timeout и abort signal.
+async function callProviderAvailability(provider, query, context) {
+    return withProviderTimeout(provider.name, context, (controller) => provider.getAvailability(query, {
+        signal: controller.signal,
+        timeoutMs: context.timeoutMs,
+        debug: context.debug,
+        language: context.language,
+    }));
+}
+// Merges availability results without hiding provider attribution.
+// Объединяет availability-результаты, не скрывая атрибуцию провайдеров.
+function mergeAvailabilityResults(query, results) {
+    return {
+        query,
+        item: results.find((result) => result.item)?.item,
+        episodes: mergeEpisodeAvailability(results),
+        options: uniqueBy(results.flatMap((result) => result.options), (option) => `${option.provider}:${option.id}`),
+        sourceProviders: uniqueBy(results.flatMap((result) => result.sourceProviders), (source) => createStreamingSourceKey(source)),
+        checkedAt: new Date().toISOString(),
+    };
+}
+// Merges episode-level availability blocks by episode identity.
+// Объединяет episode-level availability блоки по идентичности эпизода.
+function mergeEpisodeAvailability(results) {
+    const episodesByKey = new Map();
+    for (const episode of results.flatMap((result) => [
+        ...(result.episodes ?? []),
+        ...createEpisodeAvailabilityFromOptions(result.options),
+    ])) {
+        const key = createEpisodeKey(episode);
+        const existing = episodesByKey.get(key);
+        if (!existing) {
+            episodesByKey.set(key, {
+                seasonNumber: episode.seasonNumber,
+                episodeNumber: episode.episodeNumber,
+                absoluteEpisodeNumber: episode.absoluteEpisodeNumber,
+                title: episode.title,
+                options: uniqueBy(episode.options, (option) => `${option.provider}:${option.id}`),
+            });
+            continue;
+        }
+        existing.options = uniqueBy([...existing.options, ...episode.options], (option) => `${option.provider}:${option.id}`);
+        existing.title ??= episode.title;
+    }
+    return episodesByKey.size > 0 ? [...episodesByKey.values()] : undefined;
+}
+// Creates episode blocks from top-level options that carry episode identity.
+// Создает episode blocks из top-level options, которые содержат идентичность эпизода.
+function createEpisodeAvailabilityFromOptions(options) {
+    return options
+        .filter((option) => option.episode)
+        .map((option) => ({
+        seasonNumber: option.episode?.seasonNumber,
+        episodeNumber: option.episode?.episodeNumber,
+        absoluteEpisodeNumber: option.episode?.absoluteEpisodeNumber,
+        options: [option],
+    }));
+}
+// Wraps a provider promise with configured timeout behavior.
+// Оборачивает promise провайдера настроенным timeout-поведением.
+async function withProviderTimeout(providerName, context, run) {
+    const controller = new AbortController();
+    let timeout;
+    try {
+        const providerPromise = run(controller);
+        if (context.timeoutMs === undefined) {
+            return await providerPromise;
+        }
+        const timeoutPromise = new Promise((_, reject) => {
+            const timeoutError = new ProviderError({
+                provider: providerName,
+                code: "PROVIDER_TIMEOUT",
+                message: `Provider "${providerName}" timed out.`,
+                retryable: true,
+            });
+            if (context.timeoutMs <= 0) {
+                controller.abort(timeoutError);
+                reject(timeoutError);
+                return;
+            }
+            timeout = setTimeout(() => {
+                controller.abort(timeoutError);
+                reject(timeoutError);
+            }, context.timeoutMs);
+        });
+        return await Promise.race([providerPromise, timeoutPromise]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
+// Creates public response metadata for a search call.
+// Создает публичные метаданные ответа для search-вызова.
+function createResponseMeta(input) {
+    return {
+        providers: {
+            requested: input.requested,
+            successful: input.successful,
+            failed: input.failed,
+        },
+        cached: input.cached,
+        tookMs: input.tookMs,
+        warnings: input.warnings.length > 0 ? input.warnings : undefined,
+        debug: input.debug
+            ? {
+                providers: input.requested,
+                timings: input.timings ?? [],
+            }
+            : undefined,
+    };
+}
+// Creates a stable cache key for a normalized search query.
+// Создает стабильный cache key для нормализованного search query.
+function createSearchCacheKey(query) {
+    return `search:${JSON.stringify(sortObject(query))}`;
+}
+// Creates a stable cache key for a normalized details query.
+// Создает стабильный cache key для нормализованного details query.
+function createDetailsCacheKey(query) {
+    return `details:${JSON.stringify(sortObject(query))}`;
+}
+// Creates a stable cache key for a normalized streaming query.
+// Создает стабильный cache key для нормализованного streaming query.
+function createAvailabilityCacheKey(query) {
+    return `availability:${JSON.stringify(sortObject(query))}`;
+}
+// Keeps cached direct links from outliving the earliest advertised expiration.
+// Не позволяет кешированным прямым ссылкам пережить ближайший заявленный срок действия.
+function createAvailabilityCacheOptions(availability) {
+    const expiresAtValues = [
+        ...availability.options,
+        ...(availability.episodes?.flatMap((episode) => episode.options) ?? []),
+    ]
+        .map((option) => option.expiresAt)
+        .filter((value) => value !== undefined)
+        .map((value) => Date.parse(value))
+        .filter(Number.isFinite);
+    if (expiresAtValues.length === 0) {
+        return undefined;
+    }
+    const earliestExpiration = Math.min(...expiresAtValues);
+    return {
+        ttlMs: Math.max(0, earliestExpiration - Date.now() - EXPIRING_AVAILABILITY_CACHE_SAFETY_MS),
+    };
+}
+// Checks whether an external ID object contains at least one ID.
+// Проверяет, содержит ли объект внешних ID хотя бы один ID.
+function hasExternalIds(ids) {
+    return Boolean(ids && Object.values(ids).some((value) => Boolean(value)));
+}
+// Checks whether two normalized media identities share at least one exact external ID.
+// Проверяет, совпадает ли у двух нормализованных media identity хотя бы один внешний ID.
+function hasSharedExternalId(left, right) {
+    if (!left || !right) {
+        return false;
+    }
+    return EXTERNAL_ID_SHORTCUTS.some((key) => Boolean(left[key] && left[key] === right[key]));
+}
+// Checks whether query ids overlap provider-supported external ID sources.
+// Проверяет, пересекаются ли query ids с поддерживаемыми провайдером источниками ID.
+function hasSupportedExternalId(ids, supportedSources) {
+    return Boolean(ids && supportedSources.some((source) => Boolean(ids[source])));
+}
+// Checks whether query targets a concrete episode.
+// Проверяет, нацелен ли query на конкретный эпизод.
+function hasEpisodeQuery(query) {
+    return (query.seasonNumber !== undefined ||
+        query.episodeNumber !== undefined ||
+        query.absoluteEpisodeNumber !== undefined);
+}
+// Creates a stable identity for an episode availability block.
+// Создает стабильную идентичность для блока доступности эпизода.
+function createEpisodeKey(episode) {
+    return [
+        episode.seasonNumber ?? "",
+        episode.episodeNumber ?? "",
+        episode.absoluteEpisodeNumber ?? "",
+    ].join(":");
+}
+// Creates a stable identity for provider source attribution.
+// Создает стабильную идентичность для атрибуции источника провайдера.
+function createStreamingSourceKey(source) {
+    return `${source.provider}:${source.url ?? ""}:${JSON.stringify(sortObject(source.ids ?? {}))}`;
+}
+// Keeps the first value for each derived key.
+// Оставляет первое значение для каждого вычисленного ключа.
+function uniqueBy(values, getKey) {
+    const seen = new Set();
+    const unique = [];
+    for (const value of values) {
+        const key = getKey(value);
+        if (!seen.has(key)) {
+            seen.add(key);
+            unique.push(value);
+        }
+    }
+    return unique;
+}
+// Returns elapsed milliseconds since a start timestamp.
+// Возвращает количество миллисекунд, прошедших с начального timestamp.
+function elapsedSince(startedAt) {
+    return Date.now() - startedAt;
+}
+// Sorts object keys recursively for deterministic JSON cache keys.
+// Рекурсивно сортирует ключи объекта для детерминированных JSON cache keys.
+function sortObject(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortObject);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entryValue]) => [key, sortObject(entryValue)]));
+    }
+    return value;
+}
+//# sourceMappingURL=engine.js.map