@zivue/zuuid 0.2.2 → 0.2.5

package/dist/providers/musicbrainz/client.js

@@ -0,0 +1,169 @@
+import { providerZuuid } from "../../identity.js";
+import { createSourceRecord } from "../../source.js";
+import { datePrefix, nestedString, objectPayload, stringField, valueAsString } from "../common.js";
+import { MUSICBRAINZ_API_BASE, MUSICBRAINZ_ARTIST_CATEGORY, MUSICBRAINZ_COVER_ART_BASE_URL, MUSICBRAINZ_DEFAULT_USER_AGENT, MUSICBRAINZ_LABEL_CATEGORY, MUSICBRAINZ_PROVIDER, MUSICBRAINZ_RECORDING_CATEGORY, MUSICBRAINZ_RELEASE_CATEGORY, MUSICBRAINZ_RELEASE_GROUP_CATEGORY, MUSICBRAINZ_RELEASE_GROUP_COVER_ART_BASE_URL, MUSICBRAINZ_WORK_CATEGORY } from "./constants.js";
+import { transformMusicBrainzArtist } from "./artist.js";
+import { transformMusicBrainzLabel } from "./label.js";
+import { transformMusicBrainzRecording } from "./recording.js";
+import { transformMusicBrainzRelease } from "./release.js";
+import { transformMusicBrainzReleaseGroup } from "./release-group.js";
+import { transformMusicBrainzWork } from "./work.js";
+export class MusicBrainzProvider {
+    apiBase;
+    coverArtBaseUrl;
+    releaseGroupCoverArtBaseUrl;
+    userAgent;
+    fetchImpl;
+    constructor(options = {}) {
+        this.apiBase = options.apiBase ?? MUSICBRAINZ_API_BASE;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.coverArtBaseUrl = options.coverArtBaseUrl === undefined ? MUSICBRAINZ_COVER_ART_BASE_URL : options.coverArtBaseUrl;
+        this.releaseGroupCoverArtBaseUrl = options.releaseGroupCoverArtBaseUrl === undefined ? MUSICBRAINZ_RELEASE_GROUP_COVER_ART_BASE_URL : options.releaseGroupCoverArtBaseUrl;
+        this.userAgent = options.userAgent ?? MUSICBRAINZ_DEFAULT_USER_AGENT;
+    }
+    async getJson(path, params) {
+        const url = new URL(`${this.apiBase.replace(/\/$/, "")}/${path.replace(/^\//, "")}`);
+        url.searchParams.set("fmt", "json");
+        for (const [key, value] of Object.entries(params))
+            url.searchParams.set(key, value);
+        const response = await this.fetchImpl(url, { headers: { accept: "application/json", "user-agent": this.userAgent } });
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`MusicBrainz API returned ${response.status}: ${body}`);
+        }
+        return response.json();
+    }
+    transformOptions() {
+        return { coverArtBaseUrl: this.coverArtBaseUrl, releaseGroupCoverArtBaseUrl: this.releaseGroupCoverArtBaseUrl };
+    }
+    async fetchReleaseSourceRecord(input) { return fetchMusicBrainzSourceRecord(this, MUSICBRAINZ_RELEASE_CATEGORY, input); }
+    async fetchRelease(input) { const source = await this.fetchReleaseSourceRecord(input); return source ? transformMusicBrainzRelease(source, this.transformOptions()) : undefined; }
+    async searchReleaseSourceRecords(input) { return searchMusicBrainzSourceRecords(this, MUSICBRAINZ_RELEASE_CATEGORY, input); }
+    async searchReleases(input) { return searchMusicBrainz(this, MUSICBRAINZ_RELEASE_CATEGORY, input, this.transformOptions()); }
+    async fetchReleaseGroupSourceRecord(input) { return fetchMusicBrainzSourceRecord(this, MUSICBRAINZ_RELEASE_GROUP_CATEGORY, input); }
+    async fetchReleaseGroup(input) { const source = await this.fetchReleaseGroupSourceRecord(input); return source ? transformMusicBrainzReleaseGroup(source, { coverArtBaseUrl: this.releaseGroupCoverArtBaseUrl }) : undefined; }
+    async searchReleaseGroupSourceRecords(input) { return searchMusicBrainzSourceRecords(this, MUSICBRAINZ_RELEASE_GROUP_CATEGORY, input); }
+    async searchReleaseGroups(input) { return searchMusicBrainz(this, MUSICBRAINZ_RELEASE_GROUP_CATEGORY, input, this.transformOptions()); }
+    async fetchRecordingSourceRecord(input) { return fetchMusicBrainzSourceRecord(this, MUSICBRAINZ_RECORDING_CATEGORY, input); }
+    async fetchRecording(input) { const source = await this.fetchRecordingSourceRecord(input); return source ? transformMusicBrainzRecording(source) : undefined; }
+    async searchRecordingSourceRecords(input) { return searchMusicBrainzSourceRecords(this, MUSICBRAINZ_RECORDING_CATEGORY, input); }
+    async searchRecordings(input) { return searchMusicBrainz(this, MUSICBRAINZ_RECORDING_CATEGORY, input, this.transformOptions()); }
+    async fetchArtistSourceRecord(input) { return fetchMusicBrainzSourceRecord(this, MUSICBRAINZ_ARTIST_CATEGORY, input); }
+    async fetchArtist(input) { const source = await this.fetchArtistSourceRecord(input); return source ? transformMusicBrainzArtist(source) : undefined; }
+    async searchArtistSourceRecords(input) { return searchMusicBrainzSourceRecords(this, MUSICBRAINZ_ARTIST_CATEGORY, input); }
+    async searchArtists(input) { return searchMusicBrainz(this, MUSICBRAINZ_ARTIST_CATEGORY, input, this.transformOptions()); }
+    async fetchLabelSourceRecord(input) { return fetchMusicBrainzSourceRecord(this, MUSICBRAINZ_LABEL_CATEGORY, input); }
+    async fetchLabel(input) { const source = await this.fetchLabelSourceRecord(input); return source ? transformMusicBrainzLabel(source) : undefined; }
+    async searchLabelSourceRecords(input) { return searchMusicBrainzSourceRecords(this, MUSICBRAINZ_LABEL_CATEGORY, input); }
+    async searchLabels(input) { return searchMusicBrainz(this, MUSICBRAINZ_LABEL_CATEGORY, input, this.transformOptions()); }
+    async fetchWorkSourceRecord(input) { return fetchMusicBrainzSourceRecord(this, MUSICBRAINZ_WORK_CATEGORY, input); }
+    async fetchWork(input) { const source = await this.fetchWorkSourceRecord(input); return source ? transformMusicBrainzWork(source) : undefined; }
+    async searchWorkSourceRecords(input) { return searchMusicBrainzSourceRecords(this, MUSICBRAINZ_WORK_CATEGORY, input); }
+    async searchWorks(input) { return searchMusicBrainz(this, MUSICBRAINZ_WORK_CATEGORY, input, this.transformOptions()); }
+}
+export async function fetchMusicBrainzSourceRecord(provider, category, input) {
+    const id = musicBrainzId(input.id);
+    const payload = await provider.getJson(`/${entityPath(category)}/${id}`, { inc: lookupIncludes(category) });
+    if (!payload)
+        return undefined;
+    return createSourceRecord({ source: { provider: MUSICBRAINZ_PROVIDER, category, externalId: id }, payload });
+}
+export async function searchMusicBrainzSourceRecords(provider, category, input) {
+    const payload = await searchPayload(provider, category, input);
+    const results = searchItems(payload, category);
+    return {
+        results: await Promise.all(results.map((item) => createSourceRecord({ source: { provider: MUSICBRAINZ_PROVIDER, category, externalId: stringField(item, "id") ?? "" }, payload: item }))),
+        pagination: pagination(payload)
+    };
+}
+export async function searchMusicBrainz(provider, category, input, options = {}) {
+    const payload = await searchPayload(provider, category, input);
+    const results = [];
+    for (const item of searchItems(payload, category)) {
+        const externalId = stringField(item, "id");
+        const title = titleFor(item, category);
+        if (!externalId || !title)
+            continue;
+        const zuuid = await providerZuuid({ provider: MUSICBRAINZ_PROVIDER, category, externalId });
+        results.push({
+            id: zuuid,
+            zuuid,
+            category: publicCategory(category),
+            title,
+            date: dateFor(item, category),
+            cover: coverFor(item, category, options),
+            rating: null,
+            weight: numberValue(item.score),
+            relationType: null,
+            attribute: attributeFor(item, category),
+            order: null,
+            source: { source: MUSICBRAINZ_PROVIDER, category, value: externalId }
+        });
+    }
+    return { results, pagination: pagination(payload) };
+}
+async function searchPayload(provider, category, input) {
+    const query = input.query.trim();
+    if (!query)
+        throw new Error("MusicBrainz search query must not be empty");
+    return objectPayload(await provider.getJson(`/${entityPath(category)}`, {
+        query,
+        limit: String(input.limit ?? 25),
+        offset: String(input.offset ?? 0)
+    }) ?? {});
+}
+function searchItems(payload, category) {
+    const value = payload[searchKey(category)];
+    return Array.isArray(value) ? value.filter(isObject) : [];
+}
+function pagination(payload) {
+    const count = numberValue(payload.count) ?? 0;
+    const offset = numberValue(payload.offset) ?? 0;
+    const limit = Array.isArray(payload[searchKeyFromPayload(payload)]) ? payload[searchKeyFromPayload(payload)].length : 0;
+    return { page: limit > 0 ? Math.floor(offset / limit) + 1 : 1, totalPages: limit > 0 ? Math.ceil(count / limit) : 0, totalResults: count };
+}
+function searchKeyFromPayload(payload) {
+    return ["releases", "release-groups", "recordings", "artists", "labels", "works"].find((key) => Array.isArray(payload[key])) ?? "";
+}
+function lookupIncludes(category) {
+    switch (category) {
+        case MUSICBRAINZ_RELEASE_CATEGORY:
+            return "artists+labels+release-groups+media+recordings+genres+tags+url-rels";
+        case MUSICBRAINZ_RELEASE_GROUP_CATEGORY:
+            return "artists+releases+genres+tags+url-rels";
+        case MUSICBRAINZ_RECORDING_CATEGORY:
+            return "artists+releases+isrcs+genres+tags+work-rels+url-rels";
+        case MUSICBRAINZ_ARTIST_CATEGORY:
+            return "aliases+annotation+genres+tags+area-rels+url-rels";
+        case MUSICBRAINZ_LABEL_CATEGORY:
+            return "aliases+annotation+genres+tags+area-rels+url-rels";
+        case MUSICBRAINZ_WORK_CATEGORY:
+            return "aliases+annotation+artists+iswcs+genres+tags+artist-rels+url-rels";
+        default:
+            return "genres+tags";
+    }
+}
+function entityPath(category) { return category === MUSICBRAINZ_RELEASE_GROUP_CATEGORY ? "release-group" : category; }
+function searchKey(category) { return category === MUSICBRAINZ_RELEASE_GROUP_CATEGORY ? "release-groups" : `${category}s`; }
+function publicCategory(category) { return category === MUSICBRAINZ_RELEASE_GROUP_CATEGORY ? "release_group" : category === MUSICBRAINZ_WORK_CATEGORY ? "musical_work" : category; }
+function titleFor(item, category) { return category === MUSICBRAINZ_ARTIST_CATEGORY || category === MUSICBRAINZ_LABEL_CATEGORY ? stringField(item, "name") : stringField(item, "title"); }
+function dateFor(item, category) { return (category === MUSICBRAINZ_RELEASE_GROUP_CATEGORY ? stringField(item, "first-release-date") : category === MUSICBRAINZ_RECORDING_CATEGORY ? stringField(item, "first-release-date") : category === MUSICBRAINZ_ARTIST_CATEGORY || category === MUSICBRAINZ_LABEL_CATEGORY ? nestedString(item, ["life-span", "begin"]) : stringField(item, "date")) ?? null; }
+function attributeFor(item, category) { return category === MUSICBRAINZ_ARTIST_CATEGORY || category === MUSICBRAINZ_LABEL_CATEGORY || category === MUSICBRAINZ_WORK_CATEGORY ? stringField(item, "type") ?? null : stringField(item, "primary-type") ?? stringField(item, "status") ?? null; }
+function coverFor(item, category, options) { const id = stringField(item, "id"); if (!id)
+    return null; if (category === MUSICBRAINZ_RELEASE_GROUP_CATEGORY && options.releaseGroupCoverArtBaseUrl)
+    return `${options.releaseGroupCoverArtBaseUrl.replace(/\/$/, "")}/${id}/front`; if (category === MUSICBRAINZ_RELEASE_CATEGORY && options.coverArtBaseUrl && objectPayload(item["cover-art-archive"] ?? {}).front === true)
+    return `${options.coverArtBaseUrl.replace(/\/$/, "")}/${id}/front`; return null; }
+function numberValue(value) { if (typeof value === "number" && Number.isFinite(value))
+    return value; if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+} return null; }
+function isObject(value) { return !!value && typeof value === "object" && !Array.isArray(value); }
+function musicBrainzId(value) {
+    const id = value.trim();
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id))
+        throw new Error(`Invalid MusicBrainz MBID: ${value}`);
+    return id.toLowerCase();
+}

package/dist/providers/musicbrainz/constants.d.ts

@@ -7,4 +7,6 @@ export declare const MUSICBRAINZ_LABEL_CATEGORY = "label";
 export declare const MUSICBRAINZ_WORK_CATEGORY = "work";
 export declare const MUSICBRAINZ_COVER_ART_BASE_URL = "https://coverartarchive.org/release";
 export declare const MUSICBRAINZ_RELEASE_GROUP_COVER_ART_BASE_URL = "https://coverartarchive.org/release-group";
+export declare const MUSICBRAINZ_API_BASE = "https://musicbrainz.org/ws/2";
+export declare const MUSICBRAINZ_DEFAULT_USER_AGENT = "@zivue/zuuid/0.2.5 (https://github.com/zivue/zuuid)";
 //# sourceMappingURL=constants.d.ts.map

package/dist/providers/musicbrainz/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/providers/musicbrainz/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAClD,eAAO,MAAM,4BAA4B,YAAY,CAAC;AACtD,eAAO,MAAM,kCAAkC,kBAAkB,CAAC;AAClE,eAAO,MAAM,8BAA8B,cAAc,CAAC;AAC1D,eAAO,MAAM,2BAA2B,WAAW,CAAC;AACpD,eAAO,MAAM,0BAA0B,UAAU,CAAC;AAClD,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAChD,eAAO,MAAM,8BAA8B,wCAAwC,CAAC;AACpF,eAAO,MAAM,4CAA4C,8CAA8C,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/providers/musicbrainz/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAClD,eAAO,MAAM,4BAA4B,YAAY,CAAC;AACtD,eAAO,MAAM,kCAAkC,kBAAkB,CAAC;AAClE,eAAO,MAAM,8BAA8B,cAAc,CAAC;AAC1D,eAAO,MAAM,2BAA2B,WAAW,CAAC;AACpD,eAAO,MAAM,0BAA0B,UAAU,CAAC;AAClD,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAChD,eAAO,MAAM,8BAA8B,wCAAwC,CAAC;AACpF,eAAO,MAAM,4CAA4C,8CAA8C,CAAC;AACxG,eAAO,MAAM,oBAAoB,iCAAiC,CAAC;AACnE,eAAO,MAAM,8BAA8B,wDAAwD,CAAC"}

package/dist/providers/musicbrainz/constants.js

@@ -7,3 +7,5 @@ export const MUSICBRAINZ_LABEL_CATEGORY = "label";
 export const MUSICBRAINZ_WORK_CATEGORY = "work";
 export const MUSICBRAINZ_COVER_ART_BASE_URL = "https://coverartarchive.org/release";
 export const MUSICBRAINZ_RELEASE_GROUP_COVER_ART_BASE_URL = "https://coverartarchive.org/release-group";
+export const MUSICBRAINZ_API_BASE = "https://musicbrainz.org/ws/2";
+export const MUSICBRAINZ_DEFAULT_USER_AGENT = "@zivue/zuuid/0.2.5 (https://github.com/zivue/zuuid)";

package/dist/providers/musicbrainz/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./client.js";
 export * from "./artist.js";
 export * from "./constants.js";
 export * from "./label.js";
@@ -5,4 +6,5 @@ export * from "./recording.js";
 export * from "./release.js";
 export * from "./release-group.js";
 export * from "./work.js";
+export * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/musicbrainz/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/musicbrainz/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/musicbrainz/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/providers/musicbrainz/index.js

@@ -1,3 +1,4 @@
+export * from "./client.js";
 export * from "./artist.js";
 export * from "./constants.js";
 export * from "./label.js";
@@ -5,3 +6,4 @@ export * from "./recording.js";
 export * from "./release.js";
 export * from "./release-group.js";
 export * from "./work.js";
+export * from "./types.js";

package/dist/providers/musicbrainz/types.d.ts

@@ -0,0 +1,21 @@
+export type MusicBrainzFetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type MusicBrainzProviderOptions = {
+    apiBase?: string;
+    fetch?: MusicBrainzFetchLike;
+    userAgent?: string;
+    coverArtBaseUrl?: string | null;
+    releaseGroupCoverArtBaseUrl?: string | null;
+};
+export type MusicBrainzProviderTransformOptions = {
+    coverArtBaseUrl?: string | null;
+    releaseGroupCoverArtBaseUrl?: string | null;
+};
+export type FetchMusicBrainzInput = {
+    id: string;
+};
+export type MusicBrainzSearchInput = {
+    query: string;
+    limit?: number;
+    offset?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/musicbrainz/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/providers/musicbrainz/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElG,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,mCAAmC,GAAG;IAChD,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/dist/providers/musicbrainz/types.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/openstreetmap/city.d.ts

@@ -0,0 +1,2 @@
+export { transformOpenStreetMapPlace as transformOpenStreetMapCity } from "./place.js";
+//# sourceMappingURL=city.d.ts.map

package/dist/providers/openstreetmap/city.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"city.d.ts","sourceRoot":"","sources":["../../../src/providers/openstreetmap/city.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,IAAI,0BAA0B,EAAE,MAAM,YAAY,CAAC"}

package/dist/providers/openstreetmap/city.js

@@ -0,0 +1 @@
+export { transformOpenStreetMapPlace as transformOpenStreetMapCity } from "./place.js";

package/dist/providers/openstreetmap/client.d.ts

@@ -0,0 +1,31 @@
+import type { SearchResponse, ZuuidData, ZuuidSearchResult } from "../../entity.js";
+import { type SourceRecord } from "../../source.js";
+import type { FetchOpenStreetMapInput, OpenStreetMapProviderOptions, OpenStreetMapSearchInput } from "./types.js";
+export declare class OpenStreetMapProvider {
+    readonly apiBase: string;
+    readonly userAgent: string;
+    readonly language: string;
+    private readonly fetchImpl;
+    constructor(options?: OpenStreetMapProviderOptions);
+    getJson<T>(path: string, params: Record<string, string>): Promise<T | undefined>;
+    fetchCitySourceRecord(input: FetchOpenStreetMapInput): Promise<SourceRecord | undefined>;
+    fetchCity(input: FetchOpenStreetMapInput): Promise<ZuuidData | undefined>;
+    searchCitySourceRecords(input: OpenStreetMapSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchCities(input: OpenStreetMapSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+    fetchCountrySourceRecord(input: FetchOpenStreetMapInput): Promise<SourceRecord | undefined>;
+    fetchCountry(input: FetchOpenStreetMapInput): Promise<ZuuidData | undefined>;
+    searchCountrySourceRecords(input: OpenStreetMapSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchCountries(input: OpenStreetMapSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+    fetchPlaceSourceRecord(input: FetchOpenStreetMapInput): Promise<SourceRecord | undefined>;
+    fetchPlace(input: FetchOpenStreetMapInput): Promise<ZuuidData | undefined>;
+    searchPlaceSourceRecords(input: OpenStreetMapSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchPlaces(input: OpenStreetMapSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+    fetchVenueSourceRecord(input: FetchOpenStreetMapInput): Promise<SourceRecord | undefined>;
+    fetchVenue(input: FetchOpenStreetMapInput): Promise<ZuuidData | undefined>;
+    searchVenueSourceRecords(input: OpenStreetMapSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchVenues(input: OpenStreetMapSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+}
+export declare function fetchOpenStreetMapSourceRecord(provider: OpenStreetMapProvider, category: string, input: FetchOpenStreetMapInput): Promise<SourceRecord | undefined>;
+export declare function searchOpenStreetMapSourceRecords(provider: OpenStreetMapProvider, category: string, input: OpenStreetMapSearchInput): Promise<SearchResponse<SourceRecord>>;
+export declare function searchOpenStreetMap(provider: OpenStreetMapProvider, category: string, input: OpenStreetMapSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/providers/openstreetmap/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/providers/openstreetmap/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpF,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAaxE,OAAO,KAAK,EAAE,uBAAuB,EAA0B,4BAA4B,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAK1I,qBAAa,qBAAqB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBAEvC,OAAO,GAAE,4BAAiC;IAOhD,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAYhF,qBAAqB,CAAC,KAAK,EAAE,uBAAuB;IACpD,SAAS,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IACzE,uBAAuB,CAAC,KAAK,EAAE,wBAAwB;IACvD,YAAY,CAAC,KAAK,EAAE,wBAAwB;IAE5C,wBAAwB,CAAC,KAAK,EAAE,uBAAuB;IACvD,YAAY,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5E,0BAA0B,CAAC,KAAK,EAAE,wBAAwB;IAC1D,eAAe,CAAC,KAAK,EAAE,wBAAwB;IAE/C,sBAAsB,CAAC,KAAK,EAAE,uBAAuB;IACrD,UAAU,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1E,wBAAwB,CAAC,KAAK,EAAE,wBAAwB;IACxD,YAAY,CAAC,KAAK,EAAE,wBAAwB;IAE5C,sBAAsB,CAAC,KAAK,EAAE,uBAAuB;IACrD,UAAU,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1E,wBAAwB,CAAC,KAAK,EAAE,wBAAwB;IACxD,YAAY,CAAC,KAAK,EAAE,wBAAwB;CACnD;AAED,wBAAsB,8BAA8B,CAAC,QAAQ,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAYzK;AAED,wBAAsB,gCAAgC,CAAC,QAAQ,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAOhL;AAED,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC,CAyBxK"}

package/dist/providers/openstreetmap/client.js

@@ -0,0 +1,146 @@
+import { providerZuuid } from "../../identity.js";
+import { createSourceRecord } from "../../source.js";
+import { nestedString, normalizeRating, objectPayload, stringField, valueAsString } from "../common.js";
+import { OPENSTREETMAP_API_BASE, OPENSTREETMAP_CITY_CATEGORY, OPENSTREETMAP_COUNTRY_CATEGORY, OPENSTREETMAP_DEFAULT_USER_AGENT, OPENSTREETMAP_PLACE_CATEGORY, OPENSTREETMAP_PROVIDER, OPENSTREETMAP_VENUE_CATEGORY } from "./constants.js";
+import { transformOpenStreetMapPlace } from "./place.js";
+const CATEGORIES = [OPENSTREETMAP_CITY_CATEGORY, OPENSTREETMAP_COUNTRY_CATEGORY, OPENSTREETMAP_PLACE_CATEGORY, OPENSTREETMAP_VENUE_CATEGORY];
+export class OpenStreetMapProvider {
+    apiBase;
+    userAgent;
+    language;
+    fetchImpl;
+    constructor(options = {}) {
+        this.apiBase = options.apiBase ?? OPENSTREETMAP_API_BASE;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.userAgent = options.userAgent ?? OPENSTREETMAP_DEFAULT_USER_AGENT;
+        this.language = options.language ?? "en-US,en;q=0.9";
+    }
+    async getJson(path, params) {
+        const url = new URL(`${this.apiBase.replace(/\/$/, "")}/${path.replace(/^\//, "")}`);
+        for (const [key, value] of Object.entries(params))
+            url.searchParams.set(key, value);
+        const response = await this.fetchImpl(url, { headers: { accept: "application/json", "accept-language": this.language, "user-agent": this.userAgent } });
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`OpenStreetMap API returned ${response.status}: ${body}`);
+        }
+        return response.json();
+    }
+    async fetchCitySourceRecord(input) { return fetchOpenStreetMapSourceRecord(this, OPENSTREETMAP_CITY_CATEGORY, input); }
+    async fetchCity(input) { const source = await this.fetchCitySourceRecord(input); return source ? transformOpenStreetMapPlace(source) : undefined; }
+    async searchCitySourceRecords(input) { return searchOpenStreetMapSourceRecords(this, OPENSTREETMAP_CITY_CATEGORY, input); }
+    async searchCities(input) { return searchOpenStreetMap(this, OPENSTREETMAP_CITY_CATEGORY, input); }
+    async fetchCountrySourceRecord(input) { return fetchOpenStreetMapSourceRecord(this, OPENSTREETMAP_COUNTRY_CATEGORY, input); }
+    async fetchCountry(input) { const source = await this.fetchCountrySourceRecord(input); return source ? transformOpenStreetMapPlace(source) : undefined; }
+    async searchCountrySourceRecords(input) { return searchOpenStreetMapSourceRecords(this, OPENSTREETMAP_COUNTRY_CATEGORY, input); }
+    async searchCountries(input) { return searchOpenStreetMap(this, OPENSTREETMAP_COUNTRY_CATEGORY, input); }
+    async fetchPlaceSourceRecord(input) { return fetchOpenStreetMapSourceRecord(this, OPENSTREETMAP_PLACE_CATEGORY, input); }
+    async fetchPlace(input) { const source = await this.fetchPlaceSourceRecord(input); return source ? transformOpenStreetMapPlace(source) : undefined; }
+    async searchPlaceSourceRecords(input) { return searchOpenStreetMapSourceRecords(this, OPENSTREETMAP_PLACE_CATEGORY, input); }
+    async searchPlaces(input) { return searchOpenStreetMap(this, OPENSTREETMAP_PLACE_CATEGORY, input); }
+    async fetchVenueSourceRecord(input) { return fetchOpenStreetMapSourceRecord(this, OPENSTREETMAP_VENUE_CATEGORY, input); }
+    async fetchVenue(input) { const source = await this.fetchVenueSourceRecord(input); return source ? transformOpenStreetMapPlace(source) : undefined; }
+    async searchVenueSourceRecords(input) { return searchOpenStreetMapSourceRecords(this, OPENSTREETMAP_VENUE_CATEGORY, input); }
+    async searchVenues(input) { return searchOpenStreetMap(this, OPENSTREETMAP_VENUE_CATEGORY, input); }
+}
+export async function fetchOpenStreetMapSourceRecord(provider, category, input) {
+    const osmId = normalizeOsmId(input.id);
+    const payload = await provider.getJson("/lookup", {
+        osm_ids: osmId,
+        format: "jsonv2",
+        addressdetails: "1",
+        extratags: "1",
+        namedetails: "1"
+    });
+    const item = Array.isArray(payload) ? payload.find(isObject) : undefined;
+    if (!item)
+        return undefined;
+    return createSourceRecord({ source: { provider: OPENSTREETMAP_PROVIDER, category: requireCategory(category), externalId: osmId }, payload: item });
+}
+export async function searchOpenStreetMapSourceRecords(provider, category, input) {
+    const items = await searchPayload(provider, input);
+    const normalizedCategory = requireCategory(category);
+    return {
+        results: await Promise.all(items.map((item) => createSourceRecord({ source: { provider: OPENSTREETMAP_PROVIDER, category: normalizedCategory, externalId: osmExternalId(item) ?? valueAsString(item.place_id) ?? "" }, payload: item }))),
+        pagination: pagination(items, input.limit)
+    };
+}
+export async function searchOpenStreetMap(provider, category, input) {
+    const items = await searchPayload(provider, input);
+    const normalizedCategory = requireCategory(category);
+    const results = [];
+    for (const item of items) {
+        const externalId = osmExternalId(item) ?? valueAsString(item.place_id);
+        const title = stringField(item, "name") ?? stringField(item, "display_name");
+        if (!externalId || !title)
+            continue;
+        const zuuid = await providerZuuid({ provider: OPENSTREETMAP_PROVIDER, category: normalizedCategory, externalId });
+        results.push({
+            id: zuuid,
+            zuuid,
+            category: normalizedCategory,
+            title,
+            date: null,
+            cover: stringField(item, "icon") ?? null,
+            rating: normalizeRating(typeof item.importance === "number" ? item.importance : undefined, 0, 1) ?? null,
+            weight: typeof item.importance === "number" ? item.importance : null,
+            relationType: null,
+            attribute: [stringField(item, "class"), stringField(item, "type")].filter(Boolean).join(":") || null,
+            order: null,
+            source: { source: OPENSTREETMAP_PROVIDER, category: normalizedCategory, value: externalId }
+        });
+    }
+    return { results, pagination: pagination(items, input.limit) };
+}
+async function searchPayload(provider, input) {
+    const query = input.query.trim();
+    if (!query)
+        throw new Error("OpenStreetMap search query must not be empty");
+    const payload = await provider.getJson("/search", {
+        q: query,
+        format: "jsonv2",
+        addressdetails: "1",
+        extratags: "1",
+        namedetails: "1",
+        limit: String(input.limit ?? 10),
+        ...(input.language ? { "accept-language": input.language } : {})
+    });
+    return Array.isArray(payload) ? payload.filter(isObject) : [];
+}
+function pagination(items, limit) {
+    const pageSize = limit ?? items.length;
+    return { page: 1, totalPages: pageSize > 0 && items.length > 0 ? 1 : 0, totalResults: items.length };
+}
+function normalizeOsmId(value) {
+    const raw = String(value).trim();
+    const prefixed = raw.match(/^([NWR])\s*(\d+)$/i);
+    if (prefixed)
+        return `${prefixed[1].toUpperCase()}${prefixed[2]}`;
+    const typed = raw.match(/^(node|way|relation)[-:\s]*(\d+)$/i);
+    if (typed)
+        return `${typePrefix(typed[1])}${typed[2]}`;
+    if (/^\d+$/.test(raw))
+        throw new Error(`OpenStreetMap id must include an OSM type prefix N, W, or R: ${value}`);
+    throw new Error(`Invalid OpenStreetMap id: ${value}`);
+}
+function typePrefix(value) {
+    const normalized = value.toLowerCase();
+    return normalized === "node" ? "N" : normalized === "way" ? "W" : "R";
+}
+function osmExternalId(payload) {
+    const osmType = stringField(payload, "osm_type");
+    const id = valueAsString(payload.osm_id);
+    if (!osmType || !id)
+        return undefined;
+    return `${typePrefix(osmType)}${id}`;
+}
+function requireCategory(category) {
+    if (CATEGORIES.includes(category))
+        return category;
+    throw new Error(`unsupported OpenStreetMap category: ${category}`);
+}
+function isObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/dist/providers/openstreetmap/constants.d.ts

@@ -3,4 +3,6 @@ export declare const OPENSTREETMAP_CITY_CATEGORY = "city";
 export declare const OPENSTREETMAP_COUNTRY_CATEGORY = "country";
 export declare const OPENSTREETMAP_PLACE_CATEGORY = "place";
 export declare const OPENSTREETMAP_VENUE_CATEGORY = "venue";
+export declare const OPENSTREETMAP_API_BASE = "https://nominatim.openstreetmap.org";
+export declare const OPENSTREETMAP_DEFAULT_USER_AGENT = "@zivue/zuuid OpenStreetMap client (+https://github.com/zivue/zuuid)";
 //# sourceMappingURL=constants.d.ts.map

package/dist/providers/openstreetmap/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/providers/openstreetmap/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AACtD,eAAO,MAAM,2BAA2B,SAAS,CAAC;AAClD,eAAO,MAAM,8BAA8B,YAAY,CAAC;AACxD,eAAO,MAAM,4BAA4B,UAAU,CAAC;AACpD,eAAO,MAAM,4BAA4B,UAAU,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/providers/openstreetmap/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AACtD,eAAO,MAAM,2BAA2B,SAAS,CAAC;AAClD,eAAO,MAAM,8BAA8B,YAAY,CAAC;AACxD,eAAO,MAAM,4BAA4B,UAAU,CAAC;AACpD,eAAO,MAAM,4BAA4B,UAAU,CAAC;AACpD,eAAO,MAAM,sBAAsB,wCAAwC,CAAC;AAC5E,eAAO,MAAM,gCAAgC,wEAAwE,CAAC"}

package/dist/providers/openstreetmap/constants.js

@@ -3,3 +3,5 @@ export const OPENSTREETMAP_CITY_CATEGORY = "city";
 export const OPENSTREETMAP_COUNTRY_CATEGORY = "country";
 export const OPENSTREETMAP_PLACE_CATEGORY = "place";
 export const OPENSTREETMAP_VENUE_CATEGORY = "venue";
+export const OPENSTREETMAP_API_BASE = "https://nominatim.openstreetmap.org";
+export const OPENSTREETMAP_DEFAULT_USER_AGENT = "@zivue/zuuid OpenStreetMap client (+https://github.com/zivue/zuuid)";

package/dist/providers/openstreetmap/country.d.ts

@@ -0,0 +1,2 @@
+export { transformOpenStreetMapPlace as transformOpenStreetMapCountry } from "./place.js";
+//# sourceMappingURL=country.d.ts.map

package/dist/providers/openstreetmap/country.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"country.d.ts","sourceRoot":"","sources":["../../../src/providers/openstreetmap/country.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,IAAI,6BAA6B,EAAE,MAAM,YAAY,CAAC"}

package/dist/providers/openstreetmap/country.js

@@ -0,0 +1 @@
+export { transformOpenStreetMapPlace as transformOpenStreetMapCountry } from "./place.js";

package/dist/providers/openstreetmap/index.d.ts

@@ -1,3 +1,7 @@
+export * from "./types.js";
+export * from "./country.js";
+export * from "./client.js";
+export * from "./city.js";
 export * from "./constants.js";
 export * from "./place.js";
 export * from "./venue.js";

package/dist/providers/openstreetmap/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/openstreetmap/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/openstreetmap/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/providers/openstreetmap/index.js

@@ -1,3 +1,7 @@
+export * from "./types.js";
+export * from "./country.js";
+export * from "./client.js";
+export * from "./city.js";
 export * from "./constants.js";
 export * from "./place.js";
 export * from "./venue.js";

package/dist/providers/openstreetmap/types.d.ts

@@ -0,0 +1,16 @@
+export type OpenStreetMapFetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type OpenStreetMapProviderOptions = {
+    apiBase?: string;
+    fetch?: OpenStreetMapFetchLike;
+    userAgent?: string;
+    language?: string;
+};
+export type FetchOpenStreetMapInput = {
+    id: string | number;
+};
+export type OpenStreetMapSearchInput = {
+    query: string;
+    limit?: number;
+    language?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/openstreetmap/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/providers/openstreetmap/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEpG,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC"}

package/dist/providers/openstreetmap/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zivue/zuuid",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "TypeScript helpers for fetching, searching, and transforming Zuuid datasets.",
   "type": "module",
   "license": "MIT",
@@ -56,6 +56,10 @@
       "types": "./dist/providers/comicvine/transform.d.ts",
       "import": "./dist/providers/comicvine/transform.js"
     },
+    "./providers/comicvine/client": {
+      "types": "./dist/providers/comicvine/client.d.ts",
+      "import": "./dist/providers/comicvine/client.js"
+    },
     "./providers/comicvine/volume": {
       "types": "./dist/providers/comicvine/volume.d.ts",
       "import": "./dist/providers/comicvine/volume.js"
@@ -164,10 +168,22 @@
       "types": "./dist/providers/openstreetmap/index.d.ts",
       "import": "./dist/providers/openstreetmap/index.js"
     },
+    "./providers/openstreetmap/client": {
+      "types": "./dist/providers/openstreetmap/client.d.ts",
+      "import": "./dist/providers/openstreetmap/client.js"
+    },
     "./providers/openstreetmap/place": {
       "types": "./dist/providers/openstreetmap/place.d.ts",
       "import": "./dist/providers/openstreetmap/place.js"
     },
+    "./providers/openstreetmap/city": {
+      "types": "./dist/providers/openstreetmap/city.d.ts",
+      "import": "./dist/providers/openstreetmap/city.js"
+    },
+    "./providers/openstreetmap/country": {
+      "types": "./dist/providers/openstreetmap/country.d.ts",
+      "import": "./dist/providers/openstreetmap/country.js"
+    },
     "./providers/openstreetmap/venue": {
       "types": "./dist/providers/openstreetmap/venue.d.ts",
       "import": "./dist/providers/openstreetmap/venue.js"
@@ -255,6 +271,10 @@
     "./providers/gamesdb/client": {
       "types": "./dist/providers/gamesdb/client.d.ts",
       "import": "./dist/providers/gamesdb/client.js"
+    },
+    "./providers/musicbrainz/client": {
+      "types": "./dist/providers/musicbrainz/client.d.ts",
+      "import": "./dist/providers/musicbrainz/client.js"
     }
   },
   "types": "./dist/index.d.ts",