@media-engine/core 0.1.0 → 1.0.0

package/dist/engine/types.d.ts

@@ -2,12 +2,47 @@ 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";
+import type { TorrentProvider } from "../torrent/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" | "torrent";
+    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 MediaEngineOperationOptions {
+    signal?: AbortSignal;
+}
 export interface MediaEngineOptions {
     providers?: MediaProvider[];
     streamingProviders?: StreamingProvider[];
+    torrentProviders?: TorrentProvider[];
     cache?: Cache;
     mergeStrategy?: MergeStrategy;
     timeoutMs?: number;
     providerTimeouts?: Readonly<Record<string, number>>;
+    circuitBreaker?: CircuitBreakerOptions | false;
+    providerConcurrency?: ProviderConcurrencyOptions | false;
     debug?: boolean;
 }

package/dist/errors/types.d.ts

@@ -1,6 +1,6 @@
 import type { ProviderFailure } from "../response/types.js";
 export type ErrorCode = "INVALID_QUERY" | "PROVIDER_ERROR" | "UNKNOWN_ERROR";
-export type ProviderErrorCode = "PROVIDER_ERROR" | "PROVIDER_TIMEOUT" | "PROVIDER_UNAUTHORIZED" | "PROVIDER_RATE_LIMITED" | "PROVIDER_UNAVAILABLE" | "PROVIDER_INVALID_RESPONSE" | "PROVIDER_NOT_SUPPORTED";
+export type ProviderErrorCode = "PROVIDER_ERROR" | "PROVIDER_TIMEOUT" | "PROVIDER_UNAUTHORIZED" | "PROVIDER_RATE_LIMITED" | "PROVIDER_UNAVAILABLE" | "PROVIDER_INVALID_RESPONSE" | "PROVIDER_RESPONSE_TOO_LARGE" | "PROVIDER_NOT_SUPPORTED";
 export interface ProviderErrorOptions {
     provider: string;
     code: ProviderErrorCode;

package/dist/errors/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/errors/types.ts"],"names":[],"mappings":"AAmCA,kEAAkE;AAClE,wDAAwD;AACxD,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAY;IAEzB,YAAY,OAAgC;QAC1C,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAEjD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAED,qFAAqF;AACrF,4EAA4E;AAC5E,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,QAAQ,CAAS;IACjB,IAAI,CAAoB;IACxB,SAAS,CAAU;IAE5B,YAAY,OAA6B;QACvC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAEjD,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC9C,CAAC;CACF;AAED,kEAAkE;AAClE,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,OAAO,IAAI,gBAAgB,CAAC;YAC1B,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,gBAAgB,CAAC;YAC1B,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,gBAAgB,CAAC;QAC1B,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,eAAe;QACxB,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC;AAED,oEAAoE;AACpE,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,KAAc;IAChE,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,OAAO;YACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO;YACL,QAAQ;YACR,IAAI,EAAE,gBAAgB;YACtB,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ;QACR,IAAI,EAAE,gBAAgB;QACtB,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,wBAAwB;KAClC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/errors/types.ts"],"names":[],"mappings":"AAoCA,kEAAkE;AAClE,wDAAwD;AACxD,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAY;IAEzB,YAAY,OAAgC;QAC1C,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAEjD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAED,qFAAqF;AACrF,4EAA4E;AAC5E,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,QAAQ,CAAS;IACjB,IAAI,CAAoB;IACxB,SAAS,CAAU;IAE5B,YAAY,OAA6B;QACvC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAEjD,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC9C,CAAC;CACF;AAED,kEAAkE;AAClE,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,OAAO,IAAI,gBAAgB,CAAC;YAC1B,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,gBAAgB,CAAC;YAC1B,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,gBAAgB,CAAC;QAC1B,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,eAAe;QACxB,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC;AAED,oEAAoE;AACpE,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,KAAc;IAChE,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,OAAO;YACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO;YACL,QAAQ;YACR,IAAI,EAAE,gBAAgB;YACtB,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ;QACR,IAAI,EAAE,gBAAgB;QACtB,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,wBAAwB;KAClC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-export declare const MEDIA_ENGINE_CORE_VERSION = "0.1.0";
+export declare const MEDIA_ENGINE_CORE_VERSION = "1.0.0";
 export type * from "./media/index.js";
 export type * from "./search/index.js";
 export type * from "./details/index.js";
 export type * from "./response/index.js";
 export type * from "./providers/index.js";
 export type * from "./streaming/index.js";
+export type * from "./torrent/index.js";
 export * from "./merge/index.js";
 export * from "./cache/index.js";
 export * from "./engine/index.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const MEDIA_ENGINE_CORE_VERSION = "0.1.0";
+export const MEDIA_ENGINE_CORE_VERSION = "1.0.0";
 export * from "./merge/index.js";
 export * from "./cache/index.js";
 export * from "./engine/index.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAQjD,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AASjD,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/media/types.d.ts

@@ -17,7 +17,7 @@ export interface Image {
     language?: string;
     source?: string;
 }
-export type RatingSource = "imdb" | "tmdb" | "kinopoisk" | "shikimori" | "myAnimeList" | "aniList" | "internal";
+export type RatingSource = "imdb" | "tmdb" | "kinopoisk" | "shikimori" | "myAnimeList" | "aniList" | "tvmaze" | "internal";
 export interface Rating {
     source: RatingSource;
     value: number;

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;

package/dist/merge/details-identity.js

@@ -0,0 +1,63 @@
+import { hasSharedStrongId, strongIdConflicts } from "./identity.js";
+import { STRONG_ID_KEYS } from "./internal.js";
+// Keeps details attached to one strong-ID identity before any fields are combined.
+// Оставляет details одной strong-ID сущности до объединения любых полей.
+export function filterDetailsEntriesByIdentity(entries, context) {
+    const selectedIds = { ...readQueryExternalIds(context) };
+    const accepted = [];
+    for (const entry of entries) {
+        const ids = entry.result.details.ids;
+        const conflicts = strongIdConflicts(selectedIds, ids);
+        if (conflicts.length > 0 && !hasSharedStrongId(selectedIds, ids)) {
+            for (const key of conflicts) {
+                context.warnings?.push({
+                    code: "EXTERNAL_ID_CONFLICT",
+                    message: `Conflicting ${key} IDs while merging details; excluded ${ids?.[key]}.`,
+                    provider: entry.result.provider,
+                });
+            }
+            continue;
+        }
+        accepted.push(entry);
+        for (const key of STRONG_ID_KEYS) {
+            if (!selectedIds[key] && ids?.[key]) {
+                selectedIds[key] = ids[key];
+            }
+        }
+    }
+    return accepted;
+}
+// Emits warnings when details results contain conflicting media types.
+// Добавляет warnings, когда details-результаты содержат конфликтующие типы медиа.
+export function warnDetailsTypeConflicts(entries, context, selectedType) {
+    const primaryType = selectedType ?? entries[0]?.result.details.type;
+    if (!primaryType) {
+        return;
+    }
+    for (const entry of entries) {
+        const entryType = entry.result.details.type;
+        const isCompatibleAnimeCatalogType = primaryType === "anime" && entryType === "series";
+        if (entryType !== primaryType && !isCompatibleAnimeCatalogType) {
+            context.warnings?.push({
+                code: "MEDIA_TYPE_CONFLICT",
+                message: `Conflicting media types while merging details; kept ${primaryType}.`,
+                provider: entry.result.provider,
+            });
+        }
+    }
+}
+function readQueryExternalIds(context) {
+    const query = context.query;
+    if (!query) {
+        return undefined;
+    }
+    const ids = { ...query.ids };
+    for (const key of STRONG_ID_KEYS) {
+        const value = query[key];
+        if (typeof value === "string" && value.trim()) {
+            ids[key] = value.trim();
+        }
+    }
+    return Object.keys(ids).length > 0 ? ids : undefined;
+}
+//# sourceMappingURL=details-identity.js.map

package/dist/merge/details-identity.js.map

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

package/dist/merge/diversity.d.ts

@@ -0,0 +1,15 @@
+import type { MediaType } from "../media/index.js";
+import type { SearchRankEvidence } from "../search/index.js";
+export interface RankedSearchCandidate<T> {
+    value: T;
+    score: number;
+    mediaType: MediaType;
+    title: string;
+    ranking: Omit<SearchRankEvidence, "scorePosition" | "diversityPosition" | "finalPosition" | "diversity">;
+}
+export interface DiversifiedSearchCandidate<T> extends RankedSearchCandidate<T> {
+    scorePosition: number;
+    diversityPosition: number;
+    diversityFamily: string;
+}
+export declare function diversifySearchCandidates<T>(candidates: RankedSearchCandidate<T>[], enabled: boolean): DiversifiedSearchCandidate<T>[];

package/dist/merge/diversity.js

@@ -0,0 +1,52 @@
+import { normalizeTitle } from "./title.js";
+const DIVERSITY_WINDOW_SIZE = 10;
+const MAX_RESULTS_PER_FAMILY = 2;
+const SCORE_TOLERANCE = 0.03;
+const TITLE_SCORE_TOLERANCE = 0.05;
+// Interleaves only similarly ranked title/type families inside a bounded leading window.
+// Чередует только близкие по ranking title/type families внутри ограниченного верхнего окна.
+export function diversifySearchCandidates(candidates, enabled) {
+    const positioned = candidates.map((candidate, index) => ({
+        ...candidate,
+        scorePosition: index + 1,
+        diversityFamily: createDiversityFamily(candidate),
+    }));
+    if (!enabled || positioned.length < MAX_RESULTS_PER_FAMILY + 1) {
+        return positioned.map((candidate, index) => ({
+            ...candidate,
+            diversityPosition: index + 1,
+        }));
+    }
+    const pending = positioned.slice(0, DIVERSITY_WINDOW_SIZE);
+    const diversified = [];
+    const familyCounts = new Map();
+    while (pending.length > 0) {
+        const crowded = pending[0];
+        const crowdedCount = familyCounts.get(crowded.diversityFamily) ?? 0;
+        const alternativeIndex = crowdedCount >= MAX_RESULTS_PER_FAMILY
+            ? pending.findIndex((candidate, index) => index > 0 &&
+                candidate.diversityFamily !== crowded.diversityFamily &&
+                (familyCounts.get(candidate.diversityFamily) ?? 0) < MAX_RESULTS_PER_FAMILY &&
+                isComparableCandidate(candidate, crowded))
+            : -1;
+        const [selected] = pending.splice(alternativeIndex > 0 ? alternativeIndex : 0, 1);
+        if (!selected) {
+            break;
+        }
+        diversified.push(selected);
+        familyCounts.set(selected.diversityFamily, (familyCounts.get(selected.diversityFamily) ?? 0) + 1);
+    }
+    return [...diversified, ...positioned.slice(DIVERSITY_WINDOW_SIZE)].map((candidate, index) => ({
+        ...candidate,
+        diversityPosition: index + 1,
+    }));
+}
+function createDiversityFamily(candidate) {
+    const matchedTitle = candidate.ranking.titleMatch.matchedTitle ?? candidate.title;
+    return `${candidate.mediaType}:${normalizeTitle(matchedTitle)}`;
+}
+function isComparableCandidate(candidate, crowded) {
+    return (candidate.score >= crowded.score - SCORE_TOLERANCE &&
+        candidate.ranking.titleMatch.score >= crowded.ranking.titleMatch.score - TITLE_SCORE_TOLERANCE);
+}
+//# sourceMappingURL=diversity.js.map

package/dist/merge/diversity.js.map

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

package/dist/merge/fields.d.ts

@@ -0,0 +1,25 @@
+import type { Genre, Image, MediaDetails, ProviderSource, Rating } from "../media/index.js";
+import type { DetailsEntry, SearchEntry } from "./internal.js";
+import type { MergeContext } from "./types.js";
+export declare function selectTitle(entries: SearchEntry[], context: MergeContext): string | undefined;
+export declare function selectDetailsTitle(entries: DetailsEntry[], context: MergeContext): string | undefined;
+export declare function selectYear(entries: SearchEntry[], context: MergeContext): number | undefined;
+export declare function selectDetailsYear(entries: DetailsEntry[], context: MergeContext): number | undefined;
+export declare function selectReleaseDate(entries: SearchEntry[]): string | undefined;
+export declare function selectDetailsReleaseDate(entries: DetailsEntry[]): string | undefined;
+export declare function selectDescription(entries: SearchEntry[], context?: MergeContext): string | undefined;
+export declare function selectDetailsDescription(entries: DetailsEntry[], context?: MergeContext): string | undefined;
+export declare function selectShortDescription(entries: SearchEntry[]): string | undefined;
+export declare function selectBestImage(entries: SearchEntry[], field: "poster" | "backdrop"): Image | undefined;
+export declare function selectBestDetailsImage(entries: DetailsEntry[], field: "poster" | "backdrop"): Image | undefined;
+export declare function mergeGenres(entries: SearchEntry[]): Genre[] | undefined;
+export declare function mergeDetailsGenres(entries: DetailsEntry[]): Genre[] | undefined;
+export declare function mergeRatings(entries: SearchEntry[]): Rating[] | undefined;
+export declare function mergeDetailsRatings(entries: DetailsEntry[]): Rating[] | undefined;
+export declare function mergeAlternativeTitles(entries: SearchEntry[], selectedTitle: string): string[] | undefined;
+export declare function mergeDetailsAlternativeTitles(entries: DetailsEntry[], selectedTitle: string): string[] | undefined;
+export declare function mergeSources(entries: SearchEntry[]): ProviderSource[];
+export declare function mergeDetailsSources(entries: DetailsEntry[]): ProviderSource[];
+export declare function mergeDetailsImages(entries: DetailsEntry[]): Image[] | undefined;
+export declare function firstDefined<Entry, T>(entries: Entry[], pick: (entry: Entry) => T | undefined): T | undefined;
+export declare function firstMeaningfulDetailsStatus(entries: DetailsEntry[]): MediaDetails["status"];

package/dist/merge/fields.js

@@ -0,0 +1,364 @@
+import { normalizeTitle, titleCandidates } from "./title.js";
+// Selects a display title, preferring the queried title when it matches.
+// Выбирает отображаемый title, предпочитая title из запроса при совпадении.
+export function selectTitle(entries, context) {
+    const queryTitle = "title" in (context.query ?? {}) ? context.query.title : undefined;
+    const titleValues = entries.flatMap((entry) => titleCandidates(entry.result.item));
+    const localizedTitleValues = filterLocalizedText(titleValues, context.language);
+    const exactQueryTitle = queryTitle
+        ? selectExactQueryTitle(localizedTitleValues.length ? localizedTitleValues : titleValues, queryTitle)
+        : undefined;
+    if (exactQueryTitle) {
+        return exactQueryTitle;
+    }
+    const localizedTitle = selectLocalizedText(entries.flatMap((entry) => [
+        entry.result.item.title,
+        entry.result.item.originalTitle,
+        ...(entry.result.item.alternativeTitles ?? []),
+    ]), context.language);
+    if (localizedTitle) {
+        return localizedTitle;
+    }
+    return firstDefined(entries, (entry) => entry.result.item.title);
+}
+// Selects a details display title, preferring the queried title when it matches.
+// Выбирает отображаемый title деталей, предпочитая title из запроса при совпадении.
+export function selectDetailsTitle(entries, context) {
+    const localizedTitle = selectMostSupportedDetailsTitle(entries, context.language);
+    if (localizedTitle) {
+        return localizedTitle;
+    }
+    const queryTitle = "title" in (context.query ?? {}) ? context.query.title : undefined;
+    if (queryTitle) {
+        const normalizedQueryTitle = normalizeTitle(queryTitle);
+        const queryMatch = entries.find((entry) => normalizeTitle(entry.result.details.title) === normalizedQueryTitle);
+        if (queryMatch) {
+            return queryMatch.result.details.title;
+        }
+    }
+    return firstDefined(entries, (entry) => entry.result.details.title);
+}
+// Selects the localized title corroborated by the most independent providers.
+// Выбирает локализованный title, подтвержденный большинством независимых провайдеров.
+function selectMostSupportedDetailsTitle(entries, language) {
+    const candidates = new Map();
+    let order = 0;
+    for (const entry of entries) {
+        const localizedTitles = filterLocalizedText([
+            entry.result.details.title,
+            entry.result.details.originalTitle,
+            ...(entry.result.details.alternativeTitles ?? []),
+        ].filter((value) => Boolean(value?.trim())), language);
+        const providerTitles = new Set();
+        for (const value of localizedTitles) {
+            const key = normalizeTitle(value);
+            if (!key || providerTitles.has(key)) {
+                continue;
+            }
+            providerTitles.add(key);
+            const existing = candidates.get(key);
+            if (existing) {
+                existing.support += 1;
+            }
+            else {
+                candidates.set(key, { value, support: 1, order });
+            }
+            order += 1;
+        }
+    }
+    return [...candidates.values()].sort((left, right) => right.support - left.support || left.order - right.order)[0]?.value;
+}
+// Selects the primary year and emits warnings for conflicting years.
+// Выбирает основной год и добавляет warnings при конфликтующих годах.
+export function selectYear(entries, context) {
+    const primaryYear = firstDefined(entries, (entry) => entry.result.item.year);
+    for (const entry of entries) {
+        const year = entry.result.item.year;
+        if (year !== undefined && primaryYear !== undefined && year !== primaryYear) {
+            context.warnings?.push({
+                code: "YEAR_CONFLICT",
+                message: `Conflicting years while merging search results; kept ${primaryYear}.`,
+                provider: entry.result.provider,
+            });
+        }
+    }
+    return primaryYear;
+}
+// Selects the primary details year and emits warnings for conflicting years.
+// Выбирает основной год деталей и добавляет warnings при конфликтующих годах.
+export function selectDetailsYear(entries, context) {
+    const primaryYear = firstDefined(entries, (entry) => entry.result.details.year);
+    for (const entry of entries) {
+        const year = entry.result.details.year;
+        if (year !== undefined && primaryYear !== undefined && year !== primaryYear) {
+            context.warnings?.push({
+                code: "YEAR_CONFLICT",
+                message: `Conflicting years while merging details; kept ${primaryYear}.`,
+                provider: entry.result.provider,
+            });
+        }
+    }
+    return primaryYear;
+}
+// Selects the most precise release date by string length.
+// Выбирает наиболее точную дату релиза по длине строки.
+export function selectReleaseDate(entries) {
+    return maxBy(entries
+        .map((entry) => entry.result.item.releaseDate)
+        .filter((releaseDate) => Boolean(releaseDate)), (releaseDate) => releaseDate.length);
+}
+// Selects the most precise details release date by string length.
+// Выбирает наиболее точную дату релиза деталей по длине строки.
+export function selectDetailsReleaseDate(entries) {
+    return maxBy(entries
+        .map((entry) => entry.result.details.releaseDate)
+        .filter((releaseDate) => Boolean(releaseDate)), (releaseDate) => releaseDate.length);
+}
+// Selects the longest useful description.
+// Выбирает самое длинное полезное описание.
+export function selectDescription(entries, context) {
+    const descriptions = entries
+        .map((entry) => entry.result.item.description)
+        .filter((description) => Boolean(description?.trim()));
+    const localized = filterLocalizedText(descriptions, context?.language);
+    return maxBy(localized.length ? localized : descriptions, (description) => description.trim().length);
+}
+// Selects the longest useful details description.
+// Выбирает самое длинное полезное описание деталей.
+export function selectDetailsDescription(entries, context) {
+    const descriptions = entries
+        .map((entry) => entry.result.details.description)
+        .filter((description) => Boolean(description?.trim()));
+    const localized = filterLocalizedText(descriptions, context?.language);
+    return maxBy(localized.length ? localized : descriptions, (description) => description.trim().length);
+}
+// Selects the first available short description by provider priority.
+// Выбирает первое доступное короткое описание по приоритету провайдера.
+export function selectShortDescription(entries) {
+    return firstDefined(entries, (entry) => entry.result.item.shortDescription);
+}
+// Selects the best valid poster or backdrop image.
+// Выбирает лучшее валидное изображение poster или backdrop.
+export function selectBestImage(entries, field) {
+    return selectBestEntryImage(entries, (entry) => entry.result.item[field]);
+}
+// Selects the best valid details poster or backdrop image.
+// Выбирает лучшее валидное изображение poster или backdrop из деталей.
+export function selectBestDetailsImage(entries, field) {
+    return selectBestEntryImage(entries, (entry) => entry.result.details[field]);
+}
+// Merges unique genres by normalized genre name.
+// Объединяет уникальные жанры по нормализованному названию.
+export function mergeGenres(entries) {
+    const genres = new Map();
+    for (const entry of entries) {
+        for (const genre of entry.result.item.genres ?? []) {
+            const key = normalizeTitle(genre.name);
+            if (key && !genres.has(key)) {
+                genres.set(key, { ...genre });
+            }
+        }
+    }
+    return genres.size > 0 ? [...genres.values()] : undefined;
+}
+// Merges unique details genres by normalized genre name.
+// Объединяет уникальные жанры деталей по нормализованному названию.
+export function mergeDetailsGenres(entries) {
+    const genres = new Map();
+    for (const entry of entries) {
+        for (const genre of entry.result.details.genres ?? []) {
+            const key = normalizeTitle(genre.name);
+            if (key && !genres.has(key)) {
+                genres.set(key, { ...genre });
+            }
+        }
+    }
+    return genres.size > 0 ? [...genres.values()] : undefined;
+}
+// Merges ratings while keeping one rating per source.
+// Объединяет рейтинги, сохраняя один рейтинг на источник.
+export function mergeRatings(entries) {
+    const ratings = new Map();
+    for (const entry of entries) {
+        for (const rating of entry.result.item.ratings ?? []) {
+            if (!ratings.has(rating.source)) {
+                ratings.set(rating.source, { ...rating });
+            }
+        }
+    }
+    return ratings.size > 0 ? [...ratings.values()] : undefined;
+}
+// Merges details ratings while keeping one rating per source.
+// Объединяет рейтинги деталей, сохраняя один рейтинг на источник.
+export function mergeDetailsRatings(entries) {
+    const ratings = new Map();
+    for (const entry of entries) {
+        for (const rating of entry.result.details.ratings ?? []) {
+            if (!ratings.has(rating.source)) {
+                ratings.set(rating.source, { ...rating });
+            }
+        }
+    }
+    return ratings.size > 0 ? [...ratings.values()] : undefined;
+}
+// Merges alternative titles excluding the selected display title.
+// Объединяет альтернативные названия, исключая выбранный отображаемый title.
+export function mergeAlternativeTitles(entries, selectedTitle) {
+    const selectedKey = normalizeTitle(selectedTitle);
+    const titles = new Map();
+    for (const entry of entries) {
+        addAlternativeTitle(titles, entry.result.item.title, selectedKey);
+        addAlternativeTitle(titles, entry.result.item.originalTitle, selectedKey);
+        for (const title of entry.result.item.alternativeTitles ?? []) {
+            addAlternativeTitle(titles, title, selectedKey);
+        }
+    }
+    return titles.size > 0 ? [...titles.values()] : undefined;
+}
+// Merges details alternative titles excluding the selected display title.
+// Объединяет альтернативные названия деталей, исключая выбранный отображаемый title.
+export function mergeDetailsAlternativeTitles(entries, selectedTitle) {
+    const selectedKey = normalizeTitle(selectedTitle);
+    const titles = new Map();
+    for (const entry of entries) {
+        addAlternativeTitle(titles, entry.result.details.title, selectedKey);
+        addAlternativeTitle(titles, entry.result.details.originalTitle, selectedKey);
+        for (const title of entry.result.details.alternativeTitles ?? []) {
+            addAlternativeTitle(titles, title, selectedKey);
+        }
+    }
+    return titles.size > 0 ? [...titles.values()] : undefined;
+}
+// Builds public source attribution for a merged search result.
+// Создает публичную атрибуцию источников для объединенного результата поиска.
+export function mergeSources(entries) {
+    return entries.map((entry) => ({
+        provider: entry.result.source?.provider ?? entry.result.provider,
+        ids: entry.result.source?.ids ?? entry.result.item.ids,
+        url: entry.result.source?.url,
+    }));
+}
+// Builds public source attribution for merged details.
+// Создает публичную атрибуцию источников для объединенных деталей.
+export function mergeDetailsSources(entries) {
+    return entries.map((entry) => ({
+        provider: entry.result.source?.provider ?? entry.result.provider,
+        ids: entry.result.source?.ids ?? entry.result.details.ids,
+        url: entry.result.source?.url,
+    }));
+}
+// Merges unique details images by URL.
+// Объединяет уникальные изображения деталей по URL.
+export function mergeDetailsImages(entries) {
+    const images = new Map();
+    for (const entry of entries) {
+        const candidates = [
+            entry.result.details.poster,
+            entry.result.details.backdrop,
+            ...(entry.result.details.images ?? []),
+        ];
+        for (const image of candidates) {
+            if (isValidImageUrl(image) && !images.has(image.url)) {
+                images.set(image.url, { ...image });
+            }
+        }
+    }
+    return images.size > 0 ? [...images.values()] : undefined;
+}
+// Returns the first non-empty selected value from sorted entries.
+// Возвращает первое непустое выбранное значение из отсортированных entries.
+export function firstDefined(entries, pick) {
+    for (const entry of entries) {
+        const value = pick(entry);
+        if (value !== undefined && value !== "") {
+            return value;
+        }
+    }
+    return undefined;
+}
+// Returns the first lifecycle status that carries useful provider information.
+// Возвращает первый lifecycle status, который несет полезную информацию от provider.
+export function firstMeaningfulDetailsStatus(entries) {
+    return firstDefined(entries, (entry) => {
+        const status = entry.result.details.status;
+        return status === "unknown" ? undefined : status;
+    });
+}
+function selectBestEntryImage(entries, pick) {
+    const images = entries
+        .map((entry, index) => ({ image: pick(entry), index }))
+        .filter((candidate) => isValidImageUrl(candidate.image));
+    return [...images].sort((left, right) => {
+        const areaDiff = imageArea(right.image) - imageArea(left.image);
+        if (areaDiff !== 0) {
+            return areaDiff;
+        }
+        return left.index - right.index;
+    })[0]?.image;
+}
+function selectExactQueryTitle(values, queryTitle) {
+    const normalizedQueryTitle = normalizeTitle(queryTitle);
+    return values.find((value) => normalizeTitle(value) === normalizedQueryTitle);
+}
+// Selects text matching an explicitly requested language while preserving fallback behavior.
+// Выбирает текст на явно запрошенном языке, сохраняя fallback-поведение.
+function selectLocalizedText(values, language) {
+    return filterLocalizedText(values.filter((value) => Boolean(value?.trim())), language)[0];
+}
+function filterLocalizedText(values, language) {
+    const baseLanguage = language?.split("-")[0]?.toLowerCase();
+    if (!baseLanguage) {
+        return [];
+    }
+    switch (baseLanguage) {
+        case "ru":
+        case "uk":
+        case "be":
+            return values.filter((value) => /[а-яёіїєґ]/iu.test(value));
+        case "ja":
+            return values.filter((value) => /[\u3040-\u30ff\u3400-\u9fff]/u.test(value));
+        case "en":
+            return values.filter((value) => /[a-z]/iu.test(value) && !/[а-яёіїєґ\u3040-\u30ff\u3400-\u9fff]/iu.test(value));
+        default:
+            return [];
+    }
+}
+// Adds one normalized alternative title if it is useful and unique.
+// Добавляет одно нормализованное альтернативное название, если оно полезно и уникально.
+function addAlternativeTitle(titles, title, selectedKey) {
+    if (!title?.trim()) {
+        return;
+    }
+    const key = normalizeTitle(title);
+    if (key && key !== selectedKey && !titles.has(key)) {
+        titles.set(key, title);
+    }
+}
+// Returns the item with the highest computed score.
+// Возвращает элемент с максимальной вычисленной оценкой.
+function maxBy(items, score) {
+    return [...items].sort((left, right) => score(right) - score(left))[0];
+}
+// Calculates comparable image size from optional width and height.
+// Вычисляет сравнимый размер изображения по опциональным width и height.
+function imageArea(image) {
+    if (image.width && image.height) {
+        return image.width * image.height;
+    }
+    return image.width ?? image.height ?? 0;
+}
+// Checks whether an image has a valid HTTP(S) URL.
+// Проверяет, есть ли у изображения валидный HTTP(S) URL.
+function isValidImageUrl(image) {
+    if (!image?.url) {
+        return false;
+    }
+    try {
+        const url = new URL(image.url);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=fields.js.map