From ada1c12f573de7ca51c509e27d4866a20a312c46 Mon Sep 17 00:00:00 2001
From: cdricms <36056008+cdricms@users.noreply.github.com>
Date: Sat, 21 Mar 2026 17:25:07 +0100
Subject: [PATCH] Started off well

---
 .gitignore                                    |   8 +
 GEMINI.md                                     |   6 +
 Package.swift                                 |  28 +
 Sources/MusicBrainz/MusicBrainz.swift         | 863 ++++++++++++++++++
 Sources/MusicBrainzExe/main.swift             |  31 +
 .../ExtendedSearchTests.swift                 | 108 +++
 Tests/MusicBrainzTests/MusicBrainzTests.swift |  54 ++
 Tests/MusicBrainzTests/QueryTests.swift       |  36 +
 Tests/MusicBrainzTests/SearchTests.swift      |  30 +
 9 files changed, 1164 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 GEMINI.md
 create mode 100644 Package.swift
 create mode 100644 Sources/MusicBrainz/MusicBrainz.swift
 create mode 100644 Sources/MusicBrainzExe/main.swift
 create mode 100644 Tests/MusicBrainzTests/ExtendedSearchTests.swift
 create mode 100644 Tests/MusicBrainzTests/MusicBrainzTests.swift
 create mode 100644 Tests/MusicBrainzTests/QueryTests.swift
 create mode 100644 Tests/MusicBrainzTests/SearchTests.swift

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..0023a53
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,8 @@
+.DS_Store
+/.build
+/Packages
+xcuserdata/
+DerivedData/
+.swiftpm/configuration/registries.json
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.netrc
diff --git a/GEMINI.md b/GEMINI.md
new file mode 100644
index 0000000..1038081
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1,6 @@
+# MusicBrainz Swift
+
+Documentation and reference for the MusicBrainz API implementation.
+
+## Search API Reference
+- [MusicBrainz Search API Documentation](https://musicbrainz.org/doc/MusicBrainz_API/Search)
diff --git a/Package.swift b/Package.swift
new file mode 100644
index 0000000..c7674e6
--- /dev/null
+++ b/Package.swift
@@ -0,0 +1,28 @@
+// swift-tools-version: 6.2
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+	name: "MusicBrainz",
+	products: [
+		// Products define the executables and libraries a package produces, making them visible to other packages.
+		.library(
+			name: "MusicBrainz",
+			targets: ["MusicBrainz"]
+		),
+		.executable(name: "MusicBrainzExe", targets: ["MusicBrainzExe"]),
+	],
+	targets: [
+		// Targets are the basic building blocks of a package, defining a module or a test suite.
+		// Targets can depend on other targets in this package and products from dependencies.
+		.target(
+			name: "MusicBrainz"
+		),
+		.executableTarget(name: "MusicBrainzExe", dependencies: ["MusicBrainz"]),
+		.testTarget(
+			name: "MusicBrainzTests",
+			dependencies: ["MusicBrainz"]
+		),
+	]
+)
diff --git a/Sources/MusicBrainz/MusicBrainz.swift b/Sources/MusicBrainz/MusicBrainz.swift
new file mode 100644
index 0000000..9754f2a
--- /dev/null
+++ b/Sources/MusicBrainz/MusicBrainz.swift
@@ -0,0 +1,863 @@
+import Foundation
+
+#if canImport(FoundationNetworking)
+	import FoundationNetworking
+#endif
+
+public enum MusicBrainzError: Error {
+	case badURL
+	case badServerResponse(Int)
+	case decodingError(Error)
+	case coordinator(Error)
+}
+
+// MARK: - Generic Support
+
+internal struct DynamicCodingKey: CodingKey {
+	var stringValue: String
+	var intValue: Int?
+	init?(stringValue: String) { self.stringValue = stringValue }
+	init?(intValue: Int) { return nil }
+}
+
+public enum MusicBrainzEntity: String, Sendable {
+	case area
+	case artist
+	case event
+	case instrument
+	case label
+	case place
+	case recording
+	case release
+	case releaseGroup = "release-group"
+	case series
+	case work
+	case url
+
+	public var responseKey: String {
+		switch self {
+		case .series: return "series"
+		default: return "\(self.rawValue)s"
+		}
+	}
+}
+
+public struct MusicBrainzEntityType<T: MusicBrainzSearchable>: Sendable {
+	public let entity: MusicBrainzEntity
+
+	public static var area: MusicBrainzEntityType<Area> { .init(entity: .area) }
+	public static var artist: MusicBrainzEntityType<Artist> { .init(entity: .artist) }
+	public static var event: MusicBrainzEntityType<Event> { .init(entity: .event) }
+	public static var instrument: MusicBrainzEntityType<Instrument> { .init(entity: .instrument) }
+	public static var label: MusicBrainzEntityType<Label> { .init(entity: .label) }
+	public static var place: MusicBrainzEntityType<Place> { .init(entity: .place) }
+	public static var recording: MusicBrainzEntityType<Recording> { .init(entity: .recording) }
+	public static var release: MusicBrainzEntityType<Release> { .init(entity: .release) }
+	public static var releaseGroup: MusicBrainzEntityType<ReleaseGroup> {
+		.init(entity: .releaseGroup)
+	}
+	public static var series: MusicBrainzEntityType<Series> { .init(entity: .series) }
+	public static var work: MusicBrainzEntityType<Work> { .init(entity: .work) }
+	public static var url: MusicBrainzEntityType<URLReference> { .init(entity: .url) }
+}
+
+public protocol MusicBrainzSearchable: Codable, Sendable {
+	static var entityType: MusicBrainzEntity { get }
+}
+
+public struct SearchResponse<T: MusicBrainzSearchable>: Codable, Sendable {
+	public let count: Int
+	public let offset: Int
+	public let entities: [T]
+
+	private enum CodingKeys: String, CodingKey {
+		case count, offset
+	}
+
+	public init(from decoder: Decoder) throws {
+		let container = try decoder.container(keyedBy: CodingKeys.self)
+		count = try container.decode(Int.self, forKey: .count)
+		offset = try container.decode(Int.self, forKey: .offset)
+
+		let dynamicContainer = try decoder.container(keyedBy: DynamicCodingKey.self)
+		guard let key = DynamicCodingKey(stringValue: T.entityType.responseKey) else {
+			throw DecodingError.dataCorrupted(
+				DecodingError.Context(
+					codingPath: decoder.codingPath,
+					debugDescription: "Invalid response key for entity type"
+				)
+			)
+		}
+		entities = try dynamicContainer.decode([T].self, forKey: key)
+	}
+}
+
+// MARK: - Structured Queries
+
+public enum Gender: String, Sendable {
+	case male, female, other
+	case notApplicable = "not applicable"
+}
+
+public enum ArtistType: String, Sendable {
+	case person, group, orchestra, choir, character, other
+}
+
+public enum Country: String, Sendable {
+	case af = "AF"  // Afghanistan
+	case al = "AL"  // Albania
+	case dz = "DZ"  // Algeria
+	case ad = "AD"  // Andorra
+	case ao = "AO"  // Angola
+	case ar = "AR"  // Argentina
+	case am = "AM"  // Armenia
+	case au = "AU"  // Australia
+	case at = "AT"  // Austria
+	case az = "AZ"  // Azerbaijan
+	case be = "BE"  // Belgium
+	case br = "BR"  // Brazil
+	case ca = "CA"  // Canada
+	case cn = "CN"  // China
+	case dk = "DK"  // Denmark
+	case fi = "FI"  // Finland
+	case fr = "FR"  // France
+	case de = "DE"  // Germany
+	case gr = "GR"  // Greece
+	case `in` = "IN"  // India
+	case id = "ID"  // Indonesia
+	case ie = "IE"  // Ireland
+	case it = "IT"  // Italy
+	case jp = "JP"  // Japan
+	case mx = "MX"  // Mexico
+	case nl = "NL"  // Netherlands
+	case nz = "NZ"  // New Zealand
+	case no = "NO"  // Norway
+	case pl = "PL"  // Poland
+	case pt = "PT"  // Portugal
+	case ru = "RU"  // Russia
+	case kr = "KR"  // South Korea
+	case es = "ES"  // Spain
+	case se = "SE"  // Sweden
+	case ch = "CH"  // Switzerland
+	case tr = "TR"  // Turkey
+	case gb = "GB"  // United Kingdom
+	case us = "US"  // United States
+	// ... add more as needed or provide a way to use others
+}
+
+public struct MusicBrainzSearchAction<T: MusicBrainzSearchable>: Sendable {
+	public let entity: MusicBrainzEntity
+	public let query: String
+
+	fileprivate static func buildQuery(_ fields: [String: Any?], raw: String?) -> String {
+		var parts: [String] = []
+		for (key, value) in fields {
+			if let value {
+				let stringValue: String
+				if let val = value as? String {
+					stringValue = val
+				} else if let val = value as? CustomStringConvertible {
+					stringValue = val.description
+				} else if let val = value as? (any RawRepresentable),
+					let rawVal = val.rawValue as? String
+				{
+					stringValue = rawVal
+				} else {
+					continue
+				}
+
+				if !stringValue.isEmpty {
+					let escaped = stringValue.replacingOccurrences(of: "\"", with: "\\\"")
+					parts.append("\(key):\"\(escaped)\"")
+				}
+			}
+		}
+		if let raw, !raw.isEmpty {
+			parts.append(raw)
+		}
+		return parts.joined(separator: " AND ")
+	}
+}
+
+extension MusicBrainzSearchAction where T == Area {
+	public static func area(
+		name: String? = nil,
+		type: String? = nil,
+		iso: String? = nil,
+		aid: String? = nil,
+		alias: String? = nil,
+		begin: String? = nil,
+		comment: String? = nil,
+		end: String? = nil,
+		ended: Bool? = nil,
+		sortname: String? = nil,
+		tag: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"area": name, "type": type, "iso": iso, "aid": aid,
+				"alias": alias, "begin": begin, "comment": comment, "end": end,
+				"ended": ended?.description, "sortname": sortname, "tag": tag,
+			], raw: raw)
+		return .init(entity: .area, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Artist {
+	public static func artist(
+		name: String? = nil,
+		gender: Gender? = nil,
+		country: Country? = nil,
+		type: ArtistType? = nil,
+		alias: String? = nil,
+		area: String? = nil,
+		arid: String? = nil,
+		begin: String? = nil,
+		beginarea: String? = nil,
+		comment: String? = nil,
+		end: String? = nil,
+		endarea: String? = nil,
+		ended: Bool? = nil,
+		ipi: String? = nil,
+		isni: String? = nil,
+		sortname: String? = nil,
+		tag: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"artist": name, "gender": gender?.rawValue, "country": country?.rawValue,
+				"type": type?.rawValue,
+				"alias": alias, "area": area, "arid": arid, "begin": begin, "beginarea": beginarea,
+				"comment": comment, "end": end, "endarea": endarea, "ended": ended?.description,
+				"ipi": ipi, "isni": isni, "sortname": sortname, "tag": tag,
+			], raw: raw)
+		return .init(entity: .artist, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Event {
+	public static func event(
+		name: String? = nil,
+		type: String? = nil,
+		artist: String? = nil,
+		place: String? = nil,
+		aid: String? = nil,
+		area: String? = nil,
+		arid: String? = nil,
+		begin: String? = nil,
+		comment: String? = nil,
+		end: String? = nil,
+		ended: Bool? = nil,
+		eid: String? = nil,
+		pid: String? = nil,
+		tag: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"event": name, "type": type, "artist": artist, "place": place,
+				"aid": aid, "area": area, "arid": arid, "begin": begin,
+				"comment": comment, "end": end, "ended": ended?.description,
+				"eid": eid, "pid": pid, "tag": tag,
+			], raw: raw)
+		return .init(entity: .event, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Instrument {
+	public static func instrument(
+		name: String? = nil,
+		type: String? = nil,
+		description: String? = nil,
+		alias: String? = nil,
+		comment: String? = nil,
+		iid: String? = nil,
+		tag: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"instrument": name, "type": type, "description": description,
+				"alias": alias, "comment": comment, "iid": iid, "tag": tag,
+			], raw: raw)
+		return .init(entity: .instrument, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Label {
+	public static func label(
+		name: String? = nil,
+		type: String? = nil,
+		code: String? = nil,
+		country: Country? = nil,
+		alias: String? = nil,
+		area: String? = nil,
+		begin: String? = nil,
+		comment: String? = nil,
+		end: String? = nil,
+		ended: Bool? = nil,
+		ipi: String? = nil,
+		isni: String? = nil,
+		laid: String? = nil,
+		sortname: String? = nil,
+		tag: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"label": name, "type": type, "code": code, "country": country?.rawValue,
+				"alias": alias, "area": area, "begin": begin, "comment": comment,
+				"end": end, "ended": ended?.description, "ipi": ipi, "isni": isni,
+				"laid": laid, "sortname": sortname, "tag": tag,
+			], raw: raw)
+		return .init(entity: .label, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Place {
+	public static func place(
+		name: String? = nil,
+		type: String? = nil,
+		address: String? = nil,
+		area: String? = nil,
+		alias: String? = nil,
+		begin: String? = nil,
+		comment: String? = nil,
+		end: String? = nil,
+		ended: Bool? = nil,
+		lat: String? = nil,
+		long: String? = nil,
+		pid: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"place": name, "type": type, "address": address, "area": area,
+				"alias": alias, "begin": begin, "comment": comment, "end": end,
+				"ended": ended?.description, "lat": lat, "long": long, "pid": pid,
+			], raw: raw)
+		return .init(entity: .place, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Recording {
+	public static func recording(
+		title: String? = nil,
+		artist: String? = nil,
+		release: String? = nil,
+		isrc: String? = nil,
+		arid: String? = nil,
+		comment: String? = nil,
+		country: Country? = nil,
+		date: String? = nil,
+		dur: String? = nil,
+		firstreleasedate: String? = nil,
+		format: String? = nil,
+		number: String? = nil,
+		position: String? = nil,
+		primarytype: String? = nil,
+		reid: String? = nil,
+		rgid: String? = nil,
+		rid: String? = nil,
+		secondarytype: String? = nil,
+		status: String? = nil,
+		tag: String? = nil,
+		tid: String? = nil,
+		tnum: String? = nil,
+		video: Bool? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"recording": title, "artist": artist, "release": release, "isrc": isrc,
+				"arid": arid, "comment": comment, "country": country?.rawValue, "date": date,
+				"dur": dur, "firstreleasedate": firstreleasedate, "format": format,
+				"number": number, "position": position, "primarytype": primarytype,
+				"reid": reid, "rgid": rgid, "rid": rid, "secondarytype": secondarytype,
+				"status": status, "tag": tag, "tid": tid, "tnum": tnum, "video": video?.description,
+			], raw: raw)
+		return .init(entity: .recording, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Release {
+	public static func release(
+		title: String? = nil,
+		artist: String? = nil,
+		label: String? = nil,
+		barcode: String? = nil,
+		status: String? = nil,
+		arid: String? = nil,
+		asin: String? = nil,
+		catno: String? = nil,
+		comment: String? = nil,
+		country: Country? = nil,
+		date: String? = nil,
+		discids: String? = nil,
+		format: String? = nil,
+		laid: String? = nil,
+		mediums: String? = nil,
+		primarytype: String? = nil,
+		puid: String? = nil,
+		reid: String? = nil,
+		rgid: String? = nil,
+		script: String? = nil,
+		secondarytype: String? = nil,
+		tag: String? = nil,
+		tracks: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"release": title, "artist": artist, "label": label, "barcode": barcode,
+				"status": status,
+				"arid": arid, "asin": asin, "catno": catno, "comment": comment,
+				"country": country?.rawValue,
+				"date": date, "discids": discids, "format": format, "laid": laid,
+				"mediums": mediums,
+				"primarytype": primarytype, "puid": puid, "reid": reid, "rgid": rgid,
+				"script": script,
+				"secondarytype": secondarytype, "tag": tag, "tracks": tracks,
+			], raw: raw)
+		return .init(entity: .release, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == ReleaseGroup {
+	public static func releaseGroup(
+		title: String? = nil,
+		artist: String? = nil,
+		type: String? = nil,
+		arid: String? = nil,
+		comment: String? = nil,
+		primarytype: String? = nil,
+		rgid: String? = nil,
+		releases: String? = nil,
+		secondarytype: String? = nil,
+		status: String? = nil,
+		tag: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"releasegroup": title, "artist": artist, "type": type, "arid": arid,
+				"comment": comment, "primarytype": primarytype, "rgid": rgid,
+				"releases": releases, "secondarytype": secondarytype, "status": status, "tag": tag,
+			], raw: raw)
+		return .init(entity: .releaseGroup, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Series {
+	public static func series(
+		name: String? = nil,
+		type: String? = nil,
+		alias: String? = nil,
+		comment: String? = nil,
+		sid: String? = nil,
+		tag: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"series": name, "type": type, "alias": alias, "comment": comment,
+				"sid": sid, "tag": tag,
+			], raw: raw)
+		return .init(entity: .series, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == Work {
+	public static func work(
+		title: String? = nil,
+		artist: String? = nil,
+		type: String? = nil,
+		iswc: String? = nil,
+		alias: String? = nil,
+		arid: String? = nil,
+		comment: String? = nil,
+		lang: String? = nil,
+		tag: String? = nil,
+		wid: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"work": title, "artist": artist, "type": type, "iswc": iswc,
+				"alias": alias, "arid": arid, "comment": comment, "lang": lang,
+				"tag": tag, "wid": wid,
+			], raw: raw)
+		return .init(entity: .work, query: q)
+	}
+}
+
+extension MusicBrainzSearchAction where T == URLReference {
+	public static func url(
+		resource: String? = nil,
+		targettype: String? = nil,
+		targetid: String? = nil,
+		uid: String? = nil,
+		raw: String? = nil
+	) -> Self {
+		let q = buildQuery(
+			[
+				"url": resource, "targettype": targettype, "targetid": targetid, "uid": uid,
+			], raw: raw)
+		return .init(entity: .url, query: q)
+	}
+}
+
+// MARK: - Entity Models
+
+public struct LifeSpan: Codable, Sendable {
+	public let begin: String?
+	public let end: String?
+	public let ended: Bool?
+}
+
+public struct Area: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .area
+
+	public let id: String
+	public let type: String?
+	public let name: String
+	public let sortName: String?
+	public let disambiguation: String?
+	public let lifeSpan: LifeSpan?
+	public let score: Int?
+
+	enum CodingKeys: String, CodingKey {
+		case id, type, name, disambiguation, score
+		case sortName = "sort-name"
+		case lifeSpan = "life-span"
+	}
+}
+
+public struct Artist: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .artist
+
+	public let id: String
+	public let name: String
+	public let sortName: String?
+	public let type: String?
+	public let country: String?
+	public let disambiguation: String?
+	public let lifeSpan: LifeSpan?
+	public let score: Int?
+
+	enum CodingKeys: String, CodingKey {
+		case id
+		case name
+		case sortName = "sort-name"
+		case type
+		case country
+		case disambiguation
+		case lifeSpan = "life-span"
+		case score
+	}
+}
+
+public struct Release: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .release
+
+	public let id: String
+	public let title: String
+	public let status: String?
+	public let date: String?
+	public let country: String?
+	public let barcode: String?
+	public let disambiguation: String?
+	public let score: Int?
+
+	enum CodingKeys: String, CodingKey {
+		case id
+		case title
+		case status
+		case date
+		case country
+		case barcode
+		case disambiguation
+		case score
+	}
+}
+
+public struct Recording: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .recording
+
+	public let id: String
+	public let title: String
+	public let length: Int?
+	public let video: Bool?
+	public let disambiguation: String?
+	public let firstReleaseDate: String?
+	public let score: Int?
+
+	enum CodingKeys: String, CodingKey {
+		case id
+		case title
+		case length
+		case video
+		case disambiguation
+		case firstReleaseDate = "first-release-date"
+		case score
+	}
+}
+
+public struct Event: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .event
+
+	public let id: String
+	public let name: String
+	public let time: String?
+	public let disambiguation: String?
+	public let lifeSpan: LifeSpan?
+	public let score: Int?
+
+	enum CodingKeys: String, CodingKey {
+		case id, name, time, disambiguation, score
+		case lifeSpan = "life-span"
+	}
+}
+
+public struct Instrument: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .instrument
+
+	public let id: String
+	public let name: String
+	public let type: String?
+	public let description: String?
+	public let disambiguation: String?
+	public let score: Int?
+}
+
+public struct Label: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .label
+
+	public let id: String
+	public let name: String
+	public let type: String?
+	public let labelCode: Int?
+	public let country: String?
+	public let disambiguation: String?
+	public let score: Int?
+
+	enum CodingKeys: String, CodingKey {
+		case id, name, type, country, disambiguation, score
+		case labelCode = "label-code"
+	}
+}
+
+public struct Place: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .place
+
+	public let id: String
+	public let name: String
+	public let type: String?
+	public let address: String?
+	public let area: Area?
+	public let disambiguation: String?
+	public let score: Int?
+}
+
+public struct ArtistCredit: Codable, Sendable {
+	public let name: String
+	public let artist: Artist?
+	public let joinphrase: String?
+}
+
+public struct ReleaseGroup: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .releaseGroup
+
+	public let id: String
+	public let title: String
+	public let primaryType: String?
+	public let artistCredit: [ArtistCredit]?
+	public let disambiguation: String?
+	public let score: Int?
+
+	enum CodingKeys: String, CodingKey {
+		case id, title, disambiguation, score
+		case primaryType = "primary-type"
+		case artistCredit = "artist-credit"
+	}
+}
+
+public struct Series: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .series
+
+	public let id: String
+	public let name: String
+	public let type: String?
+	public let disambiguation: String?
+	public let score: Int?
+}
+
+public struct Work: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .work
+
+	public let id: String
+	public let title: String
+	public let type: String?
+	public let language: String?
+	public let disambiguation: String?
+	public let score: Int?
+}
+
+public struct URLReference: MusicBrainzSearchable {
+	public static let entityType: MusicBrainzEntity = .url
+
+	public let id: String
+	public let resource: String
+	public let score: Int?
+}
+
+// MARK: - Client
+
+public struct MusicBrainzClient: Sendable {
+	public let clientAgent: ClientAgent
+	internal static let baseURL: URL = URL(string: "https://musicbrainz.org/ws/2")!
+
+	public init(clientAgent: ClientAgent) {
+		self.clientAgent = clientAgent
+	}
+
+	private let coordinator: MusicBrainzCoordinator = .init()
+
+	public struct ClientAgent: Sendable, CustomStringConvertible {
+		public let appName: String
+		public let version: String
+		public let email: String
+
+		public init(appName: String, version: String, email: String) {
+			self.appName = appName
+			self.version = version
+			self.email = email
+		}
+
+		public var description: String {
+			"\(appName)/\(version) (\(email))"
+		}
+	}
+
+	internal func fetchRaw(_ endpoint: String, queryItems: [URLQueryItem] = [])
+		async throws(MusicBrainzError) -> Data
+	{
+		let cleanEndpoint = endpoint.hasPrefix("/") ? String(endpoint.dropFirst()) : endpoint
+		let url = MusicBrainzClient.baseURL.appending(path: cleanEndpoint)
+
+		guard var components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
+			throw .badURL
+		}
+
+		var allQueryItems = [URLQueryItem(name: "fmt", value: "json")]
+		allQueryItems.append(contentsOf: queryItems)
+		components.queryItems = allQueryItems
+
+		guard let finalURL = components.url else {
+			throw .badURL
+		}
+
+		var request = URLRequest(url: finalURL)
+		request.setValue(clientAgent.description, forHTTPHeaderField: "User-Agent")
+		request.setValue("application/json", forHTTPHeaderField: "Accept")
+
+		let (data, response) = try await coordinator.perform(request)
+
+		guard let httpResponse = response as? HTTPURLResponse else {
+			throw .badServerResponse(0)
+		}
+
+		guard httpResponse.statusCode == 200 else {
+			throw .badServerResponse(httpResponse.statusCode)
+		}
+
+		return data
+	}
+
+	public func fetch<T>(_ type: MusicBrainzEntityType<T>, id: String)
+		async throws(MusicBrainzError) -> T
+	{
+		let data = try await fetchRaw("/\(type.entity.rawValue)/\(id)")
+		do {
+			return try JSONDecoder().decode(T.self, from: data)
+		} catch {
+			throw .decodingError(error)
+		}
+	}
+
+	public func search<T>(
+		_ action: MusicBrainzSearchAction<T>,
+		limit: Int = 25,
+		offset: Int = 0
+	) async throws(MusicBrainzError) -> SearchResponse<T> {
+		let queryItems = [
+			URLQueryItem(name: "query", value: action.query),
+			URLQueryItem(name: "limit", value: "\(limit)"),
+			URLQueryItem(name: "offset", value: "\(offset)"),
+		]
+		let data = try await fetchRaw("/\(action.entity.rawValue)", queryItems: queryItems)
+		do {
+			return try JSONDecoder().decode(SearchResponse<T>.self, from: data)
+		} catch {
+			throw .decodingError(error)
+		}
+	}
+
+	@available(
+		*, deprecated, message: "Use search(_ action: MusicBrainzSearchAction<T>, ...) instead"
+	)
+	public func search<T>(
+		_ type: MusicBrainzEntityType<T>,
+		query: String,
+		limit: Int = 25,
+		offset: Int = 0
+	) async throws(MusicBrainzError) -> SearchResponse<T> {
+		let queryItems = [
+			URLQueryItem(name: "query", value: query),
+			URLQueryItem(name: "limit", value: "\(limit)"),
+			URLQueryItem(name: "offset", value: "\(offset)"),
+		]
+		let data = try await fetchRaw("/\(type.entity.rawValue)", queryItems: queryItems)
+		do {
+			return try JSONDecoder().decode(SearchResponse<T>.self, from: data)
+		} catch {
+			throw .decodingError(error)
+		}
+	}
+}
+
+// MARK: - Coordinator
+
+public actor MusicBrainzCoordinator {
+	private var nextAvailableTime: ContinuousClock.Instant = .now
+	private let clock = ContinuousClock()
+	private let session: URLSession
+
+	public init(session: URLSession = .shared) {
+		self.session = session
+	}
+
+	public func perform(_ request: URLRequest) async throws(MusicBrainzError) -> (Data, URLResponse)
+	{
+		let now = clock.now
+		let executionTime = max(now, nextAvailableTime)
+		nextAvailableTime = executionTime + .seconds(1)
+		let delay = now.duration(to: executionTime)
+
+		if delay > .zero {
+			do {
+				try await Task.sleep(for: delay)
+			} catch {
+				throw .coordinator(error)
+			}
+		}
+
+		do {
+			return try await session.data(for: request)
+		} catch {
+			throw .coordinator(error)
+		}
+	}
+}
diff --git a/Sources/MusicBrainzExe/main.swift b/Sources/MusicBrainzExe/main.swift
new file mode 100644
index 0000000..244dc3a
--- /dev/null
+++ b/Sources/MusicBrainzExe/main.swift
@@ -0,0 +1,31 @@
+import Foundation
+import MusicBrainz
+
+let client = MusicBrainzClient(
+	clientAgent: .init(appName: "MusicD", version: "0.0.1", email: "test@gmail.com"))
+
+do {
+	print("--- Artist Search: 'Michael Jackson' ---")
+	let artistSearch = try await client.search(
+		.artist(name: "Michael Jackson", gender: .male, country: .us, type: .person), limit: 5)
+	print("Total results: \(artistSearch.count)")
+	for artist in artistSearch.entities {
+		print("- \(artist.name) (\(artist.id))")
+		if let disambiguation = artist.disambiguation {
+			print("  (\(disambiguation))")
+		}
+	}
+
+	print("\n--- Release Search: 'Thriller' ---")
+	let releaseSearch = try await client.search(.release(title: "Thriller"), limit: 5)
+	print("Total results: \(releaseSearch.count)")
+	for release in releaseSearch.entities {
+		print("- \(release.title) (\(release.id))")
+		if let date = release.date {
+			print("  Date: \(date)")
+		}
+	}
+
+} catch {
+	print("Error: \(error)")
+}
diff --git a/Tests/MusicBrainzTests/ExtendedSearchTests.swift b/Tests/MusicBrainzTests/ExtendedSearchTests.swift
new file mode 100644
index 0000000..2c52165
--- /dev/null
+++ b/Tests/MusicBrainzTests/ExtendedSearchTests.swift
@@ -0,0 +1,108 @@
+import Foundation
+import Testing
+
+@testable import MusicBrainz
+
+@Test func testAreaSearchDecoding() throws {
+	let json = """
+		{
+			"created": "2024-05-20T12:00:00.000Z",
+			"count": 1,
+			"offset": 0,
+			"areas": [
+				{
+					"id": "f03ed396-3f4d-4ef4-81b0-7c03c46961e2",
+					"type": "City",
+					"score": 100,
+					"name": "London",
+					"sort-name": "London",
+					"life-span": { "ended": false }
+				}
+			]
+		}
+		""".data(using: .utf8)!
+
+	let response = try JSONDecoder().decode(SearchResponse<Area>.self, from: json)
+
+	#expect(response.count == 1)
+	#expect(response.entities.count == 1)
+	#expect(response.entities[0].name == "London")
+	#expect(response.entities[0].score == 100)
+}
+
+@Test func testReleaseGroupSearchDecoding() throws {
+	let json = """
+		{
+			"created": "2024-05-20T12:00:00.000Z",
+			"count": 1,
+			"offset": 0,
+			"release-groups": [
+				{
+					"id": "1b022e01-4da6-387b-8658-8678046e4ccc",
+					"score": 100,
+					"primary-type": "Album",
+					"title": "Nevermind",
+					"artist-credit": [{ "name": "Nirvana" }]
+				}
+			]
+		}
+		""".data(using: .utf8)!
+
+	let response = try JSONDecoder().decode(SearchResponse<ReleaseGroup>.self, from: json)
+
+	#expect(response.count == 1)
+	#expect(response.entities.count == 1)
+	#expect(response.entities[0].title == "Nevermind")
+	#expect(response.entities[0].primaryType == "Album")
+	#expect(response.entities[0].artistCredit?[0].name == "Nirvana")
+}
+
+@Test func testLabelSearchDecoding() throws {
+	let json = """
+		{
+			"created": "2024-05-20T12:00:00.000Z",
+			"count": 1,
+			"offset": 0,
+			"labels": [
+				{
+					"id": "79239441-bfd5-4981-a70c-55c3f15c1287",
+					"type": "Production",
+					"score": 100,
+					"name": "Ninja Tune",
+					"label-code": 12885,
+					"country": "GB"
+				}
+			]
+		}
+		""".data(using: .utf8)!
+
+	let response = try JSONDecoder().decode(SearchResponse<Label>.self, from: json)
+
+	#expect(response.count == 1)
+	#expect(response.entities.count == 1)
+	#expect(response.entities[0].name == "Ninja Tune")
+	#expect(response.entities[0].labelCode == 12885)
+}
+
+@Test func testURLSearchDecoding() throws {
+	let json = """
+		{
+			"created": "2024-05-20T12:00:00.000Z",
+			"count": 1,
+			"offset": 0,
+			"urls": [
+				{
+					"id": "b663423b-9b54-4067-9674-fffaecf68851",
+					"resource": "http://www.madonna.com/",
+					"score": 100
+				}
+			]
+		}
+		""".data(using: .utf8)!
+
+	let response = try JSONDecoder().decode(SearchResponse<URLReference>.self, from: json)
+
+	#expect(response.count == 1)
+	#expect(response.entities.count == 1)
+	#expect(response.entities[0].resource == "http://www.madonna.com/")
+}
diff --git a/Tests/MusicBrainzTests/MusicBrainzTests.swift b/Tests/MusicBrainzTests/MusicBrainzTests.swift
new file mode 100644
index 0000000..299e739
--- /dev/null
+++ b/Tests/MusicBrainzTests/MusicBrainzTests.swift
@@ -0,0 +1,54 @@
+import Foundation
+import Testing
+
+@testable import MusicBrainz
+
+#if canImport(FoundationNetworking)
+	import FoundationNetworking
+#endif
+
+@Test func testArtistDecoding() throws {
+	let json = """
+		{
+		    "id": "f27ec8db-af05-4f36-916e-3d57f91ecf5e",
+		    "name": "Michael Jackson",
+		    "sort-name": "Jackson, Michael",
+		    "type": "Person",
+		    "country": "US",
+		    "disambiguation": "“King of Pop”"
+		}
+		""".data(using: .utf8)!
+
+	let artist = try JSONDecoder().decode(Artist.self, from: json)
+
+	#expect(artist.id == "f27ec8db-af05-4f36-916e-3d57f91ecf5e")
+	#expect(artist.name == "Michael Jackson")
+	#expect(artist.sortName == "Jackson, Michael")
+	#expect(artist.type == "Person")
+	#expect(artist.country == "US")
+	#expect(artist.disambiguation == "“King of Pop”")
+}
+
+@Test func testCoordinatorRateLimiting() async throws {
+	let coordinator = MusicBrainzCoordinator()
+	let request = URLRequest(url: URL(string: "https://example.com")!)
+
+	let clock = ContinuousClock()
+	let start = clock.now
+
+	// Perform 3 requests concurrently
+	try await withThrowingTaskGroup(of: Void.self) { group in
+		for _ in 0..<3 {
+			group.addTask {
+				_ = try await coordinator.perform(request)
+			}
+		}
+	}
+
+	let duration = start.duration(to: clock.now)
+
+	// 3 requests should take at least 2 seconds (0s, 1s, 2s)
+	// We check for > 1.9s to account for small timing variations
+	#expect(duration >= .seconds(2))
+	print("DEBUG: Total duration for 3 requests: \(duration)")
+}
diff --git a/Tests/MusicBrainzTests/QueryTests.swift b/Tests/MusicBrainzTests/QueryTests.swift
new file mode 100644
index 0000000..03a0d73
--- /dev/null
+++ b/Tests/MusicBrainzTests/QueryTests.swift
@@ -0,0 +1,36 @@
+import Foundation
+import Testing
+
+@testable import MusicBrainz
+
+@Test func testArtistQueryBuilding() throws {
+	let action: MusicBrainzSearchAction<Artist> = .artist(name: "Michael Jackson", gender: .male, country: .us)
+	#expect(action.query.contains("artist:\"Michael Jackson\""))
+	#expect(action.query.contains("gender:\"male\""))
+	#expect(action.query.contains("country:\"US\""))
+}
+
+@Test func testReleaseQueryBuilding() throws {
+	let action: MusicBrainzSearchAction<Release> = .release(title: "Thriller", artist: "Michael Jackson", barcode: "07464381122")
+	#expect(action.query.contains("release:\"Thriller\""))
+	#expect(action.query.contains("artist:\"Michael Jackson\""))
+	#expect(action.query.contains("barcode:\"07464381122\""))
+}
+
+@Test func testRecordingQueryBuilding() throws {
+	let action: MusicBrainzSearchAction<Recording> = .recording(title: "Billie Jean", isrc: "USSM18200385", video: true)
+	#expect(action.query.contains("recording:\"Billie Jean\""))
+	#expect(action.query.contains("isrc:\"USSM18200385\""))
+	#expect(action.query.contains("video:\"true\""))
+}
+
+@Test func testRawQueryBuilding() throws {
+	let action: MusicBrainzSearchAction<Artist> = .artist(name: "Prince", raw: "type:person")
+	#expect(action.query.contains("artist:\"Prince\""))
+	#expect(action.query.contains("type:person"))
+}
+
+@Test func testQueryEscaping() throws {
+	let action: MusicBrainzSearchAction<Artist> = .artist(name: "Artist \"Quote\" Name")
+	#expect(action.query == "artist:\"Artist \\\"Quote\\\" Name\"")
+}
diff --git a/Tests/MusicBrainzTests/SearchTests.swift b/Tests/MusicBrainzTests/SearchTests.swift
new file mode 100644
index 0000000..51301e3
--- /dev/null
+++ b/Tests/MusicBrainzTests/SearchTests.swift
@@ -0,0 +1,30 @@
+import Foundation
+import Testing
+
+@testable import MusicBrainz
+
+@Test func testArtistSearchDecoding() throws {
+	let json = """
+		{
+		    "created": "2026-03-20T22:42:03.521Z",
+		    "count": 1,
+		    "offset": 0,
+		    "artists": [
+		        {
+		            "id": "f27ec8db-af05-4f36-916e-3d57f91ecf5e",
+		            "type": "Person",
+		            "name": "Michael Jackson",
+		            "sort-name": "Jackson, Michael",
+		            "country": "US",
+		            "disambiguation": "“King of Pop”"
+		        }
+		    ]
+		}
+		""".data(using: .utf8)!
+
+	let response = try JSONDecoder().decode(SearchResponse<Artist>.self, from: json)
+
+	#expect(response.count == 1)
+	#expect(response.entities.count == 1)
+	#expect(response.entities[0].name == "Michael Jackson")
+}