@omss/core 0.0.2-beta.0

package/dist/index.d.mts

@@ -0,0 +1,1324 @@
+//#region src/features/hooks/HookRegistry.d.ts
+/**
+ * Hook Registry
+ *
+ * Manages lifecycle hooks for OMSS events.
+ */
+declare class HookRegistry<T> {
+  #private;
+  /**
+   * Get all registered hooks immutable.
+   * @dangerous - Be careful with this. what you are doing might cause side effects.
+   */
+  get hooks(): ReadonlyMap<keyof T, unknown[]>;
+  /**
+   * Clear all registered hooks.
+   * @dangerous - Be careful with this. Might cause side effects.
+   */
+  reset(): void;
+  /**
+   * Run all hooks for a lifecycle event with the provided payload.
+   *
+   * @typeParam K - The name of the hook to run.
+   * @param name - The hook name (key of THooks).
+   * @param payload - The payload to pass to each hook handler.
+   */
+  run<K extends keyof T>(name: K, payload: T[K] extends ((payload: infer P) => unknown) ? P : never): Promise<void>;
+  /**
+   * Add a hook handler for a lifecycle event.
+   * @param name - The hook name (key of THooks).
+   * @param cb - The hook handler function.
+   */
+  add<K extends keyof T>(name: K, cb: T[K]): void;
+}
+//#endregion
+//#region src/features/hooks/HookService.d.ts
+declare class HookService<T> {
+  #private;
+  constructor(hookRegistry?: HookRegistry<T>);
+  /**
+   * Get all registered hooks immutable. TO ADD HOOKS, USE THE ADD METHOD
+   * @dangerous - Be careful with this. what you are doing might cause side effects.
+   */
+  get hooks(): ReadonlyMap<keyof T, unknown[]>;
+  /**
+   * Register a hook for a lifecycle event.
+   *
+   * @typeParam K - The name of the hook to register.
+   * @param name - The hook name (key of THooks).
+   * @param cb - The handler function for this hook.
+   */
+  add<K extends keyof T>(name: K, cb: T[K]): ReturnType<HookRegistry<T>['add']>;
+  /**
+   * Clear all registered hooks.
+   * @dangerous - Be careful with this. Might cause side effects.
+   */
+  reset(): ReturnType<HookRegistry<T>['reset']>;
+}
+//#endregion
+//#region src/types/plugin.d.ts
+/**
+ * Plugin with no configuration.
+ */
+type OMSSPluginType = (server: OMSSServer) => Promise<void>;
+/**
+ * Plugin with the required configuration.
+ */
+type OMSSConfiguredPluginType<T> = (server: OMSSServer, config: T) => Promise<void>;
+/**
+ * Any plugin type.
+ */
+type UnknownPluginType = OMSSPluginType | OMSSConfiguredPluginType<unknown>;
+/**
+ * Plugin options — either a plain value or a factory that receives
+ * the server instance and returns the resolved value.
+ */
+type OMSSPluginOptions<T> = T | ((server: OMSSServer) => T);
+//#endregion
+//#region src/features/plugins/plugin-state.d.ts
+/**
+ * The states of which a plugin can be.
+ */
+declare enum PluginState {
+  Registering = 0,
+  Registered = 1,
+  Unavailable = 2
+}
+//#endregion
+//#region src/utils/error.d.ts
+/**
+ * Base class for all OMSS framework errors.
+ * Use `instanceof OMSSError` to catch any framework error.
+ * Always throw a specific subclass, never this directly.
+ * Cause is not standardized and may change frequently.
+ */
+declare class OMSSError extends Error {
+  /**
+   * Create a new OMSSError.
+   * @param message - Error message
+   * @param options - Additional options for the error
+   */
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Returned when an error gets Returned in the OMSSServer class.
+ *
+ * @example
+ * return ERR(OMSSServerError('config.name must be a non-empty string', {cause: config}))
+ */
+declare class OMSSServerError extends OMSSError {}
+/**
+ * Returned during plugin registration or execution.
+ *
+ * @example
+ * return ERR(OMSSPluginError(`Plugin "${name}" is already registered`, { cause: plugin }))
+ */
+declare class OMSSPluginError extends OMSSError {}
+/**
+ * Returned during resolver registration or ID resolution.
+ *
+ * @example
+ * return ERR(OMSSResolverError(`No resolver found for namespace "xyz"`, { cause: rawId }))
+ */
+declare class OMSSResolverError extends OMSSError {}
+/**
+ * Returned during provider registration or source fetching.
+ *
+ * @example
+ * return ERR(OMSSProviderError('Provider must have at least one resolver', { cause: provider }))
+ */
+declare class OMSSProviderError extends OMSSError {}
+/**
+ * Returned when an extractor fails to extract the media from a host.
+ *
+ * @example
+ * return ERR(OMSSExtractor('Failed to extract media from host due to host changes', { cause: html }))
+ */
+declare class OMSSExtractorError extends OMSSError {}
+/**
+ * Returned when something/several things fail during source gathering.
+ *
+ * @example
+ * return ERR(OMSSSourceGatheringError('Failed to gather sources', { cause: providerResults }))
+ */
+declare class OMSSSourceGatheringError extends OMSSError {}
+//#endregion
+//#region src/types/utils.d.ts
+/**
+ * A discriminated union representing either a successful result or a failure.
+ * Can be {ok: true}, {ok: true, value: T} or {ok: false, error: E}
+ * @typeParam T - The success value type.
+ * @typeParam E - The error value type.
+ */
+type Result<T, E extends Error> = (T extends void ? {
+  ok: true;
+} : {
+  ok: true;
+  value: T;
+}) | {
+  ok: false;
+  error: E;
+};
+/**
+ * A tuple type that represents a non-empty array of elements of type T.
+ * The first element is of type T, and the rest of the elements are of type T[].
+ * This ensures that the array has at least one element.
+ * @typeParam T - The type of the elements in the array.
+ */
+type NonEmptyArray<T> = [T, ...T[]];
+//#endregion
+//#region src/features/plugins/PluginRegistry.d.ts
+/**
+ * Registry responsible for executing and managing OMSS Plugins.
+ *
+ * Plugins are executed when added.
+ */
+declare class PluginRegistry {
+  #private;
+  constructor(server: OMSSServer);
+  add(plugin: OMSSPluginType): Promise<Result<PluginState.Registered, OMSSPluginError>>;
+  add<T>(plugin: OMSSConfiguredPluginType<T>, options: OMSSPluginOptions<T>): Promise<Result<PluginState.Registered, OMSSPluginError>>;
+  /**
+   * Get the current plugin state.
+   */
+  getState<T>(plugin: UnknownPluginType | OMSSPluginType | OMSSConfiguredPluginType<T>): PluginState;
+}
+//#endregion
+//#region src/types/resolver.d.ts
+/**
+ * Canonical OMSS ID representation.
+ *
+ * The raw string follows the `<namespace>:<value_1>:<value_2>:(...):<value_n>` format and the certain id's/namespaces are standardized by OMSS.
+ */
+type OMSSId = string;
+/**
+ * Parsed representation of an OMSS ID.
+ */
+interface ParsedOMSSId {
+  /**
+   * The ID namespace
+   */
+  namespace: string;
+  /**
+   * The ID-values
+   */
+  values: string[];
+  /**
+   * The original raw ID string
+   */
+  raw: OMSSId;
+}
+/**
+ * Context passed into resolvers when executing them.
+ */
+interface ResolverExecutionContext {
+  /**
+   * OMSS server instance – gives access to plugins, config, etc.
+   */
+  server: OMSSServer;
+  /**
+   * Abort signal for cancellation.
+   */
+  signal: AbortSignal;
+}
+/**
+ * Result returned by a resolver – metadata for providers.
+ */
+type ResolverResult<T> = Result<T, OMSSResolverError>;
+/**
+ * Base interface for all OMSS resolvers.
+ *
+ * Resolvers convert an OMSS ID into usable metadata for providers.
+ */
+interface OMSSResolver<TMetadata> {
+  /**
+   * Namespace this resolver owns, e.g. "tmdb".
+   */
+  namespace: string;
+  /**
+   * Human-readable resolver name.
+   */
+  name: string;
+  /**
+   * A map of ID converters.
+   *
+   * @key - The unhandled namespace
+   * @value - A function that converts that id (from an unknown namespace/id provider) to this resolver's namespace.
+   */
+  converter: Map<string, (noHandlerId: OMSSId, ctx: ResolverExecutionContext) => Promise<Result<OMSSId, OMSSResolverError>>>;
+  /**
+   * Resolve a single ID into metadata.
+   *
+   * @param id - Parsed OMSS ID
+   * @param ctx - Execution context.
+   */
+  resolve(id: ParsedOMSSId, ctx: ResolverExecutionContext): Promise<ResolverResult<TMetadata>>;
+}
+//#endregion
+//#region src/features/resolvers/BaseResolver.d.ts
+/**
+ * Base class for all OMSS resolvers.
+ *
+ * Resolvers convert an OMSS ID into usable metadata for providers.
+ */
+declare abstract class BaseResolver<T> implements OMSSResolver<T> {
+  /**
+   * Namespace this resolver owns, e.g. "tmdb".
+   * Must be unique for a single server instance.
+   */
+  abstract namespace: string;
+  /**
+   * Human-readable resolver name.
+   */
+  abstract name: string;
+  /**
+   * A map of ID converters.
+   *
+   * @key - The unhandled namespace
+   * @value - A function that converts that id (from an unknown namespace/id provider) to this resolver's namespace.
+   */
+  abstract converter: Map<string, (noHandlerId: OMSSId, ctx: ResolverExecutionContext) => Promise<Result<OMSSId, OMSSResolverError>>>;
+  /**
+   * Resolve a single ID into metadata.
+   *
+   * @param id - Parsed OMSS ID
+   * @param ctx - Execution context.
+   */
+  abstract resolve(id: ParsedOMSSId, ctx: ResolverExecutionContext): Promise<ResolverResult<T>>;
+}
+//#endregion
+//#region src/types/middleware.d.ts
+/**
+ * A typed map of middleware-enabled operations.
+ */
+type MiddlewareOperationMap = Record<string, {
+  context: unknown;
+  result: unknown;
+}>;
+/**
+ * Middleware function for a specific operation.
+ */
+type MiddlewareHandler<TOperations extends MiddlewareOperationMap, TMethod extends keyof TOperations> = (context: TOperations[TMethod]['context'], next: () => Promise<TOperations[TMethod]['result']>) => Promise<TOperations[TMethod]['result']>;
+//#endregion
+//#region src/types/extractor.d.ts
+/**
+ * Extractor interface.
+ *
+ * Extractors are used to extract media URLs from a given hosting platform.
+ */
+type Extractor = {
+  /**
+   * A matcher function that checks if the extractor can handle the given URL.
+   */
+  matcher: ExtractorMatcher;
+  /**
+   * Parse the given URL and return the extracted media URL and headers required for playback.
+   * @param url - The URL to parse.
+   * @param ctx - Context object containing the referrer (what website opened the URL. If not applicable, keep string empty) and headers.
+   */
+  parse: (url: string, ctx: ExtractorContext) => Promise<Result<ExtractorResult, OMSSExtractorError>>;
+};
+type ExtractorMatcher = (url: string) => Promise<Result<void, OMSSExtractorError>>;
+type ExtractorResult = {
+  /**
+   * The media URL.
+   */
+  url: string;
+  /**
+   * Headers required for playback of the provided url.
+   */
+  header: Record<string, string>;
+};
+type ExtractorContext = {
+  /**
+   * The referrer (what website opened the URL. If not applicable, keep string empty)
+   */
+  referrer: string;
+  /**
+   * Headers required for playback of the provided url. If not applicable, keep empty.
+   */
+  header: Record<string, string>;
+  /**
+   * AbortSignal for cancellation.
+   */
+  signal: AbortSignal;
+};
+//#endregion
+//#region src/features/extractors/ExtractorRegistry.d.ts
+/**
+ * Extractor Registry
+ *
+ * Manages all extractors.
+ */
+declare class ExtractorRegistry {
+  #private;
+  /**
+   * Get all extractors.
+   */
+  get extractors(): Readonly<Extractor[]>;
+  /**
+   * Clear all extractors.
+   */
+  reset(): void;
+  /**
+   * Add an extractor.
+   * @param extractor - Extractor to add.
+   */
+  add(extractor: Extractor): void;
+  /**
+   * Check if an extractor is already registered.
+   * @param extractor - Extractor to check.
+   */
+  has(extractor: Extractor): boolean;
+  /**
+   * Remove an extractor.
+   * @param extractor - Extractor to remove.
+   * @returns True if the extractor was removed, false otherwise.
+   */
+  remove(extractor: Extractor): boolean;
+}
+//#endregion
+//#region src/features/extractors/ExtractorService.d.ts
+declare class ExtractorService {
+  #private;
+  constructor(extractorRegistry: ExtractorRegistry, hookRegistry: HookRegistry<OMSSHooks>);
+  /**
+   * Get all registered extractors (read-only).
+   */
+  get extractors(): Result<ReadonlyArray<Extractor>, Error>;
+  /**
+   * Find an extractor capable of handling the given URL.
+   *
+   * @param url - URL to search for.
+   * @returns The first matching {@link Extractor} or an {@link OMSSExtractorError}.
+   */
+  find(url: string): Promise<Result<Extractor, OMSSExtractorError>>;
+  /**
+   * Register an extractor.
+   *
+   * @param extractor - Extractor to register.
+   */
+  register(extractor: Extractor): Promise<Result<void, Error>>;
+  /**
+   * Remove every registered extractor.
+   */
+  reset(): Result<void, Error>;
+  /**
+   * Determine whether an extractor has already been registered.
+   *
+   * @param extractor - Extractor to check.
+   */
+  has(extractor: Extractor): Result<boolean, Error>;
+  /**
+   * Remove an extractor.
+   *
+   * @param extractor - Extractor to remove.
+   * @returns Whether the extractor was removed.
+   */
+  remove(extractor: Extractor): Result<boolean, Error>;
+}
+//#endregion
+//#region src/types/provider.d.ts
+/**
+ * Core provider interface.
+ *
+ * @typeParam P - The resolver class this provider is bound to.
+ *               The return type of P['resolve'] determines the `meta`
+ *               parameter shape of getSources().
+ */
+interface OMSSProvider<P extends BaseResolver<unknown>> {
+  /** Provider ID. Must be unique. */
+  readonly id: string;
+  /** Friendly name of the provider. */
+  readonly name: string;
+  /** Whether the provider will be used. */
+  readonly enabled: boolean;
+  /**
+   * Catalog of media this provider supports. It does not have to exist. If it does, it should be a list of media IDs.
+   * This does not get queried for source resolving, but more metadata about the provider.
+   */
+  readonly catalog?: () => Promise<NonEmptyArray<string>> | NonEmptyArray<string>;
+  /**
+   * Provide a method that checks whether this provider supports a certain ID.
+   * @param id - Parsed OMSS ID
+   */
+  readonly supportsId: (id: ParsedOMSSId) => boolean | Promise<boolean>;
+  /** Resolver that this provider is bound to. */
+  readonly resolver: P;
+  /**
+   * Fetch sources for a certain request.
+   * The shape of `request.meta` is derived from the resolver's resolve() return type.
+   */
+  getSources(request: ProviderSourcesMeta<ResolverMetadata<P>>, result: ProviderResultEmitter): Promise<ProviderResult>;
+}
+/**
+ * Extract the metadata type from a resolver's resolve method.
+ */
+type ResolverMetadata<R extends BaseResolver<unknown>> = Extract<Awaited<ReturnType<R['resolve']>>, {
+  ok: true;
+}> extends {
+  value: infer T;
+} ? T : never;
+/**
+ * The object passed to providers when they are executed.
+ */
+type ProviderSourcesMeta<T> = {
+  utils: {
+    /**
+     * The parsed OMSS ID of the current request.
+     */
+    omssId: ParsedOMSSId;
+    /**
+     * The abort controller signal for the current request. Providers can check this to abort the request early (recommended for long running requests).
+     */
+    abortSignal: AbortSignal;
+    /**
+     * A function to find an extractor by whatever the extractor service is configured to use.
+     * @param args - Arguments to pass to the extractor service's find() method.'
+     */
+    findExtractor: (...args: Parameters<ExtractorService['find']>) => ReturnType<ExtractorService['find']>;
+  }; /** Metadata returned by the resolver */
+  meta: T;
+};
+/**
+ * Provider with an unknown resolver. Utils for other services and registries
+ */
+type UnknownProvider = OMSSProvider<BaseResolver<unknown>>;
+/**
+ * The result of a provider getSources call.
+ */
+type ProviderResult = Result<OMSSProviderResult, OMSSProviderError>;
+/**
+ * The result of a provider getSources call if successful.
+ */
+interface OMSSProviderResult {
+  /**
+   * Array of sources.
+   */
+  sources: Source[];
+  /**
+   * Array of subtitle tracks.
+   */
+  subtitles: Subtitle[];
+  /**
+   * Array of errors.
+   */
+  errors: OMSSProviderError[];
+}
+/**
+ * The result object passed to the provider's getSources() method.
+ */
+type ProviderResultEmitter = {
+  /**
+   * Utilities to make your life easier
+   */
+  utils: {
+    /**
+     * Utilities for parsing metadata of sources
+     */
+    source: {
+      /**
+       * Parse a string into a possible source type.
+       * @param possibleType - The string to parse
+       */
+      parseType(possibleType: string): SourceTypes;
+      /**
+       * Parse a string into a possible source quality.
+       * @param possibleQuality - The string to parse
+       */
+      parseQuality(possibleQuality: string): SourceQuality;
+    };
+    /**
+     * Utilities for parsing metadata of subtitles
+     */
+    subtitle: {
+      /**
+       * Parse a string into a possible subtitle format.
+       * @param possibleFormat - The string to parse
+       */
+      parseFormat(possibleFormat: string): SubtitleFormat;
+    };
+  };
+  /**
+   * Method for custom logging
+   * @param action - The action to log
+   * @param data - The data to log
+   */
+  emit(action: string, data: unknown): void;
+  /**
+   * Method for debug logging
+   * @param args - Arguments to log
+   */
+  debug(...args: unknown[]): void;
+  /**
+   * Method for information logging
+   * @param args - Arguments to log
+   */
+  info(...args: unknown[]): void;
+  /**
+   * Method for warning logging
+   * @param args - Arguments to log
+   */
+  warn(...args: unknown[]): void;
+  /**
+   * Method for error logging. Not fatal.
+   * @param error - The error to log. This will be returned to the requestor
+   */
+  error(error: OMSSProviderError): void;
+  /**
+   * Method to emit a source.
+   * @param source - The source to emit
+   */
+  source(source: Omit<Source, 'provider'>): void;
+  /**
+   * Method to emit a subtitle.
+   * @param subtitle - The subtitle to emit
+   */
+  subtitle(subtitle: Omit<Subtitle, 'provider'>): void;
+  /**
+   * Method to emit a fatal error. This will stop the provider from executing.
+   * @param error - The error to emit
+   * @example
+   * ```typescript
+   * return result.fatal(new OMSSProviderError("Error Message", {cause: optionalObject}))
+   * ```
+   */
+  fatal(error: OMSSProviderError): Result<never, OMSSProviderError>;
+  /**
+   * Signal that the provider has finished processing.
+   * @important Return the return value of this method.
+   * @example
+   * ```typescript
+   * return result.done()
+   * ```
+   */
+  done(): ProviderResult;
+};
+interface BaseSource {
+  /**
+   * A string representing the original URL to the streaming source from the provider, which may require CORS handling or custom headers (provided in the headers field).
+   */
+  url: string;
+  /**
+   * Key-value pairs of HTTP (and non-standard HTTP) headers that should be included when accessing the source URL.
+   */
+  header: Record<string, string>;
+  /**
+   * Indicates if the source is streamable (true) or a direct download link (false). If false, clients must treat the URL as a download link rather than a streaming source. Download links CANNOT be used as streaming sources.
+   * @see [MDN Range Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Range#:~:text=A%20server%20that%20doesn%27t%20support%20range%20requests%20may%20ignore%20the%20Range%20header%20and%20return%20the%20whole%20resource%20with%20a%20200%20status%20code.)
+   */
+  streamable: boolean;
+  /**
+   * Source type, one of:
+   * hls — HTTP Live Streaming (M3U8).
+   * mp4 — MP4 file.
+   * mkv — MKV file.
+   * dash — MPEG-DASH (.mpd files).
+   */
+  type: SourceTypes;
+  /**
+   * Video quality. One of 8K, 4K, QHD, FHD, HD, SD, or Auto: Quality should be inferred from the best available metadata, prioritizing resolution, then bitrate, filename, or manifest information. If the quality cannot be determined, use Auto.
+   *
+   * The ranges are like following:
+   * 4320p+ → 8K
+   * 2160p–4319p → 4K
+   * 1440p–2159p → QHD
+   * 1080p–1439p → FHD
+   * 720p–1079p → HD
+   * Below 720p → SD
+   * Unknown → Auto
+   */
+  quality: SourceQuality;
+  /**
+   * Information on the provider that provided this source.
+   */
+  provider: {
+    id: string;
+    name: string;
+  };
+}
+/**
+ * A source that has at least one known language baked into the stream itself
+ * (e.g. audio muxed into the HLS/DASH manifest or MP4/MKV file).
+ */
+interface SourceWithLanguages extends BaseSource {
+  /**
+   * Human-readable language name(s). default/unknown --> Original
+   * This should be provided to the best of the provider's ability.
+   * You should only list languages that are actually available in this specific source. If the source only contains video (no audio), keep this array empty and add the audiotracks via result.audioTrack().
+   */
+  languages: NonEmptyArray<string>;
+  audioTracks?: never;
+}
+/**
+ * A source with no muxed-in audio at all (e.g. video-only stream).
+ * MUST provide at least one separate AudioTrack instead.
+ */
+interface SourceWithAudioTracks extends BaseSource {
+  languages?: never;
+  /**
+   * Array of audio tracks.
+   */
+  audioTracks: NonEmptyArray<AudioTrack>;
+}
+/**
+ * A source object.
+ * A source MUST declare at least one language (muxed-in) OR at least one
+ * separate audioTrack. Both may be present; at least one is required.
+ * @see https://github.com/omss-spec/omss-spec/blob/main/spec/v1.1/omss-v1.1.md#62-source-object
+ */
+type Source = SourceWithLanguages | SourceWithAudioTracks;
+/**
+ * Valid Source Types
+ */
+type SourceTypes = 'hls' | 'mp4' | 'dash' | 'mkv';
+/**
+ * Video quality
+ */
+type SourceQuality = '8K' | '4K' | 'QHD' | 'FHD' | 'HD' | 'SD' | 'Auto';
+/**
+ * A subtitle object.
+ * @see https://github.com/omss-spec/omss-spec/blob/main/spec/v1.1/omss-v1.1.md#63-subtitle-object
+ */
+interface Subtitle {
+  /**
+   * A string representing the original URL to the subtitle from the provider, which may require CORS handling or custom headers (provided in the headers field).
+   */
+  url: string;
+  /**
+   * Key-value pairs of HTTP (and non-standard HTTP) headers that should be included when accessing the subtitle URL.
+   */
+  header: Record<string, string>;
+  /**
+   * Human-readable language name for the subtitle track. default/unknown --> Unknown
+   */
+  label: string;
+  /**
+   * Subtitle format, one of:
+   *
+   * vtt — WebVTT.
+   * srt — SubRip.
+   */
+  format: SubtitleFormat;
+  /**
+   * Information on the provider that provided this subtitle track.
+   */
+  provider: {
+    id: string;
+    name: string;
+  };
+}
+/**
+ * Valid Subtitle Formats
+ */
+type SubtitleFormat = 'vtt' | 'srt';
+/**
+ * An audio track object.
+ * @see https://github.com/omss-spec/omss-spec/blob/main/spec/v1.1/omss-v1.1.md#62-source-object:~:text=Unknown%20%E2%86%92%20Auto-,audioTracks,-(array%20of%20strings
+ * @see https://github.com/omss-spec/omss-spec/issues/8
+ */
+interface AudioTrack {
+  /**
+   * A string representing the original URL to the audiotrack from the provider, which may require CORS handling or custom headers (provided in the headers field).
+   */
+  url: string;
+  /**
+   * Key-value pairs of HTTP (and non-standard HTTP) headers that should be included when accessing the audiotrack URL.
+   */
+  header: Record<string, string>;
+  /**
+   * Human-readable language name for the audiotrack. default/unknown --> Unknown
+   */
+  label: string;
+}
+/**
+ * Helper types for the structure that should be passed into the emitter.
+ */
+type EmittedSource = Omit<SourceWithLanguages, 'provider'> | Omit<SourceWithAudioTracks, 'provider'>;
+type EmittedSubtitle = Omit<Subtitle, 'provider'>;
+/**
+ * Methods that can be called on the ProviderService middleware.
+ */
+type ProviderServiceOperations = {
+  /**
+   * The provider registration pipeline.
+   *
+   * Middleware runs after `beforeProviderRegister` and before
+   * ProviderRegistry.add(). Context carries the provider being registered.
+   */
+  register: {
+    context: {
+      provider: UnknownProvider;
+    };
+    result: Result<UnknownProvider, OMSSProviderError>;
+  };
+};
+type ProviderServiceMiddleware<TMethod extends keyof ProviderServiceOperations> = MiddlewareHandler<ProviderServiceOperations, TMethod>;
+//#endregion
+//#region src/types/source.d.ts
+/**
+ * Options for fetching sources.
+ */
+type GetSourcesOptions = {
+  providerId?: string;
+  abortSignal?: AbortSignal;
+  cleaningFunction?: CleaningFunction;
+  providerHookService?: HookService<ProviderHooks>;
+};
+/**
+ * Object returned by the SourceService.GetSources() method if there has been at least one successful provider.
+ */
+type GatheredSources = {
+  /**
+   * Array of sources.
+   */
+  sources: Source[];
+  /**
+   * Array of subtitle tracks.
+   */
+  subtitles: Subtitle[];
+  /**
+   * Array of errors.
+   */
+  errors: OMSSError[];
+};
+/**
+ * Operations supported by the SourceService Middleware Runner with the according context and result types.
+ */
+type SourceServiceOperations = {
+  getSources: {
+    context: {
+      omssId: OMSSId;
+      options: GetSourcesOptions;
+    };
+    result: Result<GatheredSources, OMSSSourceGatheringError>;
+  };
+  afterGetSources: {
+    context: {
+      omssId: OMSSId;
+      options: GetSourcesOptions;
+      result: Result<GatheredSources, OMSSSourceGatheringError>;
+    };
+    result: Result<GatheredSources, OMSSSourceGatheringError>;
+  };
+};
+/**
+ * Middleware function for the SourceService
+ */
+type SourceServiceMiddleware<TMethod extends keyof SourceServiceOperations> = MiddlewareHandler<SourceServiceOperations, TMethod>;
+/**
+ * Function to clean a source.
+ *
+ * This function will be called between a source is registered (in the ResultEmitter) and the source is emitted.
+ */
+type ObjectToClean = {
+  url: string;
+  header: Record<string, string>;
+};
+type CleaningFunction = (obj: ObjectToClean) => ObjectToClean;
+//#endregion
+//#region src/types/hooks.d.ts
+/**
+ * Hook map for OMSS lifecycle events.
+ * Each hook name maps to its own payload signature.
+ *
+ * Hooks follow a standardized signature:
+ * - `before[action]` hooks receive the payload before the event is triggered
+ * - `after[action]` hooks receive the payload after the event is triggered
+ * - `[action]failed` hooks receive the payload if the event fails
+ *
+ * @note - There are special hooks with elevated access. See the docs for more info.
+ */
+type OMSSHooks = {
+  /**
+   * Called before a plugin is registered.
+   */
+  beforePluginRegister: <T>(payload: {
+    plugin: UnknownPluginType;
+    options?: OMSSPluginOptions<T>;
+  }) => void | Promise<void>;
+  /**
+   * Called after a plugin is successfully registered.
+   */
+  afterPluginRegister: <T>(payload: {
+    plugin: UnknownPluginType;
+    options?: OMSSPluginOptions<T>;
+  }) => void | Promise<void>;
+  /**
+   * Called when a plugin registration fails.
+   */
+  pluginRegisterFailed: <T>(payload: {
+    plugin: UnknownPluginType;
+    options?: OMSSPluginOptions<T>;
+    error: Error;
+  }) => void | Promise<void>;
+  /**
+   * Called before a provider is registered.
+   */
+  beforeProviderRegister: (payload: {
+    provider: UnknownProvider;
+  }) => void | Promise<void>;
+  /**
+   * Called after a provider is successfully registered.
+   */
+  afterProviderRegister: (payload: {
+    provider: UnknownProvider;
+  }) => void | Promise<void>;
+  /**
+   * Called when a provider registration fails.
+   */
+  providerRegisterFailed: (payload: {
+    provider: UnknownProvider;
+    error: OMSSProviderError;
+  }) => void | Promise<void>;
+  /**
+   * Called before sources are fetched for an OMSS ID.
+   * Receives the raw ID and the optional provider filter.
+   *
+   * @dangerous - This hook is not intended for general use. You can achieve very funny side effects by using it. Use with caution.
+   */
+  beforeGetSources: (payload: {
+    omssId: OMSSId;
+    providerId?: string | undefined;
+  }) => void | Promise<void>;
+  /**
+   * Called after sources have been successfully fetched.
+   * Receives the ID, optional provider filter, and the aggregated result.
+   */
+  afterGetSources: (payload: {
+    omssId: OMSSId;
+    providerId?: string | undefined;
+    result: GatheredSources;
+  }) => void | Promise<void>;
+  /**
+   * Called when a getSources call fails entirely (no provider succeeded).
+   */
+  getSourcesFailed: (payload: {
+    omssId: OMSSId;
+    providerId?: string | undefined;
+    error: OMSSProviderError;
+  }) => void | Promise<void>;
+  /**
+   * Called before an extractor is registered.
+   *
+   * @dangerous
+   * Registering another extractor from this hook is not allowed and will
+   * result in an {@link OMSSExtractorError}.
+   */
+  beforeRegisterExtractor: (payload: {
+    extractor: Extractor;
+  }) => void | Promise<void>;
+  /**
+   * Called after an extractor has been successfully registered.
+   */
+  afterRegisterExtractor: (payload: {
+    extractor: Extractor;
+  }) => void | Promise<void>;
+  /**
+   * Called when extractor registration fails.
+   */
+  extractorRegisterFailed: (payload: {
+    extractor: Extractor;
+    error: OMSSExtractorError;
+  }) => void | Promise<void>;
+  /**
+   * Called before attempting to find an extractor for a URL.
+   */
+  beforeFindExtractor: (payload: {
+    url: string;
+  }) => void | Promise<void>;
+  /**
+   * Called after extractor lookup completes.
+   *
+   * If no extractor matched, {@link payload.extractor} will be `undefined`.
+   */
+  afterFindExtractor: (payload: {
+    url: string;
+    extractor: Extractor | undefined;
+  }) => void | Promise<void>;
+  /**
+   * Called when no extractor could be found for the provided URL.
+   */
+  findExtractorFailed: (payload: {
+    url: string;
+    error: OMSSExtractorError;
+  }) => void | Promise<void>;
+};
+/**
+ * Base payload shared by every provider hook.
+ */
+interface BaseProviderHookPayload {
+  /** The provider instance that emitted the event. */
+  provider: Readonly<UnknownProvider>;
+  /**
+   * The OMSS ID that was being processed.
+   */
+  id: ParsedOMSSId;
+  /**
+   * At what time was this event emitted?
+   */
+  timestamp: string;
+}
+/**
+ * Fired when `emitter.debug(...)` is called.
+ * Intended for verbose, development-only diagnostics.
+ */
+type ProviderDebugPayload = BaseProviderHookPayload & {
+  /** Raw arguments forwarded from `debug(...args)`. */args: unknown[];
+};
+/**
+ * Fired when `emitter.info(...)` is called.
+ * General informational messages about provider execution.
+ */
+type ProviderInfoPayload = BaseProviderHookPayload & {
+  /** Raw arguments forwarded from `info(...args)`. */args: unknown[];
+};
+/**
+ * Fired when `emitter.warn(...)` is called.
+ * Non-fatal, degraded-but-recoverable situations.
+ */
+type ProviderWarnPayload = BaseProviderHookPayload & {
+  /** Raw arguments forwarded from `warn(...args)`. */args: unknown[];
+};
+/**
+ * Fired when `emitter.error(...)` is called (non-fatal) OR when
+ * `emitter.fatal(...)` is called (fatal — the aggregated error is passed here too).
+ */
+type ProviderErrorPayload = BaseProviderHookPayload & {
+  /** The error that was recorded or that terminated the provider. */error: OMSSProviderError;
+};
+/**
+ * Fired every time `emitter.source(...)` emits a new source.
+ */
+type ProviderSourcePayload = BaseProviderHookPayload & {
+  /** The source object that was just emitted. */source: Source;
+};
+/**
+ * Fired every time `emitter.subtitle(...)` emits a new subtitle track.
+ */
+type ProviderSubtitlePayload = BaseProviderHookPayload & {
+  /** The subtitle object that was just emitted. */subtitle: Subtitle;
+};
+/**
+ * Fired once when `emitter.done()` finalizes the provider's result.
+ */
+type ProviderDonePayload = BaseProviderHookPayload & {
+  /** The fully aggregated result (sources, subtitles, non-fatal errors). */result: OMSSProviderResult;
+};
+/**
+ * Fired for provider-defined custom events via `emitter.emit(action, data)`.
+ *
+ * @remarks
+ * This is an escape hatch for provider-specific diagnostics/telemetry that
+ * don't map to any of the fixed lifecycle hooks below (e.g. `"cache.hit"`,
+ * `"upstream.retry"`). The `action` string becomes the hook name itself
+ * when calling `hookReg.run(action, ...)`, so consumers register listeners
+ * for these dynamically via `hookReg.add('cache.hit', handler)`.
+ */
+type ProviderCustomEventPayload = BaseProviderHookPayload & {
+  /** Arbitrary payload associated with the custom event. */data: unknown;
+};
+interface FixedProviderHooks {
+  /** See {@link ProviderDebugPayload}. */
+  debug: (payload: ProviderDebugPayload) => void | Promise<void>;
+  /** See {@link ProviderInfoPayload}. */
+  info: (payload: ProviderInfoPayload) => void | Promise<void>;
+  /** See {@link ProviderWarnPayload}. */
+  warn: (payload: ProviderWarnPayload) => void | Promise<void>;
+  /** See {@link ProviderErrorPayload}. Fires on both `error()` and `fatal()`. */
+  error: (payload: ProviderErrorPayload) => void | Promise<void>;
+  /** See {@link ProviderSourcePayload}. Fires once per `source()` call. */
+  source: (payload: ProviderSourcePayload) => void | Promise<void>;
+  /** See {@link ProviderSubtitlePayload}. Fires once per `subtitle()` call. */
+  subtitle: (payload: ProviderSubtitlePayload) => void | Promise<void>;
+  /** See {@link ProviderDonePayload}. Fires exactly once, at the end of execution. */
+  done: (payload: ProviderDonePayload) => void | Promise<void>;
+}
+interface ProviderCustomHooks {
+  [action: string]: (payload: ProviderCustomEventPayload) => void | Promise<void>;
+}
+/**
+ * All lifecycle hooks fired by a `ProviderResultEmitter` during a single
+ * `getSources()` execution.
+ *
+ * Every union member listed in the index signature corresponds 1:1 to one
+ * of the named hooks below, so each named hook's function type is a valid
+ * subtype of the index signature — this keeps the interface consistent
+ * while still allowing strict payload typing for the well-known events.
+ */
+type ProviderHooks = FixedProviderHooks & ProviderCustomHooks;
+//#endregion
+//#region src/features/plugins/PluginService.d.ts
+/**
+ * The public API for managing OMSS plugins.
+ */
+declare class PluginService {
+  #private;
+  constructor(omssServer: OMSSServer, pluginRegistry: PluginRegistry, hookRegistry: HookRegistry<OMSSHooks>);
+  /**
+   * Register an OMSS plugin with no config into the system.
+   * @param plugin - Plugin function
+   */
+  register(plugin: OMSSPluginType): ReturnType<PluginRegistry['add']>;
+  /**
+   * Register an OMSS plugin with a config into the system.
+   * @param plugin - Plugin function
+   * @param options - Plugin configuration
+   */
+  register<T>(plugin: OMSSConfiguredPluginType<T>, options: OMSSPluginOptions<T>): ReturnType<PluginRegistry['add']>;
+  /**
+   * Get the current State of a plugin
+   * @param plugin - the plugin to get the state from
+   * @returns - a value of the PluginState enum
+   */
+  getPluginState(plugin: UnknownPluginType): ReturnType<PluginRegistry['getState']>;
+}
+//#endregion
+//#region src/types/config.d.ts
+interface OMSSConfig {
+  /**
+   * A human-readable name for this server instance.
+   */
+  name: string;
+}
+//#endregion
+//#region src/features/providers/ProviderRegistry.d.ts
+/**
+ * Registry responsible for storing and managing OMSS Providers.
+ *
+ * Providers are stored by their unique {@link UnknownProvider.id}.
+ * This registry does not know about hooks.
+ */
+declare class ProviderRegistry {
+  #private;
+  /**
+   * Adds a provider to the registry.
+   *
+   * @param provider - The provider instance to register.
+   * @returns `OK` if registration succeeded, `ERR` if the provider ID is already taken.
+   */
+  add(provider: UnknownProvider): Promise<Result<UnknownProvider, OMSSProviderError>>;
+  /**
+   * Retrieves a registered provider by its ID.
+   *
+   * @param id - The unique provider ID.
+   * @returns The provider instance, or `undefined` if not found.
+   */
+  get(id: string): UnknownProvider | undefined;
+  /**
+   * Returns all registered providers.
+   */
+  getAll(filter?: (p: UnknownProvider) => boolean): UnknownProvider[];
+  /**
+   * Returns whether a provider with the given ID is registered.
+   *
+   * @param id - The unique provider ID.
+   */
+  has(id: string): boolean;
+}
+//#endregion
+//#region src/features/source/SourceService.d.ts
+/**
+ * Public API for resolving sources for media.
+ *
+ * This service owns the public method surface, middleware execution,
+ * lifecycle hook dispatching, and request coalescing. The actual source
+ * gathering implementation lives in {@link SourceCore}.
+ */
+declare class SourceService {
+  #private;
+  constructor(omssServer: OMSSServer, providerRegistry: ProviderRegistry, hookRegistry: HookRegistry<OMSSHooks>, extractorService: ExtractorService);
+  get cleaningFunction(): CleaningFunction;
+  set cleaningFunction(fn: CleaningFunction);
+  /**
+   * Register middleware for a SourceService method.
+   *
+   * Middleware can be used for cross-cutting concerns such as caching,
+   * logging, tracing, or metrics.
+   *
+   * @param method - Middleware-enabled method name.
+   * @param handler - Middleware handler.
+   */
+  use<TMethod extends keyof SourceServiceOperations>(method: TMethod, handler: SourceServiceMiddleware<TMethod>): void;
+  /**
+   * Fetch sources from all matching providers for an OMSS ID.
+   *
+   * This method is middleware-enabled. Concurrent requests for the same
+   * `omssId` and `providerId` share the same in-flight Promise until the
+   * request settles.
+   *
+   * @param omssId - OMSS identifier such as `"tmdb:12345"`.
+   * @param options - Optional source gathering parameters.
+   * @returns Aggregated provider results or a source gathering error.
+   */
+  getSources(omssId: OMSSId, options?: GetSourcesOptions): Promise<Result<GatheredSources, OMSSSourceGatheringError>>;
+}
+//#endregion
+//#region src/features/providers/ProviderService.d.ts
+/**
+ * The public API for managing OMSS Providers.
+ */
+declare class ProviderService {
+  #private;
+  constructor(providerRegistry: ProviderRegistry, hookRegistry: HookRegistry<OMSSHooks>);
+  /**
+   * Adds middleware to the `register` pipeline.
+   * Middlewares run in insertion order, after hooks and before the
+   * actual registry `add()` call.
+   */
+  use<TMethod extends keyof ProviderServiceOperations>(method: TMethod, handler: ProviderServiceMiddleware<TMethod>): this;
+  /**
+   * Registers a provider into the system.
+   */
+  register(provider: UnknownProvider): Promise<Result<UnknownProvider, OMSSProviderError>>;
+  /**
+   * Retrieves a registered provider by its ID.
+   *
+   * @param id - The provider ID to look up.
+   * @returns The provider instance, or `undefined` if not found.
+   */
+  get(id: string): ReturnType<ProviderRegistry['get']>;
+  /**
+   * Returns all registered providers.
+   * @param filter - Optional filter function to apply to providers.
+   */
+  getAll(filter?: (p: UnknownProvider) => boolean): ReturnType<ProviderRegistry['getAll']>;
+  /**
+   * Returns whether a provider with the given ID has been registered.
+   *
+   * @param id - The provider ID to check.
+   */
+  has(id: string): ReturnType<ProviderRegistry['has']>;
+  /**
+   * Returns a map of all namespaces and an array of all known identifiers for each namespace.
+   * This list is BEST EFFORT ONLY. Do not rely on this. If any provider returns a `*` automatically, the namespace will support all identifiers (e.g. `"tmdb": ["*"], "imdb": ["tt37636", "..."]`.
+   */
+  catalog(): Promise<Result<Map<string, string[]>, OMSSProviderError>>;
+  /**
+   * Returns the catalog for a single namespace.
+   * Returns `undefined` if no provider in that namespace exposes a catalog.
+   *
+   * @param namespace - The resolver namespace to look up (e.g. `"tmdb"`).
+   * @returns Merged list of IDs for the namespace, `["*"]` if any provider
+   *          signals wildcard support, or `undefined` if no catalog data exists.
+   */
+  catalogForNamespace(namespace: string): Promise<Result<string[], OMSSProviderError>>;
+}
+//#endregion
+//#region src/core/server.d.ts
+/**
+ * Core server class for OMSS.
+ */
+declare class OMSSServer {
+  #private;
+  readonly hooks: HookService<OMSSHooks>;
+  readonly plugins: PluginService;
+  readonly providers: ProviderService;
+  readonly sources: SourceService;
+  readonly extractors: ExtractorService;
+  /**
+   * Creates a new OMSSServer instance.
+   *
+   * @param config - Immutable server configuration
+   */
+  constructor(config: OMSSConfig);
+  /**
+   * Get the OMSS Config from the constructor
+   * @returns the initialised OMSS Config
+   */
+  get config(): Readonly<OMSSConfig>;
+  /**
+   * Decorate the OMSSServer instance with a new property.
+   * @param name - The name of the property to be decorated.
+   * @param value - The value to be assigned to the property.
+   * @param deps - An array of dependency names.
+   * @returns The name of the decorated property in the {@link Result} object.
+   */
+  decorate<T>(name: string, value: T, deps?: string[]): Result<string, OMSSServerError>;
+  /**
+   * Check if a decorator with the given name exists.
+   * @param name - The name of the decorator to check.
+   * @returns True if the decorator exists, false otherwise.
+   */
+  hasDecorator(name: string): boolean;
+  /**
+   * Get a decorated property by its name.
+   * @param name - The name of the property to retrieve.
+   * @returns The decorated property value in the {@link Result} object.
+   */
+  getDecorator<T>(name: string): Result<T, OMSSServerError>;
+}
+//#endregion
+//#region src/features/providers/BaseProvider.d.ts
+/**
+ * Base class for all providers.
+ */
+declare abstract class BaseProvider<P extends BaseResolver<unknown>> implements OMSSProvider<P> {
+  /**
+   * Provider ID. Must be unique.
+   */
+  abstract readonly id: string;
+  /**
+   * Friendly name of the provider.
+   */
+  abstract readonly name: string;
+  /**
+   * Whether the provider will be used.
+   */
+  abstract readonly enabled: boolean;
+  /**
+   * Catalog of media this provider supports. It does not have to exist. If it does, it should be a list of media IDs.
+   * This does not get queried for source resolving, but more metadata about the provider.
+   */
+  abstract readonly catalog?: () => Promise<NonEmptyArray<string>> | NonEmptyArray<string>;
+  /**
+   * Provide a method that checks whether this provider supports a certain ID.
+   * @param id - Parsed OMSS ID
+   */
+  abstract readonly supportsId: (id: ParsedOMSSId) => boolean | Promise<boolean>;
+  /**
+   * Resolvers that this provider supports.
+   */
+  abstract readonly resolver: P;
+  /**
+   * Fetch sources for a certain media.
+   * @param media - Return object of the resolver's resolve() method.
+   * @param result - The result emitter.
+   */
+  abstract getSources(media: ProviderSourcesMeta<ResolverMetadata<P>>, result: ProviderResultEmitter): Promise<ProviderResult>;
+}
+//#endregion
+//#region src/features/resolvers/utils.d.ts
+/**
+ * Parses an OMSS ID in the form `namespace:value_1[:value_2[:...]]`.
+ */
+declare function parseOMSSId(id: OMSSId): Result<ParsedOMSSId, OMSSResolverError>;
+//#endregion
+//#region src/utils/utils.d.ts
+/**
+ * Convenience factory for a successful result.
+ */
+declare function OK(): Result<void, never>;
+declare function OK<T>(value: T): Result<T, never>;
+/**
+ * Convenience factory for a failed result.
+ */
+declare const ERR: <E extends Error>(error: E) => Result<never, E>;
+type ErrorConstructor<T extends OMSSError> = new (message: string, options?: {
+  cause?: Error;
+}) => T;
+/**
+ * Validate a string is safe for use as a unique identifier (only lowercase letters, numbers, and hyphens).
+ * @param value - The string to validate
+ * @param name - The name of the identifier, for error messages
+ * @param ErrorType - The error type to return if validation fails
+ */
+declare function validateSafeUniqueString<T extends OMSSError>(value: string, name: string, ErrorType: ErrorConstructor<T>): Result<void, T>;
+//#endregion
+//#region src/utils/regexp.d.ts
+declare const SAFE_UNIQUE_STRING: RegExp;
+//#endregion
+export { type AudioTrack, BaseProvider, BaseResolver, type BaseSource, type CleaningFunction, ERR, type EmittedSource, type EmittedSubtitle, type Extractor, type GatheredSources, type GetSourcesOptions, HookRegistry, HookService, type MiddlewareHandler, type MiddlewareOperationMap, type NonEmptyArray, OK, type OMSSConfig, type OMSSConfiguredPluginType, OMSSError, OMSSExtractorError, type OMSSHooks, type OMSSId, OMSSPluginError, type OMSSPluginOptions, type OMSSPluginType, type OMSSProvider, OMSSProviderError, type OMSSProviderResult, type OMSSResolver, OMSSResolverError, OMSSServer, OMSSServerError, OMSSSourceGatheringError, type ObjectToClean, type ParsedOMSSId, PluginState, type ProviderCustomEventPayload, type ProviderDebugPayload, type ProviderDonePayload, type ProviderErrorPayload, type ProviderHooks, type ProviderInfoPayload, type ProviderResult, type ProviderResultEmitter, type ProviderServiceMiddleware, type ProviderServiceOperations, type ProviderSourcePayload, type ProviderSourcesMeta, type ProviderSubtitlePayload, type ProviderWarnPayload, type ResolverExecutionContext, type ResolverMetadata, type ResolverResult, type Result, SAFE_UNIQUE_STRING, type Source, type SourceQuality, type SourceServiceMiddleware, type SourceServiceOperations, type SourceTypes, type Subtitle, type SubtitleFormat, type UnknownPluginType, type UnknownProvider, parseOMSSId, validateSafeUniqueString };
+//# sourceMappingURL=index.d.mts.map