From 759aeec76685c15ed35061990ca8d30f9e32fdf1 Mon Sep 17 00:00:00 2001
From: Ewan Croft <contact@ewancroft.uk>
Date: Thu, 13 Aug 2026 15:39:32 +0100
Subject: [PATCH] feat(tourmaline): parse MusicBrainz area/country into
 ArtistInfo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MusicBrainz's base artist lookup already returns `area` (with an
`iso-3166-1-codes` list) alongside the tags/genres/ratings tourmaline
already requests via `inc=tags+genres+ratings` — verified against the
live API with that exact query. No new `inc=` param or extra
per-artist round-trip is needed, so this is free to add without
touching the 1 req/sec MusicBrainz rate limit.

Both fields are optional on ArtistInfo, so existing server (7-day) and
client localStorage (30-day) enrichment caches degrade gracefully:
cached entries without area/areaCode just omit them until they
naturally expire and re-enrich.

Lays the groundwork for a "scrobbles/artists by region" breakdown.
---
 packages/tourmaline/src/lib/server/enrich.ts | 8 ++++++++
 packages/tourmaline/src/lib/types.ts         | 4 ++++
 2 files changed, 12 insertions(+)

diff --git a/packages/tourmaline/src/lib/server/enrich.ts b/packages/tourmaline/src/lib/server/enrich.ts
index 9feb376..a5e0483 100644
--- a/packages/tourmaline/src/lib/server/enrich.ts
+++ b/packages/tourmaline/src/lib/server/enrich.ts
@@ -92,6 +92,10 @@ interface MBArtist {
   genres?: Array<{ name: string; count: number }>;
   rating?: { value?: number };
   "life-span"?: { begin?: string; end?: string; ended?: boolean };
+  // `area` (and the `iso-3166-1-codes` it carries) is a core artist field
+  // returned by the base MusicBrainz artist lookup — no extra `inc=` param
+  // or additional request is needed to get it.
+  area?: { name?: string; "iso-3166-1-codes"?: string[] };
 }
 
 interface MBSearchResult {
@@ -136,6 +140,8 @@ async function mbGetArtistInfo(mbId: string): Promise<ArtistInfo | null> {
     listenerCount: undefined,
     playCount: undefined,
     startYear: isNaN(startYear!) ? undefined : startYear,
+    area: data.area?.name,
+    areaCode: data.area?.["iso-3166-1-codes"]?.[0],
   };
 }
 
@@ -315,6 +321,8 @@ export async function enrichArtistBatch(
             genres: mbInfo.genres?.length ? mbInfo.genres : info.genres,
             tags: mbInfo.tags?.length ? mbInfo.tags : info.tags,
             mbId: mbInfo.mbId,
+            area: mbInfo.area,
+            areaCode: mbInfo.areaCode,
           };
         }
       } else {
diff --git a/packages/tourmaline/src/lib/types.ts b/packages/tourmaline/src/lib/types.ts
index dd4cf32..2f268da 100644
--- a/packages/tourmaline/src/lib/types.ts
+++ b/packages/tourmaline/src/lib/types.ts
@@ -27,6 +27,10 @@ export interface ArtistInfo {
   playCount?: number;
   imageUrl?: string;
   startYear?: number;
+  /** MusicBrainz area (country/region of origin), e.g. "United States". */
+  area?: string;
+  /** ISO 3166-1 alpha-2 code for `area`, e.g. "US". */
+  areaCode?: string;
 }
 
 export interface GenreEntry {
-- 
2.51.2