@media-engine/core 0.1.0 → 0.1.1

package/dist/engine/query.js

@@ -0,0 +1,241 @@
+import { MediaEngineError } from "../errors/index.js";
+// Top-level public external ID shortcuts supported by engine queries.
+// Верхнеуровневые публичные сокращения внешних ID, поддерживаемые query движка.
+export const EXTERNAL_ID_SHORTCUTS = [
+    "imdb",
+    "tmdb",
+    "kinopoisk",
+    "shikimori",
+    "myAnimeList",
+    "aniList",
+];
+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;
+// Normalizes top-level external ID shortcuts into the ids object.
+// Нормализует верхнеуровневые сокращения внешних ID в объект ids.
+export 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 не передал его явно.
+export 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.
+export 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.
+export function normalizeStreamQuery(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 = query[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 содержит хотя бы один поддерживаемый вход для поиска.
+export 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 содержит хотя бы один поддерживаемый вход для поиска.
+export 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 может определить медиа или эпизод.
+export 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.",
+    });
+}
+// Gives providers enough candidates so the engine can rank before applying the public limit.
+// Дает провайдерам достаточно кандидатов, чтобы движок ранжировал до применения публичного limit.
+export function createProviderSearchQuery(query) {
+    if (query.limit === undefined || query.limit === 0) {
+        return query;
+    }
+    return {
+        ...query,
+        limit: getProviderSearchLimit(query),
+    };
+}
+// Broadens an empty typo search or separates one likely joined compound title.
+// Расширяет пустой поиск с опечаткой или разделяет вероятно слитное составное название.
+export 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 и атрибуции одного провайдера.
+export 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);
+        }
+    }
+}
+// Creates a stable cache key for a normalized search query.
+// Создает стабильный cache key для нормализованного search query.
+export function createSearchCacheKey(query) {
+    return `search:${JSON.stringify(sortObject(query))}`;
+}
+// Creates a stable cache key for a normalized details query.
+// Создает стабильный cache key для нормализованного details query.
+export function createDetailsCacheKey(query) {
+    return `details:${JSON.stringify(sortObject(query))}`;
+}
+// Creates a stable cache key for a normalized streaming query.
+// Создает стабильный cache key для нормализованного streaming query.
+export function createAvailabilityCacheKey(query) {
+    return `availability:${JSON.stringify(sortObject(query))}`;
+}
+// Checks whether an external ID object contains at least one ID.
+// Проверяет, содержит ли объект внешних ID хотя бы один ID.
+export function hasExternalIds(ids) {
+    return Boolean(ids && Object.values(ids).some((value) => Boolean(value)));
+}
+// Sorts object keys recursively for deterministic JSON cache keys.
+// Рекурсивно сортирует ключи объекта для детерминированных JSON cache keys.
+export 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;
+}
+// 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(" "));
+}
+//# sourceMappingURL=query.js.map

package/dist/engine/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/engine/query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAMtD,sEAAsE;AACtE,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,MAAM;IACN,MAAM;IACN,WAAW;IACX,WAAW;IACX,aAAa;IACb,SAAS;CACD,CAAC;AAEX,MAAM,0BAA0B,GAAG,CAAC,CAAC;AACrC,MAAM,qCAAqC,GAAG,CAAC,CAAC;AAChD,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAC5C,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAC5C,MAAM,sCAAsC,GAAG,CAAC,CAAC;AACjD,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAEtC,kEAAkE;AAClE,kEAAkE;AAClE,MAAM,UAAU,oBAAoB,CAAC,KAAkB;IACrD,MAAM,GAAG,GAAgB,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;IAElD,KAAK,MAAM,GAAG,IAAI,qBAAqB,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAEzB,IAAI,KAAK,EAAE,CAAC;YACV,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,KAAK;QACR,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE;QAC1B,GAAG,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;KAC3C,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,+BAA+B,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7D,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,wEAAwE;AACxE,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,KAAmB;IACvD,MAAM,GAAG,GAAgB,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;IAElD,KAAK,MAAM,GAAG,IAAI,qBAAqB,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAEzB,IAAI,KAAK,EAAE,CAAC;YACV,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,KAAK;QACR,GAAG,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;KAC3C,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,gFAAgF;AAChF,MAAM,UAAU,oBAAoB,CAAC,KAAkB;IACrD,MAAM,GAAG,GAAgB,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;IAClD,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtF,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAExC,KAAK,MAAM,GAAG,IAAI,qBAAqB,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAEzB,IAAI,KAAK,EAAE,CAAC;YACV,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,KAAK;QACR,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE;QAC1B,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClC,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,KAAkB;IACpD,IACE,KAAK,CAAC,KAAK,KAAK,SAAS;QACzB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,gBAAgB,CAAC,EACrF,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,uDAAuD,gBAAgB,GAAG;SACpF,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,MAAM,IAAI,gBAAgB,CAAC;QACzB,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,kDAAkD;KAC5D,CAAC,CAAC;AACL,CAAC;AAED,0EAA0E;AAC1E,qFAAqF;AACrF,MAAM,UAAU,oBAAoB,CAAC,KAAmB;IACtD,IAAI,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO;IACT,CAAC;IAED,MAAM,IAAI,gBAAgB,CAAC;QACzB,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,gDAAgD;KAC1D,CAAC,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,oEAAoE;AACpE,MAAM,UAAU,mBAAmB,CAAC,KAAkB;IACpD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,gCAAgC;SAC1C,CAAC,CAAC;IACL,CAAC;IAED,IACE,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,qBAAqB,CAAC,CAAC,IAAI,CACrF,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAC1E,EACD,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,4DAA4D;SACtE,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,MAAM,IAAI,gBAAgB,CAAC;QACzB,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,kDAAkD;KAC5D,CAAC,CAAC;AACL,CAAC;AAED,6FAA6F;AAC7F,kGAAkG;AAClG,MAAM,UAAU,yBAAyB,CAAC,KAAkB;IAC1D,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO;QACL,GAAG,KAAK;QACR,KAAK,EAAE,sBAAsB,CAAC,KAAK,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,wFAAwF;AACxF,MAAM,UAAU,yBAAyB,CAAC,KAAkB;IAC1D,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhC,IACE,MAAM,CAAC,MAAM,IAAI,0BAA0B;QAC3C,SAAS;QACT,SAAS,CAAC,MAAM,IAAI,qCAAqC,EACzD,CAAC;QACD,OAAO;YACL,GAAG,KAAK;YACR,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;SACrC,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAE9B,IACE,MAAM,CAAC,MAAM,KAAK,CAAC;QACnB,UAAU,CAAC,MAAM,GAAG,iCAAiC;QACrD,UAAU,CAAC,MAAM,GAAG,iCAAiC;QACrD,CAAC,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,EACtC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAErD,IACE,UAAU,GAAG,sCAAsC;QACnD,UAAU,CAAC,MAAM,GAAG,UAAU,GAAG,sCAAsC,EACvE,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO;QACL,GAAG,KAAK;QACR,KAAK,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;KAC9F,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,qFAAqF;AACrF,MAAM,UAAU,yBAAyB,CACvC,MAA8B,EAC9B,UAAkC;IAElC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAC7B,CAAC,QAAQ,EAAE,EAAE,CACX,QAAQ,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ;YACxC,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,CAAC,IAAI;YAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,IAAI,CAAC,EAAE,CACzC,CAAC;QAEF,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;AACH,CAAC;AAED,4DAA4D;AAC5D,kEAAkE;AAClE,MAAM,UAAU,oBAAoB,CAAC,KAAkB;IACrD,OAAO,UAAU,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,6DAA6D;AAC7D,mEAAmE;AACnE,MAAM,UAAU,qBAAqB,CAAC,KAAmB;IACvD,OAAO,WAAW,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;AACxD,CAAC;AAED,+DAA+D;AAC/D,qEAAqE;AACrE,MAAM,UAAU,0BAA0B,CAAC,KAAkB;IAC3D,OAAO,gBAAgB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,iEAAiE;AACjE,4DAA4D;AAC5D,MAAM,UAAU,cAAc,CAAC,GAA4B;IACzD,OAAO,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,mEAAmE;AACnE,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;aAClB,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC;aACpD,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;aACpD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAC7D,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iGAAiG;AACjG,gHAAgH;AAChH,SAAS,sBAAsB,CAAC,KAAkB;IAChD,IAAI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,GAAG,CAAC,yBAAyB,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAM,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,yBAAyB,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAM,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,uFAAuF;AACvF,sGAAsG;AACtG,SAAS,uBAAuB,CAAC,KAAkB;IACjD,IAAI,KAAK,CAAC,IAAI,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,eAAe,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;IAEvE,OAAO,CACL,eAAe,CAAC,MAAM,GAAG,CAAC,IAAI,eAAe,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC,CAC5F,CAAC;AACJ,CAAC"}

package/dist/engine/response-meta.d.ts

@@ -0,0 +1,13 @@
+import type { EngineWarning, ProviderFailure, ProviderTimingMeta, ResponseMeta } from "../response/index.js";
+export interface ResponseMetaInput {
+    requested: string[];
+    successful: string[];
+    failed: ProviderFailure[];
+    warnings: EngineWarning[];
+    cached: boolean;
+    tookMs: number;
+    debug: boolean;
+    timings?: ProviderTimingMeta[];
+}
+export declare function createResponseMeta(input: ResponseMetaInput): ResponseMeta;
+export declare function elapsedSince(startedAt: number): number;

package/dist/engine/response-meta.js

@@ -0,0 +1,26 @@
+// Creates public response metadata for engine calls.
+// Создает публичные метаданные ответа для вызовов engine.
+export 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,
+    };
+}
+// Returns elapsed milliseconds since a start timestamp.
+// Возвращает количество миллисекунд, прошедших с начального timestamp.
+export function elapsedSince(startedAt) {
+    return Date.now() - startedAt;
+}
+//# sourceMappingURL=response-meta.js.map

package/dist/engine/response-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-meta.js","sourceRoot":"","sources":["../../src/engine/response-meta.ts"],"names":[],"mappings":"AAoBA,qDAAqD;AACrD,0DAA0D;AAC1D,MAAM,UAAU,kBAAkB,CAAC,KAAwB;IACzD,OAAO;QACL,SAAS,EAAE;YACT,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB;QACD,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QAChE,KAAK,EAAE,KAAK,CAAC,KAAK;YAChB,CAAC,CAAC;gBACE,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;aAC7B;YACH,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;AAChC,CAAC"}

package/dist/engine/runtime.d.ts

@@ -0,0 +1,3 @@
+import type { StreamingProvider } from "../streaming/index.js";
+export declare function validateStreamingProviders(providers: StreamingProvider[]): StreamingProvider[];
+export declare function resolveProviderTimeoutMs(providerName: string, timeoutMs: number | undefined, providerTimeouts: Readonly<Record<string, number>>): number | undefined;

package/dist/engine/runtime.js

@@ -0,0 +1,29 @@
+// Validates streaming providers and rejects duplicate public names.
+// Проверяет streaming-провайдеры и отклоняет дубли публичных имен.
+export 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];
+}
+// Resolves a provider override without allowing it to exceed the global boundary.
+// Выбирает override провайдера, не позволяя ему превысить глобальную границу.
+export function resolveProviderTimeoutMs(providerName, timeoutMs, providerTimeouts) {
+    const providerTimeoutMs = providerTimeouts[providerName];
+    if (providerTimeoutMs === undefined) {
+        return timeoutMs;
+    }
+    return timeoutMs === undefined ? providerTimeoutMs : Math.min(timeoutMs, providerTimeoutMs);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/engine/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/engine/runtime.ts"],"names":[],"mappings":"AAEA,oEAAoE;AACpE,mEAAmE;AACnE,MAAM,UAAU,0BAA0B,CAAC,SAA8B;IACvE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAElC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;QAED,IAAI,IAAI,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,4BAA4B,QAAQ,CAAC,IAAI,oDAAoD,CAC9F,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,0BAA0B,CAAC,CAAC;QACzE,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;AACxB,CAAC;AAED,kFAAkF;AAClF,8EAA8E;AAC9E,MAAM,UAAU,wBAAwB,CACtC,YAAoB,EACpB,SAA6B,EAC7B,gBAAkD;IAElD,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAEzD,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;AAC9F,CAAC"}

package/dist/engine/search-enrichment.d.ts

@@ -0,0 +1,28 @@
+import type { ExternalIds, Image } from "../media/index.js";
+import type { MergeStrategy } from "../merge/index.js";
+import type { ProviderRegistry } from "../providers/index.js";
+import type { MediaSearchResult } from "../search/index.js";
+import type { ProviderCircuitBreaker } from "./circuit-breaker.js";
+import type { ProviderConcurrencyLimiter } from "./concurrency-limiter.js";
+export interface SearchPosterLookupInput {
+    result: MediaSearchResult;
+    language: string | undefined;
+    excludedProviders: ReadonlySet<string>;
+    registry: ProviderRegistry;
+    mergeStrategy: MergeStrategy;
+    debug: boolean;
+    circuitBreaker?: ProviderCircuitBreaker | undefined;
+    concurrencyLimiter?: ProviderConcurrencyLimiter | undefined;
+    getProviderTimeoutMs(providerName: string): number | undefined;
+}
+export interface SearchPosterEnrichment {
+    ids: ExternalIds | undefined;
+    poster: Image | undefined;
+}
+export declare function needsSearchEnrichment(item: {
+    ratings?: unknown[];
+    description?: string;
+    poster?: unknown;
+}): boolean;
+export declare function loadSearchPoster(input: SearchPosterLookupInput): Promise<Image | undefined>;
+export declare function applySearchPosterEnrichments(results: MediaSearchResult[], enrichments: SearchPosterEnrichment[]): MediaSearchResult[];

package/dist/engine/search-enrichment.js

@@ -0,0 +1,90 @@
+import { callTimedProviderDetails } from "./provider-calls.js";
+import { EXTERNAL_ID_SHORTCUTS, hasExternalIds } from "./query.js";
+const SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS = 1_500;
+// Enriches compact catalog hits when follow-up cards would otherwise choose different metadata.
+// Обогащает compact catalog hits, чтобы search и details не выбирали разные metadata.
+export function needsSearchEnrichment(item) {
+    return !item.ratings?.length || !item.description?.trim() || !item.poster;
+}
+// Loads only the canonical poster needed by search without blocking on a full details request.
+// Загружает только канонический постер для search, не блокируя полный details-запрос.
+export async function loadSearchPoster(input) {
+    if (!hasExternalIds(input.result.item.ids)) {
+        return undefined;
+    }
+    const query = {
+        type: input.result.item.type,
+        ids: input.result.item.ids,
+        language: input.language,
+    };
+    const searchProviders = new Set(input.result.sources.map((source) => source.provider));
+    const providers = input.registry
+        .selectDetailsProviders(query)
+        .filter((provider) => !input.excludedProviders.has(provider.name));
+    const reusablePosterProvider = providers.find((provider) => provider.searchPosterMatchesDetails === true &&
+        provider.name === input.result.item.poster?.source &&
+        searchProviders.has(provider.name));
+    const providersToLoad = reusablePosterProvider
+        ? providers.filter((provider) => provider.searchPosterMatchesDetails !== true || !searchProviders.has(provider.name))
+        : providers;
+    const outcomes = await Promise.all(providersToLoad.map((provider) => {
+        const providerTimeoutMs = input.getProviderTimeoutMs(provider.name);
+        return callTimedProviderDetails(provider, query, {
+            debug: input.debug,
+            language: input.language,
+            circuitBreaker: input.circuitBreaker,
+            concurrencyLimiter: input.concurrencyLimiter,
+            timeoutMs: providerTimeoutMs === undefined
+                ? SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS
+                : Math.min(providerTimeoutMs, SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS),
+        });
+    }));
+    const loadedResults = new Map(outcomes.flatMap((outcome) => outcome.failure || !outcome.result ? [] : [[outcome.provider, outcome.result]]));
+    const providerResults = providers.flatMap((provider) => {
+        if (provider.name === reusablePosterProvider?.name) {
+            return [
+                {
+                    provider: reusablePosterProvider.name,
+                    details: searchItemAsDetails(input.result.item),
+                },
+            ];
+        }
+        const loaded = loadedResults.get(provider.name);
+        return loaded ? [loaded] : [];
+    });
+    return input.mergeStrategy.mergeDetails(providerResults, {
+        query,
+        language: input.language,
+        debug: input.debug,
+        warnings: [],
+    })?.poster;
+}
+// Reuses only compact fields; every details-only field remains absent by construction.
+// Переиспользует только compact-поля; details-only поля намеренно остаются пустыми.
+function searchItemAsDetails(item) {
+    switch (item.type) {
+        case "movie":
+            return { ...item, type: "movie" };
+        case "series":
+            return { ...item, type: "series" };
+        case "anime":
+            return { ...item, type: "anime" };
+    }
+}
+// Applies canonical poster enrichments to matching search results.
+// Применяет canonical poster enrichment к совпадающим search results.
+export function applySearchPosterEnrichments(results, enrichments) {
+    return results.map((result) => {
+        const poster = enrichments.find((enrichment) => enrichment.poster && hasSharedExternalId(result.item.ids, enrichment.ids))?.poster;
+        return poster ? { ...result, item: { ...result.item, poster } } : result;
+    });
+}
+// 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]));
+}
+//# sourceMappingURL=search-enrichment.js.map

package/dist/engine/search-enrichment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-enrichment.js","sourceRoot":"","sources":["../../src/engine/search-enrichment.ts"],"names":[],"mappings":"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"}

package/dist/engine/stale-fallback.d.ts

@@ -0,0 +1,11 @@
+import type { ResponseMeta } from "../response/index.js";
+interface ResponseWithMeta {
+    meta: ResponseMeta;
+}
+export interface StaleFallbackInput<T extends ResponseWithMeta> {
+    stale: T | undefined;
+    pending: Promise<T>;
+    tookMs: () => number;
+}
+export declare function loadWithStaleFallback<T extends ResponseWithMeta>(input: StaleFallbackInput<T>): Promise<T>;
+export {};

package/dist/engine/stale-fallback.js

@@ -0,0 +1,60 @@
+import { MediaEngineError } from "../errors/index.js";
+// Returns stale metadata only when every current provider failure is retryable.
+// Возвращает устаревшие метаданные только при retryable-сбое всех текущих провайдеров.
+export async function loadWithStaleFallback(input) {
+    try {
+        return await input.pending;
+    }
+    catch (error) {
+        const failed = getRetryableProviderFailures(error);
+        if (!input.stale || !failed) {
+            throw error;
+        }
+        const response = structuredClone(input.stale);
+        response.meta = {
+            providers: {
+                requested: failed.map((failure) => failure.provider),
+                successful: [],
+                failed,
+            },
+            cached: true,
+            stale: true,
+            tookMs: input.tookMs(),
+            warnings: [
+                {
+                    code: "STALE_CACHE_FALLBACK",
+                    message: "Returned stale cached data because all selected providers failed retryably.",
+                },
+            ],
+            debug: response.meta.debug
+                ? {
+                    providers: failed.map((failure) => failure.provider),
+                    timings: [],
+                }
+                : undefined,
+        };
+        return response;
+    }
+}
+function getRetryableProviderFailures(error) {
+    if (!(error instanceof MediaEngineError) || error.code !== "PROVIDER_ERROR") {
+        return undefined;
+    }
+    const cause = error.cause;
+    const failed = cause?.failed;
+    if (!Array.isArray(failed) || failed.length === 0 || !failed.every(isRetryableProviderFailure)) {
+        return undefined;
+    }
+    return failed;
+}
+function isRetryableProviderFailure(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const failure = value;
+    return (typeof failure.provider === "string" &&
+        typeof failure.code === "string" &&
+        failure.retryable === true &&
+        typeof failure.message === "string");
+}
+//# sourceMappingURL=stale-fallback.js.map

package/dist/engine/stale-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-fallback.js","sourceRoot":"","sources":["../../src/engine/stale-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAatD,gFAAgF;AAChF,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAA4B;IAE5B,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,CAAC,OAAO,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,4BAA4B,CAAC,KAAK,CAAC,CAAC;QAEnD,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,MAAM,KAAK,CAAC;QACd,CAAC;QAED,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9C,QAAQ,CAAC,IAAI,GAAG;YACd,SAAS,EAAE;gBACT,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;gBACpD,UAAU,EAAE,EAAE;gBACd,MAAM;aACP;YACD,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE;YACtB,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,sBAAsB;oBAC5B,OAAO,EAAE,6EAA6E;iBACvF;aACF;YACD,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK;gBACxB,CAAC,CAAC;oBACE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;oBACpD,OAAO,EAAE,EAAE;iBACZ;gBACH,CAAC,CAAC,SAAS;SACd,CAAC;QAEF,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED,SAAS,4BAA4B,CAAC,KAAc;IAClD,IAAI,CAAC,CAAC,KAAK,YAAY,gBAAgB,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;QAC5E,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAyC,CAAC;IAC9D,MAAM,MAAM,GAAG,KAAK,EAAE,MAAM,CAAC;IAE7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,EAAE,CAAC;QAC/F,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,0BAA0B,CAAC,KAAc;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,KAAiC,CAAC;IAClD,OAAO,CACL,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;QACpC,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAChC,OAAO,CAAC,SAAS,KAAK,IAAI;QAC1B,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CACpC,CAAC;AACJ,CAAC"}

package/dist/engine/timeout-budget.d.ts

@@ -0,0 +1,7 @@
+export declare class ProviderTimeoutBudget {
+    private readonly resolveTimeoutMs;
+    private readonly now;
+    private readonly deadlines;
+    constructor(resolveTimeoutMs: (provider: string) => number | undefined, now?: () => number);
+    getRemainingMs(provider: string, callLimitMs?: number): number | undefined;
+}

package/dist/engine/timeout-budget.js

@@ -0,0 +1,31 @@
+// Shares one timeout deadline across all calls to a provider in one engine operation.
+// Делит один timeout deadline между всеми вызовами провайдера в одной операции движка.
+export class ProviderTimeoutBudget {
+    resolveTimeoutMs;
+    now;
+    deadlines = new Map();
+    constructor(resolveTimeoutMs, now = Date.now) {
+        this.resolveTimeoutMs = resolveTimeoutMs;
+        this.now = now;
+    }
+    getRemainingMs(provider, callLimitMs) {
+        const now = this.now();
+        const existingDeadline = this.deadlines.get(provider);
+        if (existingDeadline !== undefined) {
+            return applyCallLimit(Math.max(0, existingDeadline - now), callLimitMs);
+        }
+        const timeoutMs = this.resolveTimeoutMs(provider);
+        const initialBudget = applyCallLimit(timeoutMs, callLimitMs);
+        if (initialBudget !== undefined) {
+            this.deadlines.set(provider, now + initialBudget);
+        }
+        return initialBudget;
+    }
+}
+function applyCallLimit(timeoutMs, callLimitMs) {
+    if (timeoutMs === undefined) {
+        return callLimitMs;
+    }
+    return callLimitMs === undefined ? timeoutMs : Math.min(timeoutMs, callLimitMs);
+}
+//# sourceMappingURL=timeout-budget.js.map

package/dist/engine/timeout-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout-budget.js","sourceRoot":"","sources":["../../src/engine/timeout-budget.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,uFAAuF;AACvF,MAAM,OAAO,qBAAqB;IAIb;IACA;IAJF,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEvD,YACmB,gBAA0D,EAC1D,MAAoB,IAAI,CAAC,GAAG;QAD5B,qBAAgB,GAAhB,gBAAgB,CAA0C;QAC1D,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,cAAc,CAAC,QAAgB,EAAE,WAAoB;QACnD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEtD,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACnC,OAAO,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,gBAAgB,GAAG,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;QAC1E,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAClD,MAAM,aAAa,GAAG,cAAc,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAE7D,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,GAAG,aAAa,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,aAAa,CAAC;IACvB,CAAC;CACF;AAED,SAAS,cAAc,CACrB,SAA6B,EAC7B,WAA+B;IAE/B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,OAAO,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAClF,CAAC"}

package/dist/engine/types.d.ts

@@ -2,6 +2,34 @@ import type { Cache } from "../cache/index.js";
 import type { MergeStrategy } from "../merge/index.js";
 import type { MediaProvider } from "../providers/index.js";
 import type { StreamingProvider } from "../streaming/index.js";
+export interface CircuitBreakerOptions {
+    failureThreshold?: number;
+    recoveryTimeoutMs?: number;
+}
+export interface ProviderConcurrencyOptions {
+    defaultMaxConcurrent?: number;
+    maxQueueSize?: number;
+    providerLimits?: Readonly<Record<string, number>>;
+}
+export interface ProviderHealthStatus {
+    provider: string;
+    kind: "metadata" | "streaming";
+    circuitState: "closed" | "open" | "half-open" | "disabled";
+    consecutiveFailures: number;
+    totalRequests: number;
+    totalSuccesses: number;
+    totalFailures: number;
+    lastSuccessAt?: string;
+    lastFailureAt?: string;
+    lastFailureCode?: string;
+    failureCounts?: {
+        timeout: number;
+        rateLimited: number;
+        unavailable: number;
+        other: number;
+    };
+    retryAfterMs?: number;
+}
 export interface MediaEngineOptions {
     providers?: MediaProvider[];
     streamingProviders?: StreamingProvider[];
@@ -9,5 +37,7 @@ export interface MediaEngineOptions {
     mergeStrategy?: MergeStrategy;
     timeoutMs?: number;
     providerTimeouts?: Readonly<Record<string, number>>;
+    circuitBreaker?: CircuitBreakerOptions | false;
+    providerConcurrency?: ProviderConcurrencyOptions | false;
     debug?: boolean;
 }

package/dist/merge/details-identity.d.ts

@@ -0,0 +1,5 @@
+import type { MediaType } from "../media/index.js";
+import type { DetailsEntry } from "./internal.js";
+import type { MergeContext } from "./types.js";
+export declare function filterDetailsEntriesByIdentity(entries: DetailsEntry[], context: MergeContext): DetailsEntry[];
+export declare function warnDetailsTypeConflicts(entries: DetailsEntry[], context: MergeContext, selectedType?: MediaType): void;