@omss/core 0.0.2-beta.0

package/dist/index.mjs

@@ -0,0 +1,1378 @@
+//#region src/features/hooks/HookRegistry.ts
+/**
+* Hook Registry
+*
+* Manages lifecycle hooks for OMSS events.
+*/
+var HookRegistry = class {
+	/**
+	* Map storing arrays of hook handlers for each hook name.
+	*/
+	#hooks = /* @__PURE__ */ new Map();
+	/**
+	* Get all registered hooks immutable.
+	* @dangerous - Be careful with this. what you are doing might cause side effects.
+	*/
+	get hooks() {
+		return this.#hooks;
+	}
+	/**
+	* Clear all registered hooks.
+	* @dangerous - Be careful with this. Might cause side effects.
+	*/
+	reset() {
+		return this.#hooks.clear();
+	}
+	/**
+	* 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.
+	*/
+	async run(name, payload) {
+		const fns = this.#hooks.get(name) ?? [];
+		for (const fn of fns) await fn(payload);
+	}
+	/**
+	* Add a hook handler for a lifecycle event.
+	* @param name - The hook name (key of THooks).
+	* @param cb - The hook handler function.
+	*/
+	add(name, cb) {
+		const existing = this.#hooks.get(name) ?? [];
+		this.#hooks.set(name, [...existing, cb]);
+	}
+};
+//#endregion
+//#region src/features/hooks/HookService.ts
+var HookService = class {
+	#hookRegistry;
+	constructor(hookRegistry = new HookRegistry()) {
+		this.#hookRegistry = hookRegistry;
+	}
+	/**
+	* 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() {
+		return this.#hookRegistry.hooks;
+	}
+	/**
+	* 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(name, cb) {
+		this.#hookRegistry.add(name, cb);
+	}
+	/**
+	* Clear all registered hooks.
+	* @dangerous - Be careful with this. Might cause side effects.
+	*/
+	reset() {
+		return this.#hookRegistry.reset();
+	}
+	/**
+	* Get the hook registry.
+	*
+	* This is only exposed for internal purposes and should not be accessed in consumer projects.
+	* @dangerous
+	* @internal
+	*/
+	__getRegistry() {
+		return this.#hookRegistry;
+	}
+};
+//#endregion
+//#region src/features/plugins/plugin-state.ts
+/**
+* The states of which a plugin can be.
+*/
+let PluginState = /* @__PURE__ */ function(PluginState) {
+	PluginState[PluginState["Registering"] = 0] = "Registering";
+	PluginState[PluginState["Registered"] = 1] = "Registered";
+	PluginState[PluginState["Unavailable"] = 2] = "Unavailable";
+	return PluginState;
+}({});
+//#endregion
+//#region src/utils/error.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.
+*/
+var OMSSError = class extends Error {
+	/**
+	* Create a new OMSSError.
+	* @param message - Error message
+	* @param options - Additional options for the error
+	*/
+	constructor(message, options) {
+		super(message, options);
+		this.name = this.constructor.name;
+	}
+};
+/**
+* Returned when an error gets Returned in the OMSSServer class.
+*
+* @example
+* return ERR(OMSSServerError('config.name must be a non-empty string', {cause: config}))
+*/
+var OMSSServerError = class extends OMSSError {};
+/**
+* Returned during plugin registration or execution.
+*
+* @example
+* return ERR(OMSSPluginError(`Plugin "${name}" is already registered`, { cause: plugin }))
+*/
+var OMSSPluginError = class extends OMSSError {};
+/**
+* Returned during resolver registration or ID resolution.
+*
+* @example
+* return ERR(OMSSResolverError(`No resolver found for namespace "xyz"`, { cause: rawId }))
+*/
+var OMSSResolverError = class extends OMSSError {};
+/**
+* Returned during provider registration or source fetching.
+*
+* @example
+* return ERR(OMSSProviderError('Provider must have at least one resolver', { cause: provider }))
+*/
+var OMSSProviderError = class 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 }))
+*/
+var OMSSExtractorError = class extends OMSSError {};
+/**
+* Returned when something/several things fail during source gathering.
+*
+* @example
+* return ERR(OMSSSourceGatheringError('Failed to gather sources', { cause: providerResults }))
+*/
+var OMSSSourceGatheringError = class extends OMSSError {};
+//#endregion
+//#region src/utils/regexp.ts
+/**
+* Regex for validating namespace names.
+*/
+const SAFE_UNIQUE_STRING_PATTERN = "[a-z0-9-]+";
+const SAFE_UNIQUE_STRING = new RegExp(`^${SAFE_UNIQUE_STRING_PATTERN}$`);
+/**
+* Regex for matching media formats by keyword or file extension.
+*
+* Matches:
+* - format keywords (`hls`, `dash`, `mp4`, etc.)
+* - common media file extensions
+* - extensions followed by URL query strings, fragments, paths, or the end of the URL
+*/
+const HLS_REGEX = /\bhls\b|\.(?:m3u8|ts)(?:$|[\/?#])/i;
+const MP4_REGEX = /\bmp4\b|\.mp4(?:$|[\/?#])/i;
+const DASH_REGEX = /\bdash\b|\.(?:mpd|m4a)(?:$|[\/?#])/i;
+const MKV_REGEX = /\bmkv\b|\.mkv(?:$|[\/?#])/i;
+const VTT_REGEX = /\bvtt\b|\.vtt(?:$|[\/?#])/i;
+const SRT_REGEX = /\bsrt\b|\.srt(?:$|[\/?#])/i;
+/**
+* Regex for validating a single catalog entry value.
+*
+* A catalog entry must be either exactly `"*"` (wildcard — provider supports
+* all IDs in the namespace) or a safe unique string.
+*
+* Mixing `"*"` with other entries in the same catalog array is not allowed
+* and is validated separately at registration time.
+*/
+const CATALOG_ENTRY = new RegExp(`^(?:\\*|${SAFE_UNIQUE_STRING_PATTERN})$`);
+//#endregion
+//#region src/utils/utils.ts
+function OK(value) {
+	if (arguments.length === 0) return { ok: true };
+	return {
+		ok: true,
+		value
+	};
+}
+/**
+* Convenience factory for a failed result.
+*/
+const ERR = (error) => ({
+	ok: false,
+	error
+});
+/**
+* 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
+*/
+function validateSafeUniqueString(value, name, ErrorType) {
+	if (!SAFE_UNIQUE_STRING.test(value)) return ERR(new ErrorType(`Invalid ${name} "${value}". Expected only letters (lowercase), numbers, and hyphens.`));
+	return OK();
+}
+//#endregion
+//#region src/features/plugins/PluginRegistry.ts
+/**
+* Registry responsible for executing and managing OMSS Plugins.
+*
+* Plugins are executed when added.
+*/
+var PluginRegistry = class {
+	/**
+	* States of plugin x
+	*/
+	#states = /* @__PURE__ */ new Map();
+	#server;
+	/**
+	* Registration stack used for circular dependency detection.
+	*/
+	#stack = [];
+	constructor(server) {
+		this.#server = server;
+	}
+	/**
+	* Adds and runs a plugin with its options.
+	*
+	* @typeParam T - Plugin options type.
+	* @param plugin - The plugin function to register.
+	* @param options - Plugin options or a factory function that resolves options.
+	*/
+	async add(plugin, options) {
+		const state = this.#states.get(plugin);
+		if (state === 0) return ERR(new OMSSPluginError(`Circular plugin dependency detected: ${[...this.#stack, plugin].map((p) => p.name).join(" -> ")}`));
+		if (state === 1) return ERR(new OMSSPluginError(`Plugin "${plugin.name}" is already registered`));
+		this.#states.set(plugin, 0);
+		this.#stack.push(plugin);
+		const resolved = typeof options === "function" ? options(this.#server) : options;
+		try {
+			if (plugin.length === 1) await plugin(this.#server);
+			else await plugin(this.#server, resolved);
+			this.#states.set(plugin, 1);
+			return OK(1);
+		} catch (err) {
+			this.#states.delete(plugin);
+			return ERR(err instanceof OMSSPluginError ? err : new OMSSPluginError(String(err), { cause: err }));
+		} finally {
+			this.#stack.pop();
+		}
+	}
+	/**
+	* Get the current plugin state.
+	*/
+	getState(plugin) {
+		return this.#states.get(plugin) ?? 2;
+	}
+};
+//#endregion
+//#region src/features/plugins/PluginService.ts
+/**
+* The public API for managing OMSS plugins.
+*/
+var PluginService = class {
+	#pluginRegistry;
+	#hookRegistry;
+	#insideBeforePluginRegister = false;
+	constructor(omssServer, pluginRegistry, hookRegistry) {
+		this.#pluginRegistry = pluginRegistry;
+		this.#hookRegistry = hookRegistry;
+	}
+	/**
+	* Registers an OMSS plugin that can take a config into the system, but does not need to.
+	* @param plugin - Plugin implementation
+	* @param options - Plugin configuration
+	*/
+	async register(plugin, options) {
+		if (this.#insideBeforePluginRegister) return ERR(new OMSSPluginError("Plugins cannot be registered during beforePluginRegister"));
+		this.#insideBeforePluginRegister = true;
+		try {
+			await this.#hookRegistry.run("beforePluginRegister", {
+				plugin,
+				options
+			});
+		} finally {
+			this.#insideBeforePluginRegister = false;
+		}
+		const result = await this.#pluginRegistry.add(plugin, options);
+		if (!result.ok) {
+			await this.#hookRegistry.run("pluginRegisterFailed", {
+				plugin,
+				options,
+				error: result.error
+			});
+			return result;
+		}
+		await this.#hookRegistry.run("afterPluginRegister", {
+			plugin,
+			options
+		});
+		return result;
+	}
+	/**
+	* 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) {
+		return this.#pluginRegistry.getState(plugin);
+	}
+};
+//#endregion
+//#region src/features/resolvers/utils.ts
+/**
+* Parses an OMSS ID in the form `namespace:value_1[:value_2[:...]]`.
+*/
+function parseOMSSId(id) {
+	if (/\s/.test(id)) return ERR(new OMSSResolverError(`Invalid OMSS ID "${id}": cannot contain whitespace`));
+	const parts = id.split(":");
+	if (parts.length < 2) return ERR(new OMSSResolverError(`Invalid OMSS ID "${id}": missing namespace separator ":"`));
+	const [namespace, ...values] = parts;
+	if (!namespace) return ERR(new OMSSResolverError(`Invalid OMSS ID "${id}": namespace cannot be empty`));
+	const req = validateSafeUniqueString(namespace, "OMSS namespace", OMSSResolverError);
+	if (!req.ok) return ERR(req.error);
+	for (const [i, value] of values.entries()) if (value.length === 0) return ERR(new OMSSResolverError(`Invalid OMSS ID "${id}": value ${i + 1} cannot be empty`));
+	return OK({
+		namespace,
+		values: values.map((value) => decodeURIComponent(value)),
+		raw: id
+	});
+}
+//#endregion
+//#region src/features/providers/ProviderResultEmitter.ts
+/**
+* Creates a fresh `ProviderResultEmitter` instance scoped to a single
+* `getSources()` execution.
+*
+* A new emitter MUST be created per provider call. Emitters hold internal,
+* mutable state (accumulated sources/subtitles/errors) via closures, so
+* reusing a single emitter across concurrent provider executions would
+* cause data from one provider to leak into another's response.
+*
+* @param provider - The provider instance for which this emitter is being created.
+* @param hookReg - The hook registry instance for managing hooks.
+* @param cleaningFunc - A function to clean up source/subtitle URLs and headers.
+* @param id - The parsed OMSS ID of the current request.
+* @returns A new `ProviderResultEmitter` bound to this execution.
+*
+*/
+function createProviderResultEmitter(provider, hookReg, cleaningFunc, id) {
+	/**
+	* Accumulated sources emitted via `source()` during this execution.
+	* Flushed into the final result when `done()` is called.
+	*/
+	const sources = [];
+	/**
+	* Accumulated subtitles emitted via `subtitle()` during this execution.
+	* Subtitles are intentionally NOT linked to any source or audio track,
+	* so they live in their own flat array regardless of how many sources
+	* were emitted.
+	*/
+	const subtitles = [];
+	/**
+	* Accumulated NON-fatal errors emitted via `error()` during this execution.
+	* These are returned alongside successful results (via `done()`) so
+	* that partial failures (e.g. "server 2 of 3 failed") don't discard
+	* otherwise-valid sources.
+	*/
+	const errors = [];
+	return {
+		/**
+		* 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) {
+					if (HLS_REGEX.test(possibleType)) return "hls";
+					else if (MP4_REGEX.test(possibleType)) return "mp4";
+					else if (DASH_REGEX.test(possibleType)) return "dash";
+					else if (MKV_REGEX.test(possibleType)) return "mkv";
+					else return "hls";
+				},
+				/**
+				* Parse a string into a possible source quality.
+				* @param possibleQuality - The string to parse
+				*/
+				parseQuality(possibleQuality) {
+					if (!possibleQuality) return "Auto";
+					const value = possibleQuality.toLowerCase().trim().replace(/_/g, " ").replace(/-/g, " ");
+					if (/\b(8k|uhd\s*8k|4320p)\b/.test(value)) return "8K";
+					if (/\b(4k|uhd|ultra\s*hd|2160p)\b/.test(value)) return "4K";
+					if (/\b(qhd|2k|1440p|2560x1440)\b/.test(value)) return "QHD";
+					if (/\b(fhd|full\s*hd|1080p|1920x1080)\b/.test(value)) return "FHD";
+					if (/\b(hd|720p|1280x720)\b/.test(value)) return "HD";
+					if (/\b(sd|480p|576p|360p|240p)\b/.test(value)) return "SD";
+					const resolutionMatch = value.match(/(\d{3,4})(?:p|x\d{3,4})?/);
+					if (resolutionMatch) {
+						const resolution = Number(resolutionMatch[1]);
+						if (resolution >= 4320) return "8K";
+						if (resolution >= 2160) return "4K";
+						if (resolution >= 1440) return "QHD";
+						if (resolution >= 1080) return "FHD";
+						if (resolution >= 720) return "HD";
+						if (resolution > 0) return "SD";
+					}
+					const bitrateMatch = value.match(/(\d+(?:\.\d+)?)\s*(mbps|kbps)/);
+					if (bitrateMatch) {
+						const bitrate = Number(bitrateMatch[1]);
+						const mbps = bitrateMatch[2] === "kbps" ? bitrate / 1e3 : bitrate;
+						if (mbps >= 25) return "4K";
+						if (mbps >= 8) return "FHD";
+						if (mbps >= 3) return "HD";
+						return "SD";
+					}
+					return "Auto";
+				}
+			},
+			/**
+			* Utilities for parsing metadata of subtitles
+			*/
+			subtitle: { 
+			/**
+			* Parse a string into a possible subtitle format.
+			* @param possibleFormat - The string to parse
+			*/
+parseFormat(possibleFormat) {
+				if (VTT_REGEX.test(possibleFormat)) return "vtt";
+				else if (SRT_REGEX.test(possibleFormat)) return "srt";
+				else return "vtt";
+			} }
+		},
+		/**
+		* Emits a custom, provider-defined action/event.
+		*
+		* @param action - A custom event name (e.g. "cache.hit").
+		* @param data - Arbitrary payload associated with the event.
+		*/
+		emit(action, data) {
+			if (/\s/.test(action) || Object.keys(this).includes(action)) return;
+			hookReg.run(action, {
+				data,
+				provider,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		/**
+		* Logs verbose debug information. Intended for development/troubleshooting
+		* only and should be stripped or gated behind a debug flag in production.
+		*
+		* @param args - Values to log, forwarded as-is (same semantics as `console.debug`).
+		*/
+		debug(...args) {
+			hookReg.run("debug", {
+				provider,
+				args,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		/**
+		* Logs general informational messages about provider execution
+		* (e.g. "Fetched media", "Cache miss, fetching from upstream").
+		*
+		* @param args - Values to log.
+		*/
+		info(...args) {
+			hookReg.run("info", {
+				provider,
+				args,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		/**
+		* Logs a non-fatal warning. Use this for degraded-but-recoverable
+		* situations (e.g. "missing quality metadata, defaulting to Auto").
+		*
+		* @param args - Values to log.
+		*/
+		warn(...args) {
+			hookReg.run("warn", {
+				provider,
+				args,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		/**
+		* Records a NON-fatal error. The provider continues executing after
+		* calling this — use `fatal()` instead if the provider cannot continue.
+		*
+		* The error is accumulated and returned to the requestor as part of
+		* the `diagnostics`/`errors` field once `done()` is called, allowing
+		* partial success (e.g. some sources found despite one upstream
+		* server failing).
+		*
+		* @param error - The error to record. Will be surfaced to the client.
+		*/
+		error(error) {
+			errors.push(error);
+			hookReg.run("error", {
+				provider,
+				error,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		/**
+		* Emits a single resolved source.
+		*
+		* @param source - The fully-formed source object to emit.
+		*/
+		source(source) {
+			const cleanedSource = { ...source };
+			const cleaned = cleaningFunc({
+				url: cleanedSource.url,
+				header: cleanedSource.header
+			});
+			cleanedSource.url = cleaned.url;
+			cleanedSource.header = cleaned.header;
+			if ("audioTracks" in cleanedSource && cleanedSource.audioTracks) {
+				const [first, ...rest] = cleanedSource.audioTracks;
+				cleanedSource.audioTracks = [{
+					...first,
+					...cleaningFunc({
+						url: first.url,
+						header: first.header
+					})
+				}, ...rest.map((track) => ({
+					...track,
+					...cleaningFunc({
+						url: track.url,
+						header: track.header
+					})
+				}))];
+			}
+			const fullSource = {
+				...cleanedSource,
+				provider: {
+					id: provider.id,
+					name: provider.name
+				}
+			};
+			sources.push(fullSource);
+			hookReg.run("source", {
+				provider,
+				source: fullSource,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		/**
+		* Emits a single subtitle track.
+		*
+		* @param subtitle - The subtitle object to emit.
+		*/
+		subtitle(subtitle) {
+			const { url, header } = cleaningFunc({
+				url: subtitle.url,
+				header: subtitle.header
+			});
+			subtitle.url = url;
+			subtitle.header = header;
+			const fullSub = {
+				...subtitle,
+				provider: {
+					id: provider.id,
+					name: provider.name
+				}
+			};
+			subtitles.push(fullSub);
+			hookReg.run("subtitle", {
+				provider,
+				subtitle: fullSub,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		/**
+		* Immediately aborts provider execution with a fatal error.
+		*
+		* @param error - The fatal error describing why the provider could not proceed.
+		* @returns An `ERR` result wrapping the given error.
+		*/
+		fatal(error) {
+			const accumulatedError = new AggregateError([error, ...errors], error.message, { cause: error.cause });
+			const finalErr = new OMSSProviderError(accumulatedError.message, { cause: accumulatedError });
+			hookReg.run("error", {
+				provider,
+				error: finalErr,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return ERR(finalErr);
+		},
+		/**
+		* Signals that the provider has finished emitting sources/subtitles
+		* and finalizes the result.
+		*
+		* @returns An `OK` result containing all accumulated sources,
+		*          subtitles, and non-fatal errors for this execution.
+		*/
+		done() {
+			const result = {
+				sources,
+				subtitles,
+				errors
+			};
+			hookReg.run("done", {
+				provider,
+				result,
+				id,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return OK(result);
+		}
+	};
+}
+//#endregion
+//#region src/features/source/SourceCore.ts
+/**
+* Internal source gathering core.
+*
+* Handles OMSS ID parsing, provider lookup, resolver-level deduplication,
+* provider execution, and final result aggregation.
+*
+* This class intentionally does not know about OMSS Hooks, middleware, or in-flight
+* request sharing. Those concerns belong to SourceService.
+*/
+var SourceCore = class {
+	#providerRegistry;
+	#extractorService;
+	#omssServer;
+	constructor(omssServer, providerRegistry, extractorService) {
+		this.#omssServer = omssServer;
+		this.#providerRegistry = providerRegistry;
+		this.#extractorService = extractorService;
+	}
+	/**
+	* Gather sources for a single OMSS ID.
+	*
+	* @param omssId - Raw OMSS identifier.
+	* @param opts - Optional source gathering parameters.
+	* @param providerHookRegistry - Hook registry for provider hooks.
+	* @param cleaningFunction - Optional custom function to clean url's and headers
+	* @returns Aggregated provider results or a source gathering error.
+	*/
+	async getSources(omssId, opts, providerHookRegistry, cleaningFunction) {
+		const parsed = parseOMSSId(omssId);
+		if (!parsed.ok) return ERR(new OMSSSourceGatheringError(`Failed to parse OMSS id "${omssId}": ${parsed.error.message}`, { cause: parsed.error }));
+		const providers = opts.providerId ? this.#providerRegistry.getAll((p) => p.id === opts.providerId && p.resolver.namespace === parsed.value.namespace) : this.#providerRegistry.getAll((p) => p.resolver.namespace === parsed.value.namespace);
+		if (providers.length === 0) return ERR(new OMSSSourceGatheringError(`No providers found for namespace "${parsed.value.namespace}"` + (opts.providerId ? ` and provider "${opts.providerId}"` : "")));
+		const signal = opts.abortSignal ?? new AbortController().signal;
+		const ctx = {
+			server: this.#omssServer,
+			signal
+		};
+		/**
+		* Resolver-level deduplication: multiple providers that share the same
+		* resolver run that resolver only once, then share the result.
+		*/
+		const resolverCache = /* @__PURE__ */ new Map();
+		/**
+		* Get resolver metadata for a provider, reusing the same resolver
+		* promise when multiple providers share the same resolver.
+		*
+		* @param provider - Provider whose resolver metadata should be loaded.
+		* @returns Resolver metadata or a source gathering error.
+		*/
+		const getResolvedMeta = (provider) => {
+			const resolverKey = `${provider.resolver.namespace}:${provider.resolver.name}`;
+			let promise = resolverCache.get(resolverKey);
+			if (!promise) {
+				promise = (async () => {
+					if (signal.aborted) return ERR(new OMSSSourceGatheringError("Operation aborted"));
+					const result = await provider.resolver.resolve(parsed.value, ctx);
+					if (!result.ok) return ERR(new OMSSSourceGatheringError(`Resolver failed for ${resolverKey}: ${result.error.message}`, { cause: result.error }));
+					return OK(result.value);
+				})();
+				resolverCache.set(resolverKey, promise);
+			}
+			return promise;
+		};
+		/**
+		* Resolve sources for a single provider.
+		*
+		* @param provider - Provider to execute.
+		* @returns Provider result or a source gathering error.
+		*/
+		const resolveForProvider = async (provider) => {
+			if (signal.aborted) return ERR(new OMSSSourceGatheringError("Operation aborted"));
+			if (!await provider.supportsId(parsed.value)) return OK({
+				sources: [],
+				subtitles: [],
+				errors: [new OMSSProviderError(`Provider "${provider.id}" did not support this id: "${parsed.value.raw}"`)]
+			});
+			if (signal.aborted) return ERR(new OMSSSourceGatheringError("Operation aborted"));
+			const metaResult = await getResolvedMeta(provider);
+			if (!metaResult.ok) return metaResult;
+			if (signal.aborted) return ERR(new OMSSSourceGatheringError("Operation aborted"));
+			const resultEmitter = createProviderResultEmitter(provider, providerHookRegistry.__getRegistry(), cleaningFunction, parsed.value);
+			return provider.getSources({
+				utils: {
+					omssId: parsed.value,
+					abortSignal: signal,
+					findExtractor: this.#extractorService.find
+				},
+				meta: metaResult.value
+			}, resultEmitter);
+		};
+		const settled = await Promise.allSettled(providers.map((provider) => resolveForProvider(provider)));
+		if (signal.aborted) return ERR(new OMSSSourceGatheringError("Operation aborted"));
+		const allSources = [];
+		const allSubtitles = [];
+		const unexpectedErrors = [];
+		const omssErrors = [];
+		let hasSuccess = false;
+		for (const item of settled) {
+			if (item.status === "rejected") {
+				omssErrors.push(new OMSSSourceGatheringError(`Provider execution failed: ${item.reason instanceof Error ? item.reason.message : String(item.reason)}`, { cause: item.reason instanceof Error ? item.reason : void 0 }));
+				unexpectedErrors.push(item.reason);
+				continue;
+			}
+			const res = item.value;
+			if (res.ok) {
+				hasSuccess = true;
+				allSources.push(...res.value.sources);
+				allSubtitles.push(...res.value.subtitles);
+				omssErrors.push(...res.value.errors);
+				continue;
+			}
+			omssErrors.push(res.error);
+		}
+		if (!hasSuccess) return ERR(new OMSSSourceGatheringError(`All providers failed for namespace "${parsed.value.namespace}" and id: "${parsed.value.raw}"`, { cause: new AggregateError([...omssErrors, ...unexpectedErrors], "Multiple failures detected") }));
+		return OK({
+			sources: allSources,
+			subtitles: allSubtitles,
+			errors: omssErrors
+		});
+	}
+};
+//#endregion
+//#region src/utils/AsyncDeduper.ts
+/**
+* Generic helper for deduplicating concurrent asynchronous work by key.
+*
+* When the same key is requested multiple times while a request is still in
+* flight, all callers receive the same Promise. Once the Promise settles, the
+* key is removed automatically so the next request starts fresh.
+*
+* @typeParam TKey - Cache key type.
+* @typeParam TValue - Promise resolution type.
+*/
+var AsyncDeduper = class {
+	#entries = /* @__PURE__ */ new Map();
+	/**
+	* Returns the current in-flight Promise for a key, if one exists.
+	*
+	* @param key - In-flight request key.
+	* @returns Existing Promise or undefined.
+	*/
+	get(key) {
+		return this.#entries.get(key);
+	}
+	/**
+	* Check whether a key currently has an in-flight Promise.
+	*
+	* @param key - In-flight request key.
+	* @returns True if the key is currently in flight.
+	*/
+	has(key) {
+		return this.#entries.has(key);
+	}
+	/**
+	* Delete a key manually.
+	*
+	* @param key - In-flight request key.
+	* @returns True if an entry existed and was removed.
+	*/
+	delete(key) {
+		return this.#entries.delete(key);
+	}
+	/**
+	* Clear all tracked in-flight requests.
+	*/
+	clear() {
+		this.#entries.clear();
+	}
+	/**
+	* Run a Promise factory for a key, reusing an existing in-flight Promise
+	* when available.
+	*
+	* @param key - In-flight request key.
+	* @param factory - Factory that creates the Promise when no request exists yet.
+	* @returns Shared or newly created Promise.
+	*/
+	run(key, factory) {
+		const existing = this.#entries.get(key);
+		if (existing) return existing;
+		const promise = factory().finally(() => {
+			this.#entries.delete(key);
+		});
+		this.#entries.set(key, promise);
+		return promise;
+	}
+};
+//#endregion
+//#region src/utils/middleware.ts
+/**
+* Reusable typed middleware runner.
+*/
+var MiddlewareRunner = class {
+	#handlers = {};
+	/**
+	* Register middleware for a specific operation.
+	*
+	* @param method - Operation name.
+	* @param handler - Middleware handler.
+	*/
+	use(method, handler) {
+		(this.#handlers[method] ??= []).push(handler);
+	}
+	/**
+	* Run middleware chain for a specific operation.
+	*
+	* @param method - Operation name.
+	* @param context - Operation context payload.
+	* @param finalHandler - Final function to execute after middleware.
+	* @returns The operation result.
+	*/
+	run(method, context, finalHandler) {
+		const handlers = this.#handlers[method] ?? [];
+		let index = -1;
+		const dispatch = (position) => {
+			if (position <= index) return Promise.reject(/* @__PURE__ */ new Error("next() called multiple times"));
+			index = position;
+			const handler = handlers[position];
+			if (!handler) return finalHandler();
+			return handler(context, () => dispatch(position + 1));
+		};
+		return dispatch(0);
+	}
+};
+//#endregion
+//#region src/features/source/SourceService.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}.
+*/
+var SourceService = class {
+	#hookRegistry;
+	#core;
+	/**
+	* Middleware runner for SourceService operations.
+	*/
+	#middleware = new MiddlewareRunner();
+	/**
+	* Deduplicates concurrent getSources requests by request key.
+	*/
+	#inFlight = new AsyncDeduper();
+	constructor(omssServer, providerRegistry, hookRegistry, extractorService) {
+		this.#hookRegistry = hookRegistry;
+		this.#core = new SourceCore(omssServer, providerRegistry, extractorService);
+	}
+	get cleaningFunction() {
+		return this.#cleaningFunction;
+	}
+	set cleaningFunction(fn) {
+		this.#cleaningFunction = fn;
+	}
+	/**
+	* 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(method, handler) {
+		this.#middleware.use(method, handler);
+	}
+	/**
+	* 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.
+	*/
+	async getSources(omssId, options = {}) {
+		return this.#middleware.run("getSources", {
+			omssId,
+			options
+		}, () => this.#internalGetSources(omssId, options));
+	}
+	/**
+	* Get and set the cleaning function for the source core.
+	*/
+	#cleaningFunction = (obj) => obj;
+	/**
+	* Internal wrapper around source gathering.
+	*
+	* Runs lifecycle hooks and deduplicates concurrent requests before
+	* delegating to {@link SourceCore}.
+	*
+	* @param omssId - OMSS identifier.
+	* @param options - Optional source gathering parameters.
+	* @returns Aggregated provider results or a source gathering error.
+	*/
+	async #internalGetSources(omssId, options) {
+		await this.#hookRegistry.run("beforeGetSources", {
+			omssId,
+			providerId: options.providerId
+		});
+		const inFlightKey = this.#getInFlightKey(omssId, options.providerId);
+		const result = await this.#inFlight.run(inFlightKey, () => this.#core.getSources(omssId, options, options.providerHookService ?? new HookService(), options.cleaningFunction ?? this.cleaningFunction));
+		if (result.ok) {
+			await this.#hookRegistry.run("afterGetSources", {
+				omssId,
+				providerId: options.providerId,
+				result: result.value
+			});
+			return this.#middleware.run("afterGetSources", {
+				omssId,
+				options,
+				result
+			}, () => Promise.resolve(result));
+		}
+		await this.#hookRegistry.run("getSourcesFailed", {
+			omssId,
+			providerId: options.providerId,
+			error: result.error
+		});
+		return result;
+	}
+	/**
+	* Build the stable in-flight key for a getSources request.
+	*
+	* @param omssId - OMSS identifier.
+	* @param providerId - Optional provider filter.
+	* @returns Unique in-flight request key.
+	*/
+	#getInFlightKey(omssId, providerId) {
+		return `${omssId}|${providerId ?? ""}`;
+	}
+};
+//#endregion
+//#region src/features/providers/ProviderRegistry.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.
+*/
+var ProviderRegistry = class {
+	/**
+	* Internal map of registered providers, keyed by provider ID.
+	*/
+	#providers = /* @__PURE__ */ new Map();
+	/**
+	* 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.
+	*/
+	async add(provider) {
+		if (this.#providers.has(provider.id)) return ERR(new OMSSProviderError(`Provider "${provider.id}" is already registered`));
+		const valProvIdReq = validateSafeUniqueString(provider.id, "provider ID", OMSSProviderError);
+		if (!valProvIdReq.ok) return ERR(valProvIdReq.error);
+		const valResolverNamespaceReq = validateSafeUniqueString(provider.resolver.namespace, "resolver namespace for resolver with name: \"" + provider.resolver.name + "\" and id:", OMSSProviderError);
+		if (!valResolverNamespaceReq.ok) return ERR(valResolverNamespaceReq.error);
+		if (this.getAll().some((p) => p.resolver.namespace === provider.resolver.namespace && p.resolver !== provider.resolver)) return ERR(new OMSSProviderError(`Resolver namespace "${provider.resolver.namespace}" is already registered by another provider and another resolver. Use one resolver per namespace.`));
+		if (provider.catalog) {
+			const entries = await provider.catalog();
+			const hasWildcard = entries.includes("*");
+			const hasOther = entries.some((id) => id !== "*");
+			if (hasWildcard && hasOther) return ERR(new OMSSProviderError(`Provider "${provider.id}" catalog contains "*" mixed with other IDs. Use either a single "*" or a list of valid IDs.`));
+			for (const id of entries) if (!CATALOG_ENTRY.test(id)) return ERR(new OMSSProviderError(`Provider "${provider.id}" catalog contains an invalid entry "${id}". Entries must be non-empty strings with no whitespace, or "*".`));
+		}
+		this.#providers.set(provider.id, provider);
+		return OK(provider);
+	}
+	/**
+	* Retrieves a registered provider by its ID.
+	*
+	* @param id - The unique provider ID.
+	* @returns The provider instance, or `undefined` if not found.
+	*/
+	get(id) {
+		return this.#providers.get(id);
+	}
+	/**
+	* Returns all registered providers.
+	*/
+	getAll(filter) {
+		if (filter) return [...this.#providers.values()].filter(filter);
+		return [...this.#providers.values()];
+	}
+	/**
+	* Returns whether a provider with the given ID is registered.
+	*
+	* @param id - The unique provider ID.
+	*/
+	has(id) {
+		return this.#providers.has(id);
+	}
+};
+//#endregion
+//#region src/features/providers/ProviderService.ts
+/**
+* The public API for managing OMSS Providers.
+*/
+var ProviderService = class {
+	#providerRegistry;
+	#hookRegistry;
+	#middleware = new MiddlewareRunner();
+	#insideBeforeProviderRegister = false;
+	constructor(providerRegistry, hookRegistry) {
+		this.#providerRegistry = providerRegistry;
+		this.#hookRegistry = hookRegistry;
+	}
+	/**
+	* Adds middleware to the `register` pipeline.
+	* Middlewares run in insertion order, after hooks and before the
+	* actual registry `add()` call.
+	*/
+	use(method, handler) {
+		this.#middleware.use(method, handler);
+		return this;
+	}
+	/**
+	* Registers a provider into the system.
+	*/
+	async register(provider) {
+		if (this.#insideBeforeProviderRegister) return ERR(new OMSSProviderError("Providers cannot be registered during beforeProviderRegister"));
+		this.#insideBeforeProviderRegister = true;
+		try {
+			await this.#hookRegistry.run("beforeProviderRegister", { provider });
+		} finally {
+			this.#insideBeforeProviderRegister = false;
+		}
+		const result = await this.#middleware.run("register", { provider }, () => this.#providerRegistry.add(provider));
+		if (!result.ok) {
+			await this.#hookRegistry.run("providerRegisterFailed", {
+				provider,
+				error: result.error
+			});
+			return ERR(result.error);
+		}
+		await this.#hookRegistry.run("afterProviderRegister", { provider });
+		return result;
+	}
+	/**
+	* 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) {
+		return this.#providerRegistry.get(id);
+	}
+	/**
+	* Returns all registered providers.
+	* @param filter - Optional filter function to apply to providers.
+	*/
+	getAll(filter) {
+		return this.#providerRegistry.getAll(filter);
+	}
+	/**
+	* Returns whether a provider with the given ID has been registered.
+	*
+	* @param id - The provider ID to check.
+	*/
+	has(id) {
+		return this.#providerRegistry.has(id);
+	}
+	/**
+	* 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", "..."]`.
+	*/
+	async catalog() {
+		const allProviders = this.getAll();
+		const result = /* @__PURE__ */ new Map();
+		await Promise.all(allProviders.map(async (provider) => {
+			if (!provider.catalog) return;
+			const namespace = provider.resolver.namespace;
+			const entries = await provider.catalog();
+			if (result.get(namespace)?.[0] === "*") return;
+			if (entries.includes("*")) {
+				result.set(namespace, ["*"]);
+				return;
+			}
+			const existing = result.get(namespace) ?? [];
+			const merged = Array.from(/* @__PURE__ */ new Set([...existing, ...entries]));
+			result.set(namespace, merged);
+		}));
+		return OK(result);
+	}
+	/**
+	* 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.
+	*/
+	async catalogForNamespace(namespace) {
+		const providers = this.getAll((p) => p.resolver.namespace === namespace);
+		if (providers.length === 0) return ERR(new OMSSProviderError(`No providers registered for namespace "${namespace}"`));
+		const result = [];
+		for (const provider of providers) {
+			if (!provider.catalog) continue;
+			const entries = await provider.catalog();
+			if (entries.includes("*")) return OK(["*"]);
+			for (const id of entries) if (!result.includes(id)) result.push(id);
+		}
+		return result.length > 0 ? OK(result) : ERR(new OMSSProviderError(`No catalog data available for namespace "${namespace}"`));
+	}
+};
+//#endregion
+//#region src/features/extractors/ExtractorService.ts
+var ExtractorService = class {
+	#extractorRegistry;
+	#hookRegistry;
+	#insideBeforeRegisterExtractor = false;
+	constructor(extractorRegistry, hookRegistry) {
+		this.#extractorRegistry = extractorRegistry;
+		this.#hookRegistry = hookRegistry;
+	}
+	/**
+	* Get all registered extractors (read-only).
+	*/
+	get extractors() {
+		return OK(this.#extractorRegistry.extractors);
+	}
+	/**
+	* 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}.
+	*/
+	async find(url) {
+		await this.#hookRegistry.run("beforeFindExtractor", { url });
+		const extractors = this.#extractorRegistry.extractors;
+		const results = await Promise.all(extractors.map((extractor) => extractor.matcher(url)));
+		for (let i = 0; i < extractors.length; i++) if (results[i].ok) {
+			const extractor = extractors[i];
+			await this.#hookRegistry.run("afterFindExtractor", {
+				url,
+				extractor
+			});
+			return OK(extractor);
+		}
+		const error = new OMSSExtractorError(`No extractor found for URL "${url}"`);
+		await this.#hookRegistry.run("findExtractorFailed", {
+			url,
+			error
+		});
+		return ERR(error);
+	}
+	/**
+	* Register an extractor.
+	*
+	* @param extractor - Extractor to register.
+	*/
+	async register(extractor) {
+		if (this.#insideBeforeRegisterExtractor) return ERR(new OMSSExtractorError("Extractors cannot be registered during beforeRegisterExtractor"));
+		this.#insideBeforeRegisterExtractor = true;
+		try {
+			await this.#hookRegistry.run("beforeRegisterExtractor", { extractor });
+		} finally {
+			this.#insideBeforeRegisterExtractor = false;
+		}
+		try {
+			this.#extractorRegistry.add(extractor);
+		} catch (error) {
+			const extractorError = error instanceof OMSSExtractorError ? error : new OMSSExtractorError(error instanceof Error ? error.message : String(error));
+			await this.#hookRegistry.run("extractorRegisterFailed", {
+				extractor,
+				error: extractorError
+			});
+			return ERR(extractorError);
+		}
+		await this.#hookRegistry.run("afterRegisterExtractor", { extractor });
+		return OK();
+	}
+	/**
+	* Remove every registered extractor.
+	*/
+	reset() {
+		this.#extractorRegistry.reset();
+		return OK();
+	}
+	/**
+	* Determine whether an extractor has already been registered.
+	*
+	* @param extractor - Extractor to check.
+	*/
+	has(extractor) {
+		return OK(this.#extractorRegistry.has(extractor));
+	}
+	/**
+	* Remove an extractor.
+	*
+	* @param extractor - Extractor to remove.
+	* @returns Whether the extractor was removed.
+	*/
+	remove(extractor) {
+		return OK(this.#extractorRegistry.remove(extractor));
+	}
+};
+//#endregion
+//#region src/features/extractors/ExtractorRegistry.ts
+/**
+* Extractor Registry
+*
+* Manages all extractors.
+*/
+var ExtractorRegistry = class {
+	/**
+	* Array of extractors.
+	*/
+	#extractors = Array();
+	/**
+	* Get all extractors.
+	*/
+	get extractors() {
+		return this.#extractors;
+	}
+	/**
+	* Clear all extractors.
+	*/
+	reset() {
+		this.#extractors.length = 0;
+	}
+	/**
+	* Add an extractor.
+	* @param extractor - Extractor to add.
+	*/
+	add(extractor) {
+		if (this.#extractors.some((e) => e === extractor)) return;
+		this.#extractors.push(extractor);
+	}
+	/**
+	* Check if an extractor is already registered.
+	* @param extractor - Extractor to check.
+	*/
+	has(extractor) {
+		return this.#extractors.includes(extractor);
+	}
+	/**
+	* Remove an extractor.
+	* @param extractor - Extractor to remove.
+	* @returns True if the extractor was removed, false otherwise.
+	*/
+	remove(extractor) {
+		if (!this.has(extractor)) return false;
+		this.#extractors.splice(this.#extractors.indexOf(extractor), 1);
+		return true;
+	}
+};
+//#endregion
+//#region src/core/server.ts
+/**
+* Core server class for OMSS.
+*/
+var OMSSServer = class {
+	hooks;
+	plugins;
+	providers;
+	sources;
+	extractors;
+	#config;
+	/**
+	* Creates a new OMSSServer instance.
+	*
+	* @param config - Immutable server configuration
+	*/
+	constructor(config) {
+		this.#config = config;
+		const hooksRegistry = new HookRegistry();
+		const extractorRegistry = new ExtractorRegistry();
+		const pluginRegistry = new PluginRegistry(this);
+		const providerRegistry = new ProviderRegistry();
+		this.hooks = new HookService(hooksRegistry);
+		this.extractors = new ExtractorService(extractorRegistry, hooksRegistry);
+		this.plugins = new PluginService(this, pluginRegistry, hooksRegistry);
+		this.providers = new ProviderService(providerRegistry, hooksRegistry);
+		this.sources = new SourceService(this, providerRegistry, hooksRegistry, this.extractors);
+	}
+	/**
+	* Get the OMSS Config from the constructor
+	* @returns the initialised OMSS Config
+	*/
+	get config() {
+		return this.#config;
+	}
+	/**
+	* 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(name, value, deps = []) {
+		if (Object.hasOwn(this, name)) return ERR(new OMSSServerError(`Decorator "${name}" already exists`, { cause: { existing: this[name] } }));
+		for (const dep of deps) if (!this.hasDecorator(dep)) return ERR(new OMSSServerError(`"${name}" depends on "${dep}", which does not exist`));
+		Object.defineProperty(this, name, {
+			value,
+			writable: false,
+			configurable: false,
+			enumerable: true
+		});
+		return OK(name);
+	}
+	/**
+	* 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) {
+		return Object.hasOwn(this, name);
+	}
+	/**
+	* 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(name) {
+		if (!Object.hasOwn(this, name)) return ERR(new OMSSServerError(`Decorator "${name}" not found`));
+		return OK(this[name]);
+	}
+};
+//#endregion
+//#region src/features/providers/BaseProvider.ts
+/**
+* Base class for all providers.
+*/
+var BaseProvider = class {};
+//#endregion
+//#region src/features/resolvers/BaseResolver.ts
+/**
+* Base class for all OMSS resolvers.
+*
+* Resolvers convert an OMSS ID into usable metadata for providers.
+*/
+var BaseResolver = class {};
+//#endregion
+export { BaseProvider, BaseResolver, ERR, HookRegistry, HookService, OK, OMSSError, OMSSExtractorError, OMSSPluginError, OMSSProviderError, OMSSResolverError, OMSSServer, OMSSServerError, OMSSSourceGatheringError, PluginState, SAFE_UNIQUE_STRING, parseOMSSId, validateSafeUniqueString };
+
+//# sourceMappingURL=index.mjs.map