@discord-player/plugin-host 8.0.0-dev.1 → 8.0.0-dev.2

package/dist/providers/lrclib.d.ts

@@ -0,0 +1,120 @@
+/** Search parameters supported by the LRCLIB API. */
+export interface LrcSearchParams {
+    /** Free-form query. Either `q` or `trackName` is required. */
+    q?: string;
+    /** Track title. Either `q` or `trackName` is required. */
+    trackName?: string;
+    /** Artist name filter. */
+    artistName?: string;
+    /** Album name filter. */
+    albumName?: string;
+}
+/** Parameters accepted by LRCLIB's exact lookup endpoints. */
+export interface LrcGetParams extends LrcSearchParams {
+    /** Track duration in seconds. */
+    duration?: number;
+}
+/** Lyrics record returned by LRCLIB search. */
+export interface LrcSearchResult {
+    /** LRCLIB record ID. */
+    id: number;
+    /** Display name supplied by LRCLIB. */
+    name: string;
+    /** Track title. */
+    trackName: string;
+    /** Artist name. */
+    artistName: string;
+    /** Album name. */
+    albumName: string;
+    /** Track duration in seconds. */
+    duration: number;
+    /** Whether the recording is instrumental. */
+    instrumental: boolean;
+    /** Plain lyric text, when available. */
+    plainLyrics: string;
+    /** Synchronized LRC text, when supplied by the service. */
+    syncedLyrics?: string;
+}
+/** Lyrics record returned by exact LRCLIB lookups. */
+/** Lyrics record returned by the LRCLIB exact lookup endpoints. */
+export type LrcGetResult = Omit<LrcSearchResult, 'name'>;
+/** LRCLIB API client with serialized requests and bounded retries. */
+export declare class LrcLib {
+    #private;
+    /** Player used to identify requests and publish debug messages. */
+    readonly player: {
+        version: string;
+        debug(message: string): void;
+    };
+    /** Base API URL. */
+    api: string;
+    /** Request timeout in milliseconds. */
+    timeout: number;
+    /** Maximum retry count for rate limits and server errors. */
+    retryLimit: number;
+    /**
+     * Create an LRCLIB client owned by one Player.
+     * @param player Player used to identify requests and publish debug messages.
+     */
+    constructor(
+    /** Player used to identify requests and publish debug messages. */
+    player: {
+        version: string;
+        debug(message: string): void;
+    });
+    /**
+     * Set the request timeout.
+     * @param timeout Positive request timeout in milliseconds.
+     */
+    setRequestTimeout(
+    /** Timeout in milliseconds. */
+    timeout: number): void;
+    /**
+     * Set the maximum retry count.
+     * @param limit Non-negative retry count for rate limits and server errors.
+     */
+    setRetryLimit(
+    /** Non-negative retry count. */
+    limit: number): void;
+    /**
+     * Get lyrics by exact track metadata.
+     * @param params Track title, artist, album, and optional duration.
+     */
+    get(
+    /** Exact lookup metadata. */
+    params: LrcGetParams): Promise<LrcGetResult>;
+    /**
+     * Get lyrics by LRCLIB record ID.
+     * @param id Numeric LRCLIB record ID.
+     */
+    getById(
+    /** Numeric LRCLIB record ID. */
+    id: `${number}` | number): Promise<LrcGetResult>;
+    /**
+     * Get cached lyrics by exact track metadata.
+     * @param params Track title, artist, album, and optional duration.
+     */
+    getCached(
+    /** Exact lookup metadata. */
+    params: LrcGetParams): Promise<LrcGetResult>;
+    /**
+     * Search LRCLIB for matching lyric records.
+     * @param params Free-form query or track and artist metadata.
+     */
+    search(
+    /** Search query or track and artist metadata. */
+    params: LrcSearchParams): Promise<LrcSearchResult[]>;
+    /**
+     * Send one serialized request to LRCLIB.
+     * @param path API path, with or without a leading slash.
+     * @param options Additional fetch options merged with the default GET request.
+     * @returns Parsed JSON response.
+     */
+    request<Result>(
+    /** API path, with or without a leading slash. */
+    path: string, 
+    /** Additional fetch options merged with the default GET request. */
+    options?: RequestInit): Promise<Result>;
+}
+/** Optional LRCLIB provider. No provider is installed by constructing a Player. */
+export declare const lrclibPlugin: (options?: Record<string, never> | undefined) => import("../plugins/types.js").PluginRegistration<Record<string, never>>;

package/dist/providers/lrclib.js

@@ -0,0 +1,183 @@
+import { definePlugin } from '../plugins/types.js';
+import { parseLyrics } from '../lyrics.js';
+function toSnakeCase(params) {
+    const result = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        const snake = key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+        result.set(snake, String(value));
+    }
+    return result;
+}
+function delayWait(ms, signal) {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', abort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+/** LRCLIB API client with serialized requests and bounded retries. */
+export class LrcLib {
+    player;
+    /** Base API URL. */
+    api = 'https://lrclib.net/api';
+    /** Request timeout in milliseconds. */
+    timeout = 15_000;
+    /** Maximum retry count for rate limits and server errors. */
+    retryLimit = 5;
+    #tail = Promise.resolve();
+    /**
+     * Create an LRCLIB client owned by one Player.
+     * @param player Player used to identify requests and publish debug messages.
+     */
+    constructor(
+    /** Player used to identify requests and publish debug messages. */
+    player) {
+        this.player = player;
+    }
+    /**
+     * Set the request timeout.
+     * @param timeout Positive request timeout in milliseconds.
+     */
+    setRequestTimeout(
+    /** Timeout in milliseconds. */
+    timeout) {
+        if (!Number.isFinite(timeout) || timeout <= 0)
+            throw new RangeError('Request timeout must be a positive finite number.');
+        this.timeout = timeout;
+    }
+    /**
+     * Set the maximum retry count.
+     * @param limit Non-negative retry count for rate limits and server errors.
+     */
+    setRetryLimit(
+    /** Non-negative retry count. */
+    limit) {
+        if (!Number.isInteger(limit) || limit < 0)
+            throw new RangeError('Retry limit must be a non-negative integer.');
+        this.retryLimit = limit;
+    }
+    /**
+     * Get lyrics by exact track metadata.
+     * @param params Track title, artist, album, and optional duration.
+     */
+    get(
+    /** Exact lookup metadata. */
+    params) {
+        return this.request(`get?${toSnakeCase(params)}`);
+    }
+    /**
+     * Get lyrics by LRCLIB record ID.
+     * @param id Numeric LRCLIB record ID.
+     */
+    getById(
+    /** Numeric LRCLIB record ID. */
+    id) {
+        return this.request(`get/${id}`);
+    }
+    /**
+     * Get cached lyrics by exact track metadata.
+     * @param params Track title, artist, album, and optional duration.
+     */
+    getCached(
+    /** Exact lookup metadata. */
+    params) {
+        return this.request(`get-cached?${toSnakeCase(params)}`);
+    }
+    /**
+     * Search LRCLIB for matching lyric records.
+     * @param params Free-form query or track and artist metadata.
+     */
+    search(
+    /** Search query or track and artist metadata. */
+    params) {
+        if (!params.q && !params.trackName)
+            throw new TypeError('Provide either q or trackName when searching lyrics.');
+        return this.request(`search?${toSnakeCase(params)}`);
+    }
+    /**
+     * Send one serialized request to LRCLIB.
+     * @param path API path, with or without a leading slash.
+     * @param options Additional fetch options merged with the default GET request.
+     * @returns Parsed JSON response.
+     */
+    async request(
+    /** API path, with or without a leading slash. */
+    path, 
+    /** Additional fetch options merged with the default GET request. */
+    options = {}) {
+        let release;
+        const turn = new Promise((resolve) => {
+            release = resolve;
+        });
+        const previous = this.#tail;
+        this.#tail = previous.then(() => turn);
+        await previous;
+        try {
+            const url = `${this.api}${path.startsWith('/') ? path : `/${path}`}`;
+            this.player.debug(`[LrcLib] Requesting ${path}`);
+            for (let attempt = 0;; attempt++) {
+                const response = await fetch(url, {
+                    method: 'GET',
+                    redirect: 'follow',
+                    ...options,
+                    signal: options.signal ?? AbortSignal.timeout(this.timeout),
+                    headers: {
+                        'User-Agent': `Discord-Player/${this.player.version}`,
+                        'Content-Type': 'application/json',
+                        ...options.headers,
+                    },
+                });
+                if (response.ok)
+                    return (await response.json());
+                if ((response.status === 429 || response.status >= 500) && attempt < this.retryLimit) {
+                    const retryAfter = Number(response.headers.get('retry-after'));
+                    const delay = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : Math.min(250 * 2 ** attempt, 4000);
+                    await delayWait(delay, options.signal);
+                    continue;
+                }
+                throw new Error(`LRCLIB request failed with HTTP ${response.status} ${response.statusText}.`);
+            }
+        }
+        finally {
+            release();
+        }
+    }
+}
+/** Optional LRCLIB provider. No provider is installed by constructing a Player. */
+export const lrclibPlugin = definePlugin({
+    id: 'org.lrclib',
+    setup(ctx) {
+        const client = new LrcLib({ version: 'plugin-host', debug: (message) => ctx.player.debug(message) });
+        ctx.on('lyrics.search', async ({ input }, { signal }) => {
+            const params = typeof input === 'string' ? { q: input } : { trackName: input.title, artistName: input.author };
+            const records = await client.request(`search?${toSnakeCase(params)}`, {
+                signal: AbortSignal.any([signal, AbortSignal.timeout(client.timeout)]),
+            });
+            return records.map((record) => ({
+                plain: record.plainLyrics
+                    ? { available: true, text: record.plainLyrics }
+                    : { available: false },
+                synced: record.syncedLyrics
+                    ? { available: true, lines: parseLyrics(record.syncedLyrics) }
+                    : { available: false },
+                metadata: {
+                    id: record.id,
+                    trackName: record.trackName,
+                    artistName: record.artistName,
+                    albumName: record.albumName,
+                    instrumental: record.instrumental,
+                },
+            }));
+        });
+    },
+});
+//# sourceMappingURL=lrclib.js.map

package/dist/providers/lrclib.js.map

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

package/dist/remote.d.ts

@@ -0,0 +1,29 @@
+import type { OperationName } from './plugins/types.js';
+/** Existing standalone HTTP deployment. Authentication stays outside Track metadata. */
+export interface RemotePluginHostOptions {
+    /** Stable deployment identity matching the audio node's configured host. */
+    hostId: string;
+    /** HTTP(S) origin without embedded credentials. */
+    url: string;
+    /** Optional bearer credential. */
+    token?: string;
+    /** Bounded discovery and execution deadline, default 15000ms. */
+    timeoutMs?: number;
+}
+/** Advertised provider capabilities from a standalone host. */
+export interface RemoteProvider {
+    /** Actual provider identity, separate from deployment identity. */
+    id: string;
+    /** Implemented operation names. */
+    operations: OperationName[];
+    /** Registered source protocols. */
+    protocols: string[];
+    /** Advertised operation priorities, applied unless the client descriptor overrides them. */
+    priorities?: Partial<Record<OperationName, number>>;
+}
+/** Validate live advertised capabilities; no plugin is installed on the remote server.
+ * @param host Existing standalone deployment.
+ * @param signal Registration lifetime.
+ * @returns Actual remote provider declarations.
+ */
+export declare function discoverRemote(host: RemotePluginHostOptions, signal: AbortSignal): Promise<RemoteProvider[]>;

package/dist/remote.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { lyricsResultSchema } from './lyrics.js';
+import { deserializeSourceResult, serializeSourceTrack, } from './protocol.js';
+import { Track } from './structures/track.js';
+/** Fetch one authenticated metadata response through the current HTTP boundary.
+ * @internal
+ * @param host Existing deployment.
+ * @param path Discovery or execution path.
+ * @param signal Request cancellation.
+ * @param body Optional serialized execution request.
+ * @returns Parsed metadata; operational failures reject.
+ */
+export async function remoteMetadata(host, path, signal, body) {
+    const url = new URL(host.url);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(host.hostId) ||
+        !['http:', 'https:'].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.pathname !== '/' ||
+        url.search ||
+        url.hash)
+        throw new TypeError('Source host requires a stable ID and an HTTP(S) origin without credentials');
+    if (!Number.isSafeInteger(host.timeoutMs ?? 15000) || (host.timeoutMs ?? 15000) < 1)
+        throw new RangeError('Source host timeout must be a positive safe integer');
+    const response = await fetch(`${url.origin}${path}`, {
+        method: body === undefined ? 'GET' : 'POST',
+        redirect: 'error',
+        signal: AbortSignal.any([signal, AbortSignal.timeout(host.timeoutMs ?? 15000)]),
+        headers: { 'content-type': 'application/json', ...(host.token ? { authorization: `Bearer ${host.token}` } : {}) },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    if (!response.ok)
+        throw new Error(`Source host ${host.hostId}: metadata request failed (HTTP ${response.status})`);
+    return response.json();
+}
+/** Validate live advertised capabilities; no plugin is installed on the remote server.
+ * @param host Existing standalone deployment.
+ * @param signal Registration lifetime.
+ * @returns Actual remote provider declarations.
+ */
+export async function discoverRemote(host, signal) {
+    const manifest = await remoteMetadata(host, '/.well-known/remedia', signal);
+    if (!manifest ||
+        typeof manifest !== 'object' ||
+        !('protocolVersion' in manifest) ||
+        manifest.protocolVersion !== 1 ||
+        !('providers' in manifest) ||
+        !Array.isArray(manifest.providers))
+        throw new Error(`Source host ${host.hostId}: incompatible metadata manifest`);
+    if (!('hostId' in manifest) || manifest.hostId !== host.hostId)
+        throw new Error(`Source host ${host.hostId}: deployment identity does not match advertised host`);
+    return manifest.providers.map((provider) => {
+        if (!provider ||
+            typeof provider.id !== 'string' ||
+            !Array.isArray(provider.operations) ||
+            !provider.operations.every((name) => typeof name === 'string') ||
+            !Array.isArray(provider.protocols) ||
+            !provider.protocols.every((name) => typeof name === 'string'))
+            throw new TypeError('Invalid remote provider manifest');
+        if (provider.priorities !== undefined)
+            z.record(z.string(), z.number()).parse(provider.priorities);
+        return provider;
+    });
+}
+/** Register remote metadata operations into the ordinary capability registry.
+ * @internal
+ * @param ctx Registration owner.
+ * @param providerId Actual remote provider ID.
+ * @param host Existing deployment configuration.
+ * @param advertised Already validated discovery for a bulk host registration.
+ */
+export async function registerRemote(ctx, providerId, host, advertised) {
+    const provider = (advertised ?? (await discoverRemote(host, ctx.signal))).find((item) => item.id === providerId);
+    if (!provider)
+        throw new Error(`Source host ${host.hostId}: provider ${providerId} is not advertised`);
+    const execute = async (request, signal) => {
+        const envelope = await remoteMetadata(host, '/remedia/v1/execute', signal, {
+            pluginId: 'discord-player.source',
+            operation: 'metadata.execute',
+            input: request,
+        });
+        if (!envelope ||
+            typeof envelope !== 'object' ||
+            !('handled' in envelope) ||
+            envelope.handled !== true ||
+            !('result' in envelope))
+            throw new Error(`Source host ${host.hostId}: invalid metadata response`);
+        return envelope.result;
+    };
+    const portableQuery = (input) => {
+        const original = input.options ?? {};
+        return {
+            ...input,
+            options: {
+                limit: original.limit,
+                blockExtractors: original.blockExtractors,
+                requestedBy: typeof original.requestedBy === 'object' ? original.requestedBy?.id : original.requestedBy,
+            },
+        };
+    };
+    if (provider.operations.includes('search.query.match')) {
+        ctx.on('search.query.match', async (input, { signal }) => {
+            const result = await execute({ providerId, operation: 'search.query.match', input: portableQuery(input) }, signal);
+            const matches = z
+                .array(z.object({ score: z.number(), pluginId: z.string().optional() }).nullable())
+                .parse(result);
+            return matches.find((match) => match !== null && match.score >= 0) ?? null;
+        }, { protocols: provider.protocols, priority: provider.priorities?.['search.query.match'] });
+    }
+    if (provider.operations.includes('search.query.resolve')) {
+        ctx.on('search.query.resolve', async (input, { signal }) => {
+            const result = deserializeSourceResult((await execute({ providerId, operation: 'search.query.resolve', input: portableQuery(input) }, signal)));
+            for (const track of result.tracks)
+                if (track.sourceReference?.pluginId !== providerId || track.sourceReference.hostId !== host.hostId)
+                    throw new Error('Remote Track provider or deployment identity does not match its registration');
+            return result;
+        }, { protocols: provider.protocols, priority: provider.priorities?.['search.query.resolve'] });
+    }
+    if (provider.operations.includes('track.related')) {
+        ctx.on('track.related', async ({ track }, { signal }) => {
+            const result = await execute({ providerId, operation: 'track.related', input: { track: serializeSourceTrack(track) } }, signal);
+            return deserializeSourceResult(result);
+        }, { priority: provider.priorities?.['track.related'] });
+    }
+    if (provider.operations.includes('lyrics.search')) {
+        ctx.on('lyrics.search', async ({ input }, { signal }) => {
+            const result = await execute({
+                providerId,
+                operation: 'lyrics.search',
+                input: { input: input instanceof Track ? input.serialize() : input },
+            }, signal);
+            const groups = z.array(z.array(lyricsResultSchema).nullable()).parse(result);
+            return groups
+                .flatMap((group) => group ?? [])
+                .map((record) => ({
+                ...record,
+                provider: { pluginId: providerId, hostId: host.hostId, data: record.provider?.data ?? null },
+            }));
+        }, { priority: provider.priorities?.['lyrics.search'] });
+    }
+}
+//# sourceMappingURL=remote.js.map

package/dist/remote.js.map

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

package/dist/runtime.d.ts

@@ -30,20 +30,12 @@ export declare class SourcePluginRuntime extends SafeEventEmitter<SourceRuntimeE
      * @param options Source settings and optional embedding context.
      */
     constructor(options?: SourcePluginRuntimeOptions);
-    /** Queue orchestration requires an actual DiscordPlayer. */
-    get queues(): never;
-    /** Voice nodes require an actual DiscordPlayer. */
-    get nodes(): never;
-    /** Audio clients are unavailable in standalone source execution. */
-    get remedia(): never;
     /** Required audio access is unavailable in standalone execution. */
     getRemedia(): RemediaClient;
     /** Optional audio access returns null.
      * @param throwOnMissing Optional lookup flag.
      */
     getRemedia(throwOnMissing: false): RemediaClient | null;
-    /** Playback is outside the source compatibility API. */
-    play(): never;
     /** Emit a source diagnostic.
      * @param message Diagnostic text.
      */

package/dist/runtime.js

@@ -24,27 +24,11 @@ export class SourcePluginRuntime extends SafeEventEmitter {
         this.plugins = new PluginRegistry(this.player, () => this.options.blockExtractors ?? [], options.hostId);
         this.extractors = new ExtractorExecutionContext(this.player);
     }
-    /** Queue orchestration requires an actual DiscordPlayer. */
-    get queues() {
-        throw new Error('SourcePluginRuntime does not provide queues; use DiscordPlayer for playback');
-    }
-    /** Voice nodes require an actual DiscordPlayer. */
-    get nodes() {
-        throw new Error('SourcePluginRuntime does not provide voice nodes; use DiscordPlayer for playback');
-    }
-    /** Audio clients are unavailable in standalone source execution. */
-    get remedia() {
-        throw new Error('SourcePluginRuntime does not initialize a Remedia audio client');
-    }
     getRemedia(throwOnMissing = true) {
         if (throwOnMissing)
             throw new Error('SourcePluginRuntime does not initialize an audio client; use DiscordPlayer');
         return null;
     }
-    /** Playback is outside the source compatibility API. */
-    play() {
-        throw new Error('SourcePluginRuntime cannot play audio; use DiscordPlayer');
-    }
     /** Emit a source diagnostic.
      * @param message Diagnostic text.
      */
@@ -74,45 +58,59 @@ export class SourcePluginRuntime extends SafeEventEmitter {
             return new SearchResult({ tracks: query.tracks, playlist: query });
         }
         const blocked = [...(this.options.blockExtractors ?? []), ...(options.blockExtractors ?? [])];
-        const target = options.pluginId ?? (options.searchEngine?.startsWith('ext:') ? options.searchEngine.slice(4) : undefined);
         await this.plugins.ready();
-        const prefix = /^([\w.-]+):(?:\/\/)?(.*)$/s.exec(query);
+        const engine = options.searchEngine;
+        const legacy = engine?.startsWith('ext:') ? engine.slice(4) : undefined;
+        if (legacy !== undefined && !this.extractors.get(legacy))
+            throw new Error(`Legacy extractor ${legacy} is not registered`);
+        const target = legacy ?? (engine && this.plugins.has(engine) ? engine : undefined);
+        const prefix = options.resolveCustomProtocols !== false && !/^(?:https?|file):/i.test(query) && !/^[a-z]:/i.test(query)
+            ? /^([a-z][a-z0-9+.-]*):(?:\/\/)?(.*)$/is.exec(query)
+            : null;
         const protocol = prefix && this.plugins.supportsProtocol(prefix[1], { pluginId: target, blocked }) ? prefix[1] : undefined;
+        const providerHint = target ? undefined : engine;
         const input = {
             query: protocol ? prefix[2] : query,
             protocol,
+            providerHint,
             options: {
-                ...options,
-                searchEngine: (options.searchEngine?.startsWith('ext:') ? undefined : options.searchEngine) ??
-                    options.source ??
-                    (/^https?:\/\//i.test(query) ? 'arbitrary' : 'auto'),
+                requestedBy: options.requestedBy,
+                requestOptions: options.requestOptions,
+                limit: options.limit,
+                blockExtractors: options.blockExtractors,
             },
         };
-        const execution = { signal: options.signal, blocked, pluginId: target };
+        const execution = { signal: options.signal, blocked, pluginId: target, hostId: options.hostId };
         const matches = target
-            ? [{ pluginId: target, score: 0 }]
-            : await this.plugins.execute('search.query.match', input, execution);
-        const match = matches.find((item) => item !== null && item.score >= 0);
-        if (!match?.pluginId) {
-            return SearchResult.empty();
-        }
-        const result = await this.plugins.execute('search.query.resolve', input, {
-            ...execution,
-            pluginId: match.pluginId,
-        });
-        if (!result) {
-            return SearchResult.empty();
-        }
-        for (const track of result.tracks) {
-            track.sourceReference ??= {
+            ? [{ pluginId: target, score: 0, hostId: options.hostId }]
+            : protocol
+                ? this.plugins.protocolMatches(protocol, execution)
+                : await this.plugins.execute('search.query.match', input, execution);
+        for (const match of matches) {
+            if (!match?.pluginId || match.score < 0)
+                continue;
+            const result = await this.plugins.execute('search.query.resolve', input, {
+                ...execution,
                 pluginId: match.pluginId,
-                data: { url: track.url },
-            };
-            if (options.requestedBy !== undefined) {
-                track.requestedBy = options.requestedBy;
+                hostId: match.hostId ?? (target ? options.hostId : null),
+            });
+            if (!result?.tracks.length) {
+                if (target)
+                    break;
+                continue;
+            }
+            for (const track of result.tracks) {
+                track.sourceReference ??= {
+                    pluginId: match.pluginId,
+                    ...(match.hostId ? { hostId: match.hostId } : {}),
+                    data: { url: track.url },
+                };
+                if (options.requestedBy !== undefined)
+                    track.requestedBy = options.requestedBy;
             }
+            return new SearchResult(result);
         }
-        return new SearchResult(result);
+        return SearchResult.empty();
     }
 }
 //# sourceMappingURL=runtime.js.map