fix(providers): warn if GTIN lookup found multiple results for Spotify / Tidal

providers/Spotify/mod.ts

@@ -173,8 +173,12 @@ export class SpotifyReleaseLookup extends ReleaseApiLookup<SpotifyProvider, Albu
 					this.constructReleaseApiUrl(),
 					this.options.snapshotMaxTimestamp,
 				);
-				if (cacheEntry.content?.albums?.items?.length) {
-					return cacheEntry.content.albums.items[0].id;
+				const releases = cacheEntry.content?.albums?.items;
+				if (releases?.length) {
+					if (releases.length > 1) {
+						this.warnMultipleResults(releases.slice(1).map((release) => release.external_urls?.spotify));
+					}
+					return releases[0].id;
 				}
 			}
 		}

providers/Tidal/mod.ts

@@ -157,6 +157,9 @@ export class TidalReleaseLookup extends ReleaseApiLookup<TidalProvider, Album> {
 				return Boolean(data?.data?.length);
 			};
 			const result = await this.queryAllRegions<Result<Album>>(isValidData);
+			if (result.data.length > 1) {
+				this.warnMultipleResults(result.data.slice(1).map((release) => release.resource.tidalUrl));
+			}
 			return result.data[0].resource;
 		} else {
 			const isValidData = (data: Resource<Album>) => {

providers/base.ts

@@ -21,6 +21,7 @@ import type { PartialDate } from '@/utils/date.ts';
 import type { CacheOptions, Snapshot, SnapStorage } from 'snap-storage';
 import type { MaybePromise } from 'utils/types.d.ts';
 import type { Logger } from 'std/log/logger.ts';
+import { pluralWithCount } from '@/utils/plural.ts';
 
 export type ProviderOptions = Partial<{
 	/** Duration of one rate-limiting interval for requests (in ms). */
@@ -335,6 +336,20 @@ export abstract class ReleaseLookup<Provider extends MetadataProvider, RawReleas
 		};
 	}
 
+	/**
+	 * Shows a warning if the provider found more than the expected result for a lookup.
+	 * Expects a list of URLs pointing to the extra results from the provider.
+	 */
+	protected warnMultipleResults(urls: string[] | URL[]) {
+		const lines = urls.map((url) => `${url} ([lookup](?url=${encodeURIComponent(String(url))}))`);
+		this.addMessage(
+			`The API also returned ${
+				pluralWithCount(urls.length, 'other result, which was skipped', 'other results, which were skipped')
+			}:\n- ${lines.join('\n- ')}`,
+			'warning',
+		);
+	}
+
 	/** Determines excluded regions of the release (if available regions have been specified for the provider). */
 	private withExcludedRegions(release: HarmonyRelease): HarmonyRelease {
 		const availableRegions = this.provider.availableRegions;

providers/iTunes/mod.ts

@@ -3,7 +3,6 @@ import { type CacheEntry, MetadataApiProvider, ReleaseApiLookup } from '@/provid
 import { DurationPrecision, FeatureQuality, FeatureQualityMap } from '@/providers/features.ts';
 import { parseISODateTime, PartialDate } from '@/utils/date.ts';
 import { isEqualGTIN, isValidGTIN } from '@/utils/gtin.ts';
-import { pluralWithCount } from '@/utils/plural.ts';
 
 import type { Collection, Kind, ReleaseResult, Track } from './api_types.ts';
 import type {
@@ -142,12 +141,7 @@ export class iTunesReleaseLookup extends ReleaseApiLookup<iTunesProvider, Releas
 			const skippedUrls = uniqueSkippedIds.map((id) =>
 				this.cleanViewUrl(skippedResults.find((result) => result.collectionId === id)!.collectionViewUrl)
 			);
-			this.addMessage(
-				`The API also returned ${
-					pluralWithCount(skippedUrls.length, 'other result, which was skipped', 'other results, which were skipped')
-				}:\n- ${skippedUrls.join('\n- ')}`,
-				'warning',
-			);
+			this.warnMultipleResults(skippedUrls);
 		}
 
 		const linkTypes: LinkType[] = [];