@media-engine/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Media Engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# @media-engine/core
+
+Core TypeScript package for Media Engine.
+
+It owns the framework-independent engine, public media types, provider contracts, streaming provider contracts, provider registry, merge strategy, cache interface, error model, and testing utilities.
+
+Core does not import concrete providers and does not read API keys from the environment. Providers are passed in from the outside.
+
+## Install
+
+```bash
+npm install @media-engine/core
+```
+
+## Basic Usage
+
+```ts
+import { MediaEngine, createMockProvider } from "@media-engine/core";
+
+const media = new MediaEngine({
+  providers: [createMockProvider()],
+});
+
+const response = await media.search({
+  title: "Interstellar",
+});
+
+console.log(response.results[0]?.item.title);
+console.log(response.meta.providers.successful);
+```
+
+## Usage With Mock Provider
+
+```ts
+import {
+  MediaEngine,
+  createDetailsResult,
+  createMockProvider,
+  createSearchResult,
+  sampleMovie,
+} from "@media-engine/core";
+
+const mockProvider = createMockProvider({
+  name: "local-fixture",
+  searchResults: [createSearchResult("local-fixture", sampleMovie)],
+  detailsResult: createDetailsResult("local-fixture", sampleMovie),
+});
+
+const media = new MediaEngine({
+  providers: [mockProvider],
+});
+
+const search = await media.search({
+  imdb: "tt0816692",
+});
+
+const details = await media.getDetails({
+  imdb: "tt0816692",
+});
+
+console.log(search.results.length);
+console.log(details.details?.title);
+```
+
+## Provider Contract Overview
+
+A provider is a small object that implements the `MediaProvider` contract:
+
+```ts
+import type { MediaProvider } from "@media-engine/core";
+
+export const provider: MediaProvider = {
+  name: "example",
+  kind: "metadata",
+  capabilities: {
+    mediaTypes: ["movie", "series", "anime"],
+    search: {
+      byTitle: true,
+      byExternalIds: ["imdb", "tmdb"],
+    },
+    details: {
+      byExternalIds: ["imdb", "tmdb"],
+    },
+  },
+  async search(query, context) {
+    return [];
+  },
+  async getDetails(query, context) {
+    return null;
+  },
+};
+```
+
+`capabilities` tell the engine when a provider can be selected. `search` returns normalized provider search results. `getDetails` is optional; providers without it are skipped by `MediaEngine.getDetails`.
+
+Provider methods receive a `context` with `signal`, `timeoutMs`, `debug`, and `language`. Providers should respect `context.signal` when they perform slow work.
+
+Applications can bound slower optional providers independently while keeping a global upper limit:
+
+```ts
+const media = new MediaEngine({
+  providers,
+  timeoutMs: 5_000,
+  providerTimeouts: {
+    cinemeta: 2_500,
+    wikidata: 2_500,
+  },
+});
+```
+
+The effective timeout is the smaller of `timeoutMs` and the matching `providerTimeouts` value.
+
+## Streaming Availability Contract
+
+Streaming availability is separate from metadata search and details. Configure streaming providers through `streamingProviders` and call `getAvailability` with a media or episode identity.
+
+```ts
+import { MediaEngine, createMockProvider } from "@media-engine/core";
+import type { StreamingProvider } from "@media-engine/core";
+
+const streamingProvider: StreamingProvider = {
+  name: "example-streaming",
+  kind: "streaming",
+  capabilities: {
+    mediaTypes: ["movie", "series", "anime"],
+    lookup: {
+      byTitle: true,
+      byExternalIds: ["imdb"],
+      byEpisode: true,
+    },
+    features: ["embed", "translations", "qualities"],
+  },
+  async getAvailability(query) {
+    return {
+      query,
+      options: [],
+      sourceProviders: [{ provider: "example-streaming" }],
+      checkedAt: new Date().toISOString(),
+    };
+  },
+};
+
+const media = new MediaEngine({
+  providers: [createMockProvider()],
+  streamingProviders: [streamingProvider],
+});
+
+const availability = await media.getAvailability({
+  type: "movie",
+  imdb: "tt0816692",
+});
+```
+
+Core does not decide whether a third-party player source is appropriate for a product. Concrete streaming providers must document their own source rules and expose only safe access URLs.
+
+## Search Response Example
+
+```ts
+import { MediaEngine, createSuccessProvider } from "@media-engine/core";
+
+const media = new MediaEngine({
+  providers: [createSuccessProvider()],
+});
+
+const response = await media.search({
+  title: "Interstellar",
+});
+```
+
+Shape:
+
+```ts
+{
+  query: {
+    title: "Interstellar",
+  },
+  results: [
+    {
+      item: {
+        id: "sample-movie-interstellar",
+        type: "movie",
+        title: "Interstellar",
+        year: 2014,
+      },
+      score: 0.5,
+      sources: [
+        {
+          provider: "success-provider",
+        },
+      ],
+    },
+  ],
+  meta: {
+    providers: {
+      requested: ["success-provider"],
+      successful: ["success-provider"],
+      failed: [],
+    },
+    cached: false,
+    tookMs: 1,
+  },
+}
+```
+
+`score`, `tookMs`, and optional fields can vary with the provider result and merge strategy.
+
+## Details Response Example
+
+```ts
+import { MediaEngine, createSuccessProvider } from "@media-engine/core";
+
+const media = new MediaEngine({
+  providers: [createSuccessProvider()],
+});
+
+const response = await media.getDetails({
+  imdb: "tt0816692",
+});
+```
+
+Shape:
+
+```ts
+{
+  query: {
+    imdb: "tt0816692",
+    ids: {
+      imdb: "tt0816692",
+    },
+  },
+  details: {
+    id: "sample-movie-interstellar",
+    type: "movie",
+    title: "Interstellar",
+    year: 2014,
+  },
+  meta: {
+    providers: {
+      requested: ["success-provider"],
+      successful: ["success-provider"],
+      failed: [],
+    },
+    cached: false,
+    tookMs: 1,
+  },
+}
+```
+
+If selected providers return no details, `details` is `null`.
+
+## Availability Response Example
+
+```ts
+import { MediaEngine, createSuccessProvider } from "@media-engine/core";
+
+const media = new MediaEngine({
+  providers: [createSuccessProvider()],
+});
+
+const response = await media.getAvailability({
+  type: "movie",
+  imdb: "tt0816692",
+});
+```
+
+When no streaming providers are configured, `options` is empty and `sourceProviders` is empty. Provider failures are exposed through response metadata when configured providers fail.
+
+## Bounded Memory Cache
+
+```ts
+import { MediaEngine, MemoryCache } from "@media-engine/core";
+
+const media = new MediaEngine({
+  cache: new MemoryCache({
+    defaultTtlMs: 5 * 60_000,
+    maxEntries: 500,
+  }),
+});
+```
+
+`defaultTtlMs` applies when a cache write does not specify its own TTL. `maxEntries` bounds memory usage and evicts the least-recently-used entry when full.
+
+## Testing Utilities
+
+The core package exports deterministic helpers for tests and examples:
+
+- `createMockProvider`;
+- `createSuccessProvider`;
+- `createFailingProvider`;
+- `createTimeoutProvider`;
+- `sampleMovie`;
+- `sampleSeries`;
+- `sampleAnime`.
+
+These helpers do not call real APIs and do not require API keys.

package/dist/cache/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./memory.js";
+export type * from "./types.js";

package/dist/cache/index.js

@@ -0,0 +1,2 @@
+export * from "./memory.js";
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/cache/memory.d.ts

@@ -0,0 +1,19 @@
+import type { Cache, CacheSetOptions } from "./types.js";
+export interface MemoryCacheOptions {
+    now?: () => number;
+    defaultTtlMs?: number;
+    maxEntries?: number;
+}
+export declare class MemoryCache implements Cache {
+    private readonly entries;
+    private readonly now;
+    private readonly defaultTtlMs?;
+    private readonly maxEntries?;
+    constructor(options?: MemoryCacheOptions);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, options?: CacheSetOptions): void;
+    delete(key: string): void;
+    clear(): void;
+    private isExpired;
+    private evictOverflow;
+}

package/dist/cache/memory.js

@@ -0,0 +1,83 @@
+// Simple synchronous in-memory cache with optional TTL support.
+// Простой синхронный in-memory cache с опциональной поддержкой TTL.
+export class MemoryCache {
+    entries = new Map();
+    now;
+    defaultTtlMs;
+    maxEntries;
+    constructor(options = {}) {
+        if (options.maxEntries !== undefined &&
+            (!Number.isInteger(options.maxEntries) || options.maxEntries <= 0)) {
+            throw new TypeError("MemoryCache maxEntries must be a positive integer.");
+        }
+        this.now = options.now ?? Date.now;
+        this.defaultTtlMs = options.defaultTtlMs;
+        this.maxEntries = options.maxEntries;
+    }
+    // Reads a cached value and removes it when it has expired.
+    // Читает значение из cache и удаляет его, если срок истек.
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        if (this.isExpired(entry)) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        if (this.maxEntries !== undefined) {
+            this.entries.delete(key);
+            this.entries.set(key, entry);
+        }
+        return cloneCacheValue(entry.value);
+    }
+    // Stores a value with an optional TTL in milliseconds.
+    // Сохраняет значение с опциональным TTL в миллисекундах.
+    set(key, value, options = {}) {
+        const ttlMs = options.ttlMs ?? this.defaultTtlMs;
+        const expiresAt = ttlMs === undefined || ttlMs < 0 ? undefined : this.now() + ttlMs;
+        this.entries.delete(key);
+        this.entries.set(key, { value: cloneCacheValue(value), expiresAt });
+        this.evictOverflow();
+    }
+    // Removes one cache entry by key.
+    // Удаляет одну запись cache по ключу.
+    delete(key) {
+        this.entries.delete(key);
+    }
+    // Removes all cache entries.
+    // Удаляет все записи cache.
+    clear() {
+        this.entries.clear();
+    }
+    // Checks whether one cache entry is expired at the current time.
+    // Проверяет, истекла ли одна запись cache к текущему времени.
+    isExpired(entry) {
+        return entry.expiresAt !== undefined && entry.expiresAt <= this.now();
+    }
+    // Evicts expired entries first, then least-recently-used entries until the bound is met.
+    // Сначала удаляет истекшие записи, затем давно не использованные до соблюдения лимита.
+    evictOverflow() {
+        if (this.maxEntries === undefined || this.entries.size <= this.maxEntries) {
+            return;
+        }
+        for (const [key, entry] of this.entries) {
+            if (this.isExpired(entry)) {
+                this.entries.delete(key);
+            }
+        }
+        while (this.entries.size > this.maxEntries) {
+            const oldestKey = this.entries.keys().next().value;
+            if (oldestKey === undefined) {
+                break;
+            }
+            this.entries.delete(oldestKey);
+        }
+    }
+}
+// Keeps callers from mutating values stored by the shared in-memory cache.
+// Не позволяет вызывающему коду изменять значения внутри общего memory cache.
+function cloneCacheValue(value) {
+    return structuredClone(value);
+}
+//# sourceMappingURL=memory.js.map

package/dist/cache/memory.js.map

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

package/dist/cache/types.d.ts

@@ -0,0 +1,9 @@
+export interface CacheSetOptions {
+    ttlMs?: number;
+}
+export interface Cache {
+    get<T>(key: string): Promise<T | undefined> | T | undefined;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+}

package/dist/cache/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":""}

package/dist/details/index.d.ts

@@ -0,0 +1 @@
+export type * from "./types.js";

package/dist/details/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/details/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/details/index.ts"],"names":[],"mappings":""}

package/dist/details/types.d.ts

@@ -0,0 +1,19 @@
+import type { ExternalIds, MediaDetails, MediaType } from "../media/index.js";
+import type { ResponseMeta } from "../response/index.js";
+export interface DetailsQuery {
+    id?: string;
+    ids?: ExternalIds;
+    imdb?: string;
+    tmdb?: string;
+    kinopoisk?: string;
+    shikimori?: string;
+    myAnimeList?: string;
+    aniList?: string;
+    type?: MediaType;
+    language?: string;
+}
+export interface DetailsResponse {
+    query: DetailsQuery;
+    details: MediaDetails | null;
+    meta: ResponseMeta;
+}

package/dist/details/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/details/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/details/types.ts"],"names":[],"mappings":""}

package/dist/engine/engine.d.ts

@@ -0,0 +1,29 @@
+import type { Cache } from "../cache/index.js";
+import type { DetailsQuery, DetailsResponse } from "../details/index.js";
+import { type MergeStrategy } from "../merge/index.js";
+import { ProviderRegistry, type ProviderInfo } from "../providers/index.js";
+import type { SearchQuery, SearchResponse } from "../search/index.js";
+import type { MediaAvailability, StreamQuery, StreamingProviderInfo } from "../streaming/index.js";
+import type { MediaEngineOptions } from "./types.js";
+export declare class MediaEngine {
+    private readonly registry;
+    private readonly streamingProviders;
+    private readonly cache?;
+    private readonly mergeStrategy;
+    private readonly timeoutMs?;
+    private readonly providerTimeouts;
+    private readonly debug;
+    constructor(options?: MediaEngineOptions);
+    getProviders(): ProviderInfo[];
+    getStreamingProviders(): StreamingProviderInfo[];
+    search(query: SearchQuery): Promise<SearchResponse>;
+    getDetails(query: DetailsQuery): Promise<DetailsResponse>;
+    getAvailability(query: StreamQuery): Promise<MediaAvailability>;
+    protected get providerRegistry(): ProviderRegistry;
+    protected get engineCache(): Cache | undefined;
+    protected get engineMergeStrategy(): MergeStrategy;
+    protected get engineTimeoutMs(): number | undefined;
+    private getProviderTimeoutMs;
+    private loadSearchPoster;
+    protected get engineDebug(): boolean;
+}