@zivue/zuuid 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.5 - 2026-05-25
+
+- Added live OpenStreetMap/Nominatim lookup and search support for cities, countries, places, and venues.
+- Added `OpenStreetMapProvider`, `visit.openstreetmap` client facades, city/country subpath exports, examples, and README documentation.
+
+## 0.2.4 - 2026-05-25
+
+- Added live ComicVine API support for volumes, issues, story arcs, characters, people, and publishers.
+- Added `ComicVineProvider`, ComicVine fetch/search helpers, category-first client facades, examples, and `providers/comicvine/client` export.
+
 ## 0.2.3 - 2026-05-25
 
 - Added live MusicBrainz lookup/search support for releases, release groups, recordings, artists, labels, and works.

package/README.md

@@ -4,7 +4,7 @@ Search, fetch, and normalize media metadata from external providers into a share
 
 This package is meant to be used by apps that need provider-backed lookup and transformation, but do not want provider-specific response shapes leaking through the app.
 
-TMDB, Open Library, GamesDB, and MusicBrainz include live search/fetch clients. IMDb includes a fetch-by-ID title-page scraper for movie and TV titles. Additional providers currently expose source-record transformers: you provide the raw provider payload, and this package normalizes it into `ZuuidData`.
+TMDB, Open Library, ComicVine, GamesDB, MusicBrainz, and OpenStreetMap include live search/fetch clients. IMDb includes a fetch-by-ID title-page scraper for movie and TV titles. Additional providers currently expose source-record transformers: you provide the raw provider payload, and this package normalizes it into `ZuuidData`.
 
 Storage, caching, indexing, review state, object-store keys, and persistence belong in a layer outside this package.
 
@@ -109,20 +109,20 @@ Ratings are normalized to a `0-5` scale when the provider exposes a compatible n
 | TMDB | person | yes | yes | yes |
 | Open Library | book | yes | yes | yes |
 | Open Library | author | yes | yes | yes |
-| ComicVine | volume, issue, story_arc, character, person, publisher | no | no | yes |
+| ComicVine | volume, issue, story_arc, character, person, publisher | yes | yes | yes |
 | IMDb | movie, tv | no | yes | yes |
 | GamesDB | game | yes | yes | yes |
 | GamesDB | platform | no | yes | yes |
 | Jikan | anime, manga, producer, magazine, character, person | no | no | yes |
 | MusicBrainz | release, release-group, recording, artist, label, work | yes | yes | yes |
 | OpenFoodFacts | product | no | no | yes |
-| OpenStreetMap | city, country, place, venue | no | no | yes |
+| OpenStreetMap | city, country, place, venue | yes | yes | yes |
 | Podcast / iTunes | podcast | no | no | yes |
 | Setlist.fm | setlist, artist, venue | no | no | yes |
 | Ticketmaster | event, attraction, venue | no | no | yes |
 | Wger | exercise, equipment | no | no | yes |
 
-For IMDb, search is marked `no` because the scraper fetches known title IDs such as `tt0137523`; it does not implement IMDb search. GamesDB platform search is marked `no` because only game search and ID fetches are currently implemented. For transformer-only providers, "Search" and "Fetch" are marked `no` because this package does not perform those HTTP requests yet. Use your own provider client or stored payloads, wrap the payload in a `SourceRecord`, and call the category transformer.
+For IMDb, search is marked `no` because the scraper fetches known title IDs such as `tt0137523`; it does not implement IMDb search. ComicVine and GamesDB require API keys for live API calls. GamesDB platform search is marked `no` because only game search and ID fetches are currently implemented. For transformer-only providers, "Search" and "Fetch" are marked `no` because this package does not perform those HTTP requests yet. Use your own provider client or stored payloads, wrap the payload in a `SourceRecord`, and call the category transformer.
 
 
 
@@ -154,6 +154,57 @@ const game = await zuuid.play.gamesdb?.game.fetch({ id: 17444 });
 
 GamesDB transforms accept both simple flat payloads and native TheGamesDB API envelopes with `data.games`, `data.platforms`, lookup maps, and `boxart` image metadata.
 
+## OpenStreetMap
+
+`OpenStreetMapProvider` uses the public Nominatim API for OSM lookup and search. It sends a descriptive `User-Agent` by default and lets you override it. Fetch IDs must be OSM object IDs with a type prefix: `N` for node, `W` for way, or `R` for relation.
+
+```ts
+import { OpenStreetMapProvider } from "@zivue/zuuid/providers/openstreetmap";
+
+const osm = new OpenStreetMapProvider({
+  userAgent: "your-app/1.0 (you@example.com)"
+});
+
+const city = await osm.fetchCity({ id: "R406091" });
+const venues = await osm.searchVenues({ query: "Blue Note Oslo" });
+```
+
+The category-first client exposes OpenStreetMap under `visit.openstreetmap`:
+
+```ts
+const zuuid = createZuuidClient({ providers: { openstreetmap: {} } });
+
+const places = await zuuid.visit.openstreetmap?.place.search({ query: "Eiffel Tower" });
+const country = await zuuid.visit.openstreetmap?.country.fetch({ id: "R2978650" });
+```
+
+## ComicVine Credentials
+
+`ComicVineProvider` uses the ComicVine API and requires an API key:
+
+```ts
+import { ComicVineProvider } from "@zivue/zuuid/providers/comicvine";
+
+const comicvine = new ComicVineProvider({
+  apiKey: process.env.COMICVINE_API_KEY!
+});
+
+const volume = await comicvine.fetchVolume({ id: 1 });
+const issues = await comicvine.searchIssues({ query: "Saga" });
+const publisher = await comicvine.fetchPublisher({ id: 10 });
+```
+
+The category-first client exposes ComicVine under `read.comicvine` and `people.comicvine`:
+
+```ts
+const zuuid = createZuuidClient({
+  providers: { comicvine: { apiKey: process.env.COMICVINE_API_KEY! } }
+});
+
+const volumes = await zuuid.read.comicvine?.volume.search({ query: "Saga" });
+const character = await zuuid.people.comicvine?.character.search({ query: "Spider-Man" });
+```
+
 
 ## MusicBrainz
 
@@ -228,6 +279,8 @@ const tvShows = await zuuid.tv.tmdb?.search({ query: "Game of Thrones" });
 const people = await zuuid.people.tmdb?.search({ query: "Brad Pitt" });
 const books = await zuuid.read.openlibrary?.search({ query: "The Lord of the Rings" });
 const authors = await zuuid.people.openlibrary?.search({ query: "J. K. Rowling" });
+const comics = await zuuid.read.comicvine?.volume.search({ query: "Saga" });
+const places = await zuuid.visit.openstreetmap?.place.search({ query: "Eiffel Tower" });
 ```
 
 Provider methods are also available directly:
@@ -246,6 +299,22 @@ const books = await openlibrary.searchBooks({ query: "The Lord of the Rings" });
 const authors = await openlibrary.searchAuthors({ query: "J. K. Rowling" });
 ```
 
+```ts
+import { ComicVineProvider } from "@zivue/zuuid/providers/comicvine";
+
+const comicvine = new ComicVineProvider({ apiKey: process.env.COMICVINE_API_KEY! });
+const volumes = await comicvine.searchVolumes({ query: "Saga" });
+const issues = await comicvine.searchIssues({ query: "Saga" });
+```
+
+```ts
+import { OpenStreetMapProvider } from "@zivue/zuuid/providers/openstreetmap";
+
+const osm = new OpenStreetMapProvider();
+const places = await osm.searchPlaces({ query: "Eiffel Tower" });
+const city = await osm.fetchCity({ id: "R406091" });
+```
+
 Search options include pagination and common TMDB filters:
 
 ```ts
@@ -430,6 +499,10 @@ npm run example:search -- author "J. K. Rowling"
 npm run example:search -- release-group "Kind of Blue"
 npm run example:search -- recording "So What"
 npm run example:search -- artist "Miles Davis"
+COMICVINE_API_KEY=... npm run example:search -- comicvine:volume "Saga"
+COMICVINE_API_KEY=... npm run example:search -- comicvine:issue "Saga"
+npm run example:search -- openstreetmap:place "Eiffel Tower"
+npm run example:search -- openstreetmap:venue "Blue Note Oslo"
 ```
 
 Fetch and transform a selected provider ID:
@@ -447,11 +520,15 @@ Fetch live provider examples:
 ```sh
 npm run example:fetch -- imdb:movie tt0137523
 npm run example:fetch -- imdb:tv tt0944947
+COMICVINE_API_KEY=... npm run example:fetch -- comicvine:volume 1
+COMICVINE_API_KEY=... npm run example:fetch -- comicvine:issue 101
 GAMESDB_API_KEY=... npm run example:fetch -- gamesdb:game 17444
 GAMESDB_API_KEY=... npm run example:fetch -- gamesdb:platform 6
 npm run example:fetch -- musicbrainz:release f5093c06-23e3-404f-aeaa-40f72885ee3a
 npm run example:fetch -- musicbrainz:release-group aaa50249-1e6b-3910-b830-7e2fb622a8c4
 npm run example:fetch -- musicbrainz:artist 561d854a-6a28-4aa7-8c99-323e6ce46c2a
+npm run example:fetch -- openstreetmap:city R406091
+npm run example:fetch -- openstreetmap:country R2978650
 ```
 
 Transformer-only providers do not have fetch examples. Wrap a real payload from your own provider client in a `SourceRecord` and call the transformer directly.
@@ -487,8 +564,10 @@ Provider exports:
 - `TmdbProvider`
 - `OpenLibraryProvider`
 - `ImdbProvider`
+- `ComicVineProvider`
 - `GamesDbProvider`
 - `MusicBrainzProvider`
+- `OpenStreetMapProvider`
 - `transformTmdbMovie(sourceRecord, options?)`
 - `transformTmdbTv(sourceRecord, options?)`
 - `transformTmdbPerson(sourceRecord, options?)`

package/dist/client.d.ts

@@ -1,15 +1,19 @@
+import { type ComicVineProviderOptions, type ComicVineSearchInput, type FetchComicVineInput } from "./providers/comicvine/index.js";
 import type { SearchResponse, ZuuidData, ZuuidSearchResult } from "./entity.js";
 import { type FetchMusicBrainzInput, type MusicBrainzProviderOptions, type MusicBrainzSearchInput } from "./providers/musicbrainz/index.js";
 import { type FetchOpenLibraryAuthorInput, type FetchOpenLibraryBookInput, type OpenLibraryProviderOptions, type OpenLibrarySearchInput } from "./providers/openlibrary/index.js";
+import { type FetchOpenStreetMapInput, type OpenStreetMapProviderOptions, type OpenStreetMapSearchInput } from "./providers/openstreetmap/index.js";
 import { type FetchTmdbMovieInput, type FetchTmdbPersonInput, type FetchTmdbTvInput, type TmdbProviderOptions, type TmdbSearchInput } from "./providers/tmdb/index.js";
 import { type FetchGamesDbGameInput, type FetchGamesDbPlatformInput, type GamesDbProviderOptions, type GamesDbSearchInput } from "./providers/gamesdb/index.js";
 import { type FetchImdbTitleInput, type ImdbProviderOptions } from "./providers/imdb/index.js";
 import type { SourceRecord } from "./source.js";
 export type ProviderConfigs = {
+    comicvine?: ComicVineProviderOptions;
     gamesdb?: GamesDbProviderOptions;
     imdb?: ImdbProviderOptions;
     musicbrainz?: MusicBrainzProviderOptions;
     openlibrary?: OpenLibraryProviderOptions;
+    openstreetmap?: OpenStreetMapProviderOptions;
     tmdb?: TmdbProviderOptions;
 };
 export type ZuuidClientConfig = {
@@ -50,9 +54,19 @@ export type ZuuidClient = {
             artist: ProviderClient<FetchMusicBrainzInput, MusicBrainzSearchInput>;
             label: ProviderClient<FetchMusicBrainzInput, MusicBrainzSearchInput>;
         };
+        comicvine?: {
+            character: ProviderClient<FetchComicVineInput, ComicVineSearchInput>;
+            person: ProviderClient<FetchComicVineInput, ComicVineSearchInput>;
+            publisher: ProviderClient<FetchComicVineInput, ComicVineSearchInput>;
+        };
     };
     read: {
         openlibrary?: ProviderClient<FetchOpenLibraryBookInput, OpenLibrarySearchInput>;
+        comicvine?: {
+            volume: ProviderClient<FetchComicVineInput, ComicVineSearchInput>;
+            issue: ProviderClient<FetchComicVineInput, ComicVineSearchInput>;
+            storyArc: ProviderClient<FetchComicVineInput, ComicVineSearchInput>;
+        };
     };
     listen: {
         musicbrainz?: {
@@ -68,6 +82,14 @@ export type ZuuidClient = {
             platform: FetchOnlyProviderClient<FetchGamesDbPlatformInput>;
         };
     };
+    visit: {
+        openstreetmap?: {
+            city: ProviderClient<FetchOpenStreetMapInput, OpenStreetMapSearchInput>;
+            country: ProviderClient<FetchOpenStreetMapInput, OpenStreetMapSearchInput>;
+            place: ProviderClient<FetchOpenStreetMapInput, OpenStreetMapSearchInput>;
+            venue: ProviderClient<FetchOpenStreetMapInput, OpenStreetMapSearchInput>;
+        };
+    };
 };
 export declare function createZuuidClient(config?: ZuuidClientConfig): ZuuidClient;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAQL,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC5B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAIL,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC5B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,wBAAwB,EAC9B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAKL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,WAAW,CAAC,EAAE,0BAA0B,CAAC;IACzC,WAAW,CAAC,EAAE,0BAA0B,CAAC;IACzC,aAAa,CAAC,EAAE,4BAA4B,CAAC;IAC7C,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,WAAW,IAAI;IAC7C,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IAC1D,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IACzE,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAC3E,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;IACnF,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACrD,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,WAAW,IAAI;IACjD,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IAC1D,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IACzE,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACrD,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,WAAW,EAAE,YAAY,IAAI;IACtD,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IAC1D,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IACzE,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACxE,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;IAChF,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACrD,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE;QACL,IAAI,CAAC,EAAE,uBAAuB,CAAC,mBAAmB,CAAC,CAAC;QACpD,IAAI,CAAC,EAAE,cAAc,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;KAC7D,CAAC;IACF,EAAE,EAAE;QACF,IAAI,CAAC,EAAE,uBAAuB,CAAC,mBAAmB,CAAC,CAAC;QACpD,IAAI,CAAC,EAAE,cAAc,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;KAC1D,CAAC;IACF,MAAM,EAAE;QACN,IAAI,CAAC,EAAE,cAAc,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;QAC7D,WAAW,CAAC,EAAE,cAAc,CAAC,2BAA2B,EAAE,sBAAsB,CAAC,CAAC;QAClF,WAAW,CAAC,EAAE;YACZ,MAAM,EAAE,cAAc,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC;YACtE,KAAK,EAAE,cAAc,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC;SACtE,CAAC;QACF,SAAS,CAAC,EAAE;YACV,SAAS,EAAE,cAAc,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAAC;YACrE,MAAM,EAAE,cAAc,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAAC;YAClE,SAAS,EAAE,cAAc,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAAC;SACtE,CAAC;KACH,CAAC;IACF,IAAI,EAAE;QACJ,WAAW,CAAC,EAAE,cAAc,CAAC,yBAAyB,EAAE,sBAAsB,CAAC,CAAC;QAChF,SAAS,CAAC,EAAE;YACV,MAAM,EAAE,cAAc,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAAC;YAClE,KAAK,EAAE,cAAc,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAAC;YACjE,QAAQ,EAAE,cAAc,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAAC;SACrE,CAAC;KACH,CAAC;IACF,MAAM,EAAE;QACN,WAAW,CAAC,EAAE;YACZ,OAAO,EAAE,cAAc,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC;YACvE,YAAY,EAAE,cAAc,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC;YAC5E,SAAS,EAAE,cAAc,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC;YACzE,IAAI,EAAE,cAAc,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC;SACrE,CAAC;KACH,CAAC;IACF,IAAI,EAAE;QACJ,OAAO,CAAC,EAAE;YACR,IAAI,EAAE,cAAc,CAAC,qBAAqB,EAAE,kBAAkB,CAAC,CAAC;YAChE,QAAQ,EAAE,uBAAuB,CAAC,yBAAyB,CAAC,CAAC;SAC9D,CAAC;KACH,CAAC;IACF,KAAK,EAAE;QACL,aAAa,CAAC,EAAE;YACd,IAAI,EAAE,cAAc,CAAC,uBAAuB,EAAE,wBAAwB,CAAC,CAAC;YACxE,OAAO,EAAE,cAAc,CAAC,uBAAuB,EAAE,wBAAwB,CAAC,CAAC;YAC3E,KAAK,EAAE,cAAc,CAAC,uBAAuB,EAAE,wBAAwB,CAAC,CAAC;YACzE,KAAK,EAAE,cAAc,CAAC,uBAAuB,EAAE,wBAAwB,CAAC,CAAC;SAC1E,CAAC;KACH,CAAC;CACH,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,iBAAsB,GAAG,WAAW,CAwO7E"}

package/dist/client.js

@@ -1,13 +1,17 @@
+import { ComicVineProvider, transformComicVine } from "./providers/comicvine/index.js";
 import { MusicBrainzProvider, transformMusicBrainzArtist, transformMusicBrainzLabel, transformMusicBrainzRecording, transformMusicBrainzRelease, transformMusicBrainzReleaseGroup, transformMusicBrainzWork } from "./providers/musicbrainz/index.js";
 import { OpenLibraryProvider, transformOpenLibraryAuthor, transformOpenLibraryBook } from "./providers/openlibrary/index.js";
+import { OpenStreetMapProvider, transformOpenStreetMapPlace } from "./providers/openstreetmap/index.js";
 import { TmdbProvider, transformTmdbMovie, transformTmdbPerson, transformTmdbTv } from "./providers/tmdb/index.js";
 import { GamesDbProvider, transformGamesDbGame, transformGamesDbPlatform } from "./providers/gamesdb/index.js";
 import { ImdbProvider, transformImdbMovie, transformImdbTv } from "./providers/imdb/index.js";
 export function createZuuidClient(config = {}) {
+    const comicvine = config.providers?.comicvine ? new ComicVineProvider(config.providers.comicvine) : undefined;
     const gamesdb = config.providers?.gamesdb ? new GamesDbProvider(config.providers.gamesdb) : undefined;
     const imdb = config.providers?.imdb ? new ImdbProvider(config.providers.imdb) : undefined;
     const musicbrainz = config.providers?.musicbrainz ? new MusicBrainzProvider(config.providers.musicbrainz) : undefined;
     const openlibrary = config.providers?.openlibrary ? new OpenLibraryProvider(config.providers.openlibrary) : undefined;
+    const openstreetmap = config.providers?.openstreetmap ? new OpenStreetMapProvider(config.providers.openstreetmap) : undefined;
     const tmdb = config.providers?.tmdb ? new TmdbProvider(config.providers.tmdb) : undefined;
     return Object.freeze({
         movie: Object.freeze({
@@ -82,6 +86,31 @@ export function createZuuidClient(config = {}) {
                         transform: (source) => transformMusicBrainzLabel(source)
                     })
                 })
+                : undefined,
+            comicvine: comicvine
+                ? Object.freeze({
+                    character: Object.freeze({
+                        fetch: (input) => comicvine.fetchCharacter(input),
+                        fetchSourceRecord: (input) => comicvine.fetchCharacterSourceRecord(input),
+                        search: (input) => comicvine.searchCharacters(input),
+                        searchSourceRecords: (input) => comicvine.searchCharacterSourceRecords(input),
+                        transform: (source) => transformComicVine(source)
+                    }),
+                    person: Object.freeze({
+                        fetch: (input) => comicvine.fetchPerson(input),
+                        fetchSourceRecord: (input) => comicvine.fetchPersonSourceRecord(input),
+                        search: (input) => comicvine.searchPeople(input),
+                        searchSourceRecords: (input) => comicvine.searchPersonSourceRecords(input),
+                        transform: (source) => transformComicVine(source)
+                    }),
+                    publisher: Object.freeze({
+                        fetch: (input) => comicvine.fetchPublisher(input),
+                        fetchSourceRecord: (input) => comicvine.fetchPublisherSourceRecord(input),
+                        search: (input) => comicvine.searchPublishers(input),
+                        searchSourceRecords: (input) => comicvine.searchPublisherSourceRecords(input),
+                        transform: (source) => transformComicVine(source)
+                    })
+                })
                 : undefined
         }),
         read: Object.freeze({
@@ -93,6 +122,31 @@ export function createZuuidClient(config = {}) {
                     searchSourceRecords: (input) => openlibrary.searchBookSourceRecords(input),
                     transform: (source) => transformOpenLibraryBook(source, openlibrary.transformOptions())
                 })
+                : undefined,
+            comicvine: comicvine
+                ? Object.freeze({
+                    volume: Object.freeze({
+                        fetch: (input) => comicvine.fetchVolume(input),
+                        fetchSourceRecord: (input) => comicvine.fetchVolumeSourceRecord(input),
+                        search: (input) => comicvine.searchVolumes(input),
+                        searchSourceRecords: (input) => comicvine.searchVolumeSourceRecords(input),
+                        transform: (source) => transformComicVine(source)
+                    }),
+                    issue: Object.freeze({
+                        fetch: (input) => comicvine.fetchIssue(input),
+                        fetchSourceRecord: (input) => comicvine.fetchIssueSourceRecord(input),
+                        search: (input) => comicvine.searchIssues(input),
+                        searchSourceRecords: (input) => comicvine.searchIssueSourceRecords(input),
+                        transform: (source) => transformComicVine(source)
+                    }),
+                    storyArc: Object.freeze({
+                        fetch: (input) => comicvine.fetchStoryArc(input),
+                        fetchSourceRecord: (input) => comicvine.fetchStoryArcSourceRecord(input),
+                        search: (input) => comicvine.searchStoryArcs(input),
+                        searchSourceRecords: (input) => comicvine.searchStoryArcSourceRecords(input),
+                        transform: (source) => transformComicVine(source)
+                    })
+                })
                 : undefined
         }),
         listen: Object.freeze({
@@ -146,6 +200,40 @@ export function createZuuidClient(config = {}) {
                     })
                 })
                 : undefined
+        }),
+        visit: Object.freeze({
+            openstreetmap: openstreetmap
+                ? Object.freeze({
+                    city: Object.freeze({
+                        fetch: (input) => openstreetmap.fetchCity(input),
+                        fetchSourceRecord: (input) => openstreetmap.fetchCitySourceRecord(input),
+                        search: (input) => openstreetmap.searchCities(input),
+                        searchSourceRecords: (input) => openstreetmap.searchCitySourceRecords(input),
+                        transform: (source) => transformOpenStreetMapPlace(source)
+                    }),
+                    country: Object.freeze({
+                        fetch: (input) => openstreetmap.fetchCountry(input),
+                        fetchSourceRecord: (input) => openstreetmap.fetchCountrySourceRecord(input),
+                        search: (input) => openstreetmap.searchCountries(input),
+                        searchSourceRecords: (input) => openstreetmap.searchCountrySourceRecords(input),
+                        transform: (source) => transformOpenStreetMapPlace(source)
+                    }),
+                    place: Object.freeze({
+                        fetch: (input) => openstreetmap.fetchPlace(input),
+                        fetchSourceRecord: (input) => openstreetmap.fetchPlaceSourceRecord(input),
+                        search: (input) => openstreetmap.searchPlaces(input),
+                        searchSourceRecords: (input) => openstreetmap.searchPlaceSourceRecords(input),
+                        transform: (source) => transformOpenStreetMapPlace(source)
+                    }),
+                    venue: Object.freeze({
+                        fetch: (input) => openstreetmap.fetchVenue(input),
+                        fetchSourceRecord: (input) => openstreetmap.fetchVenueSourceRecord(input),
+                        search: (input) => openstreetmap.searchVenues(input),
+                        searchSourceRecords: (input) => openstreetmap.searchVenueSourceRecords(input),
+                        transform: (source) => transformOpenStreetMapPlace(source)
+                    })
+                })
+                : undefined
         })
     });
 }

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

@@ -0,0 +1,40 @@
+import type { SearchResponse, ZuuidData, ZuuidSearchResult } from "../../entity.js";
+import { type SourceRecord } from "../../source.js";
+import type { ComicVineApiResponse, ComicVineProviderOptions, ComicVineSearchInput, FetchComicVineInput } from "./types.js";
+export declare class ComicVineProvider {
+    readonly apiBase: string;
+    readonly userAgent: string;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(options: ComicVineProviderOptions);
+    getJson<T>(path: string, params: Record<string, string>): Promise<T | undefined>;
+    getEnvelope<T>(path: string, params: Record<string, string>): Promise<ComicVineApiResponse<T>>;
+    fetchVolumeSourceRecord(input: FetchComicVineInput): Promise<SourceRecord | undefined>;
+    fetchVolume(input: FetchComicVineInput): Promise<ZuuidData | undefined>;
+    searchVolumeSourceRecords(input: ComicVineSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchVolumes(input: ComicVineSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+    fetchIssueSourceRecord(input: FetchComicVineInput): Promise<SourceRecord | undefined>;
+    fetchIssue(input: FetchComicVineInput): Promise<ZuuidData | undefined>;
+    searchIssueSourceRecords(input: ComicVineSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchIssues(input: ComicVineSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+    fetchStoryArcSourceRecord(input: FetchComicVineInput): Promise<SourceRecord | undefined>;
+    fetchStoryArc(input: FetchComicVineInput): Promise<ZuuidData | undefined>;
+    searchStoryArcSourceRecords(input: ComicVineSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchStoryArcs(input: ComicVineSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+    fetchCharacterSourceRecord(input: FetchComicVineInput): Promise<SourceRecord | undefined>;
+    fetchCharacter(input: FetchComicVineInput): Promise<ZuuidData | undefined>;
+    searchCharacterSourceRecords(input: ComicVineSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchCharacters(input: ComicVineSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+    fetchPersonSourceRecord(input: FetchComicVineInput): Promise<SourceRecord | undefined>;
+    fetchPerson(input: FetchComicVineInput): Promise<ZuuidData | undefined>;
+    searchPersonSourceRecords(input: ComicVineSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchPeople(input: ComicVineSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+    fetchPublisherSourceRecord(input: FetchComicVineInput): Promise<SourceRecord | undefined>;
+    fetchPublisher(input: FetchComicVineInput): Promise<ZuuidData | undefined>;
+    searchPublisherSourceRecords(input: ComicVineSearchInput): Promise<SearchResponse<SourceRecord>>;
+    searchPublishers(input: ComicVineSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+}
+export declare function fetchComicVineSourceRecord(provider: ComicVineProvider, category: string, input: FetchComicVineInput): Promise<SourceRecord | undefined>;
+export declare function searchComicVineSourceRecords(provider: ComicVineProvider, category: string, input: ComicVineSearchInput): Promise<SearchResponse<SourceRecord>>;
+export declare function searchComicVine(provider: ComicVineProvider, category: string, input: ComicVineSearchInput): Promise<SearchResponse<ZuuidSearchResult>>;
+//# sourceMappingURL=client.d.ts.map

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

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

package/dist/providers/comicvine/client.js

@@ -0,0 +1,190 @@
+import { providerZuuid } from "../../identity.js";
+import { createSourceRecord } from "../../source.js";
+import { datePrefix, nestedString, stringField, valueAsString } from "../common.js";
+import { COMICVINE_API_BASE, COMICVINE_CHARACTER_CATEGORY, COMICVINE_DEFAULT_USER_AGENT, COMICVINE_ISSUE_CATEGORY, COMICVINE_PERSON_CATEGORY, COMICVINE_PROVIDER, COMICVINE_PUBLISHER_CATEGORY, COMICVINE_STORY_ARC_CATEGORY, COMICVINE_VOLUME_CATEGORY } from "./constants.js";
+import { transformComicVine } from "./transform.js";
+const CATEGORY_CONFIG = {
+    [COMICVINE_VOLUME_CATEGORY]: { detailPath: "volume", searchResource: "volume", idPrefix: "4050", publicCategory: "comic" },
+    [COMICVINE_ISSUE_CATEGORY]: { detailPath: "issue", searchResource: "issue", idPrefix: "4000", publicCategory: "comic" },
+    [COMICVINE_STORY_ARC_CATEGORY]: { detailPath: "story_arc", searchResource: "story_arc", idPrefix: "4045", publicCategory: "comic" },
+    [COMICVINE_CHARACTER_CATEGORY]: { detailPath: "character", searchResource: "character", idPrefix: "4005", publicCategory: "person" },
+    [COMICVINE_PERSON_CATEGORY]: { detailPath: "person", searchResource: "person", idPrefix: "4040", publicCategory: "person" },
+    [COMICVINE_PUBLISHER_CATEGORY]: { detailPath: "publisher", searchResource: "publisher", idPrefix: "4010", publicCategory: "organization" }
+};
+export class ComicVineProvider {
+    apiBase;
+    userAgent;
+    apiKey;
+    fetchImpl;
+    constructor(options) {
+        this.apiKey = options.apiKey.trim();
+        if (!this.apiKey)
+            throw new Error("ComicVine API key must not be empty");
+        this.apiBase = options.apiBase ?? COMICVINE_API_BASE;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.userAgent = options.userAgent ?? COMICVINE_DEFAULT_USER_AGENT;
+    }
+    async getJson(path, params) {
+        const url = new URL(`${this.apiBase.replace(/\/$/, "")}/${path.replace(/^\//, "")}`);
+        url.searchParams.set("api_key", this.apiKey);
+        url.searchParams.set("format", "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(`ComicVine API returned ${response.status}: ${body}`);
+        }
+        const payload = await response.json();
+        if (payload.status_code === 101)
+            return undefined;
+        if (payload.status_code !== undefined && payload.status_code !== 1) {
+            throw new Error(`ComicVine API returned status ${payload.status_code}: ${payload.error ?? "unknown error"}`);
+        }
+        return payload.results;
+    }
+    async getEnvelope(path, params) {
+        const url = new URL(`${this.apiBase.replace(/\/$/, "")}/${path.replace(/^\//, "")}`);
+        url.searchParams.set("api_key", this.apiKey);
+        url.searchParams.set("format", "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.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`ComicVine API returned ${response.status}: ${body}`);
+        }
+        const payload = await response.json();
+        if (payload.status_code !== undefined && payload.status_code !== 1) {
+            throw new Error(`ComicVine API returned status ${payload.status_code}: ${payload.error ?? "unknown error"}`);
+        }
+        return payload;
+    }
+    async fetchVolumeSourceRecord(input) { return fetchComicVineSourceRecord(this, COMICVINE_VOLUME_CATEGORY, input); }
+    async fetchVolume(input) { const source = await this.fetchVolumeSourceRecord(input); return source ? transformComicVine(source) : undefined; }
+    async searchVolumeSourceRecords(input) { return searchComicVineSourceRecords(this, COMICVINE_VOLUME_CATEGORY, input); }
+    async searchVolumes(input) { return searchComicVine(this, COMICVINE_VOLUME_CATEGORY, input); }
+    async fetchIssueSourceRecord(input) { return fetchComicVineSourceRecord(this, COMICVINE_ISSUE_CATEGORY, input); }
+    async fetchIssue(input) { const source = await this.fetchIssueSourceRecord(input); return source ? transformComicVine(source) : undefined; }
+    async searchIssueSourceRecords(input) { return searchComicVineSourceRecords(this, COMICVINE_ISSUE_CATEGORY, input); }
+    async searchIssues(input) { return searchComicVine(this, COMICVINE_ISSUE_CATEGORY, input); }
+    async fetchStoryArcSourceRecord(input) { return fetchComicVineSourceRecord(this, COMICVINE_STORY_ARC_CATEGORY, input); }
+    async fetchStoryArc(input) { const source = await this.fetchStoryArcSourceRecord(input); return source ? transformComicVine(source) : undefined; }
+    async searchStoryArcSourceRecords(input) { return searchComicVineSourceRecords(this, COMICVINE_STORY_ARC_CATEGORY, input); }
+    async searchStoryArcs(input) { return searchComicVine(this, COMICVINE_STORY_ARC_CATEGORY, input); }
+    async fetchCharacterSourceRecord(input) { return fetchComicVineSourceRecord(this, COMICVINE_CHARACTER_CATEGORY, input); }
+    async fetchCharacter(input) { const source = await this.fetchCharacterSourceRecord(input); return source ? transformComicVine(source) : undefined; }
+    async searchCharacterSourceRecords(input) { return searchComicVineSourceRecords(this, COMICVINE_CHARACTER_CATEGORY, input); }
+    async searchCharacters(input) { return searchComicVine(this, COMICVINE_CHARACTER_CATEGORY, input); }
+    async fetchPersonSourceRecord(input) { return fetchComicVineSourceRecord(this, COMICVINE_PERSON_CATEGORY, input); }
+    async fetchPerson(input) { const source = await this.fetchPersonSourceRecord(input); return source ? transformComicVine(source) : undefined; }
+    async searchPersonSourceRecords(input) { return searchComicVineSourceRecords(this, COMICVINE_PERSON_CATEGORY, input); }
+    async searchPeople(input) { return searchComicVine(this, COMICVINE_PERSON_CATEGORY, input); }
+    async fetchPublisherSourceRecord(input) { return fetchComicVineSourceRecord(this, COMICVINE_PUBLISHER_CATEGORY, input); }
+    async fetchPublisher(input) { const source = await this.fetchPublisherSourceRecord(input); return source ? transformComicVine(source) : undefined; }
+    async searchPublisherSourceRecords(input) { return searchComicVineSourceRecords(this, COMICVINE_PUBLISHER_CATEGORY, input); }
+    async searchPublishers(input) { return searchComicVine(this, COMICVINE_PUBLISHER_CATEGORY, input); }
+}
+export async function fetchComicVineSourceRecord(provider, category, input) {
+    const comicCategory = requireCategory(category);
+    const id = comicVineId(input.id);
+    const config = CATEGORY_CONFIG[comicCategory];
+    const payload = await provider.getJson(`/${config.detailPath}/${config.idPrefix}-${id}/`, {});
+    if (!payload)
+        return undefined;
+    return createSourceRecord({ source: { provider: COMICVINE_PROVIDER, category, externalId: id }, payload });
+}
+export async function searchComicVineSourceRecords(provider, category, input) {
+    const payload = await searchPayload(provider, category, input);
+    const comicCategory = requireCategory(category);
+    return {
+        results: await Promise.all(searchItems(payload).map((item) => createSourceRecord({ source: { provider: COMICVINE_PROVIDER, category, externalId: resultId(item, comicCategory) ?? "" }, payload: item }))),
+        pagination: pagination(payload)
+    };
+}
+export async function searchComicVine(provider, category, input) {
+    const payload = await searchPayload(provider, category, input);
+    const comicCategory = requireCategory(category);
+    const results = [];
+    for (const item of searchItems(payload)) {
+        const externalId = resultId(item, comicCategory);
+        const title = stringField(item, "name") ?? stringField(item, "title");
+        if (!externalId || !title)
+            continue;
+        const zuuid = await providerZuuid({ provider: COMICVINE_PROVIDER, category, externalId });
+        results.push({
+            id: zuuid,
+            zuuid,
+            category: CATEGORY_CONFIG[comicCategory].publicCategory,
+            title,
+            date: dateFor(item),
+            cover: nestedString(item, ["image", "super_url"]) ?? nestedString(item, ["image", "original_url"]) ?? nestedString(item, ["image", "medium_url"]) ?? null,
+            rating: null,
+            weight: numberValue(item, "score"),
+            relationType: null,
+            attribute: attributeFor(item, comicCategory),
+            order: null,
+            source: { source: COMICVINE_PROVIDER, category, value: externalId }
+        });
+    }
+    return { results, pagination: pagination(payload) };
+}
+async function searchPayload(provider, category, input) {
+    const comicCategory = requireCategory(category);
+    const query = input.query.trim();
+    if (!query)
+        throw new Error("ComicVine search query must not be empty");
+    return provider.getEnvelope("/search/", {
+        query,
+        resources: CATEGORY_CONFIG[comicCategory].searchResource,
+        limit: String(input.limit ?? 25),
+        offset: String(input.offset ?? 0),
+        ...(input.fieldList?.length ? { field_list: input.fieldList.join(",") } : {})
+    });
+}
+function searchItems(payload) {
+    return Array.isArray(payload.results) ? payload.results.filter(isObject) : [];
+}
+function pagination(payload) {
+    const total = payload.number_of_total_results ?? searchItems(payload).length;
+    const offset = payload.offset ?? 0;
+    const limit = payload.limit ?? payload.number_of_page_results ?? searchItems(payload).length;
+    return { page: limit > 0 ? Math.floor(offset / limit) + 1 : 1, totalPages: limit > 0 ? Math.ceil(total / limit) : 0, totalResults: total };
+}
+function requireCategory(category) {
+    if (category in CATEGORY_CONFIG)
+        return category;
+    throw new Error(`unsupported ComicVine category: ${category}`);
+}
+function comicVineId(value) {
+    const id = String(value).trim();
+    const normalized = id.includes("-") ? id.split("-").pop() ?? "" : id;
+    if (!/^\d+$/.test(normalized))
+        throw new Error(`ComicVine id must be numeric: ${value}`);
+    return normalized;
+}
+function resultId(item, category) {
+    const raw = valueAsString(item.id);
+    if (!raw)
+        return undefined;
+    return raw.startsWith(`${CATEGORY_CONFIG[category].idPrefix}-`) ? raw.slice(CATEGORY_CONFIG[category].idPrefix.length + 1) : raw;
+}
+function dateFor(item) {
+    return datePrefix(stringField(item, "cover_date")) ?? datePrefix(stringField(item, "store_date")) ?? stringField(item, "start_year") ?? null;
+}
+function attributeFor(item, category) {
+    if (category === COMICVINE_ISSUE_CATEGORY)
+        return stringField(item, "issue_number") ?? null;
+    if (category === COMICVINE_PERSON_CATEGORY || category === COMICVINE_CHARACTER_CATEGORY)
+        return stringField(item, "real_name") ?? null;
+    return stringField(item, "deck") ?? null;
+}
+function numberValue(item, key) {
+    const value = item[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function isObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}

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

@@ -5,4 +5,6 @@ export declare const COMICVINE_STORY_ARC_CATEGORY = "story_arc";
 export declare const COMICVINE_CHARACTER_CATEGORY = "character";
 export declare const COMICVINE_PERSON_CATEGORY = "person";
 export declare const COMICVINE_PUBLISHER_CATEGORY = "publisher";
+export declare const COMICVINE_API_BASE = "https://comicvine.gamespot.com/api";
+export declare const COMICVINE_DEFAULT_USER_AGENT = "@zivue/zuuid ComicVine client (+https://github.com/zivue/zuuid)";
 //# sourceMappingURL=constants.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/providers/comicvine/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAC9C,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAChD,eAAO,MAAM,4BAA4B,cAAc,CAAC;AACxD,eAAO,MAAM,4BAA4B,cAAc,CAAC;AACxD,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,4BAA4B,cAAc,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/providers/comicvine/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAC9C,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAChD,eAAO,MAAM,4BAA4B,cAAc,CAAC;AACxD,eAAO,MAAM,4BAA4B,cAAc,CAAC;AACxD,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,4BAA4B,cAAc,CAAC;AACxD,eAAO,MAAM,kBAAkB,uCAAuC,CAAC;AACvE,eAAO,MAAM,4BAA4B,oEAAoE,CAAC"}

package/dist/providers/comicvine/constants.js

@@ -5,3 +5,5 @@ export const COMICVINE_STORY_ARC_CATEGORY = "story_arc";
 export const COMICVINE_CHARACTER_CATEGORY = "character";
 export const COMICVINE_PERSON_CATEGORY = "person";
 export const COMICVINE_PUBLISHER_CATEGORY = "publisher";
+export const COMICVINE_API_BASE = "https://comicvine.gamespot.com/api";
+export const COMICVINE_DEFAULT_USER_AGENT = "@zivue/zuuid ComicVine client (+https://github.com/zivue/zuuid)";

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

@@ -1,3 +1,5 @@
+export * from "./types.js";
+export * from "./client.js";
 export * from "./character.js";
 export * from "./constants.js";
 export * from "./issue.js";

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

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

package/dist/providers/comicvine/index.js

@@ -1,3 +1,5 @@
+export * from "./types.js";
+export * from "./client.js";
 export * from "./character.js";
 export * from "./constants.js";
 export * from "./issue.js";

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

@@ -0,0 +1,26 @@
+export type ComicVineFetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type ComicVineProviderOptions = {
+    apiKey: string;
+    apiBase?: string;
+    fetch?: ComicVineFetchLike;
+    userAgent?: string;
+};
+export type FetchComicVineInput = {
+    id: string | number;
+};
+export type ComicVineSearchInput = {
+    query: string;
+    limit?: number;
+    offset?: number;
+    fieldList?: string[];
+};
+export type ComicVineApiResponse<T> = {
+    error?: string;
+    limit?: number;
+    offset?: number;
+    number_of_page_results?: number;
+    number_of_total_results?: number;
+    status_code?: number;
+    results?: T;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/providers/comicvine/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhG,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC"}

package/dist/providers/comicvine/types.js

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

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

@@ -8,5 +8,5 @@ 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.3 (https://github.com/zivue/zuuid)";
+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.js

@@ -8,4 +8,4 @@ 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.3 (https://github.com/zivue/zuuid)";
+export const MUSICBRAINZ_DEFAULT_USER_AGENT = "@zivue/zuuid/0.2.5 (https://github.com/zivue/zuuid)";

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.3",
+  "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"