@zivue/zuuid 0.1.0 → 0.2.1

package/README.md

@@ -1,10 +1,12 @@
 # @zivue/zuuid
 
-TypeScript helpers for fetching, searching, and transforming Zuuid datasets.
+Search, fetch, and normalize media metadata from external providers into a shared Zuuid data shape.
 
-Zuuid is the metadata, search, and indexing substrate for Zivue/Stareto. This package focuses on the client-side model: provider-stable UUIDs, source records, and normalized Zuuid datasets.
+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.
 
-Storage, caching, object keys, and persistence belong in a layer outside this package.
+TMDB and Open Library include live search/fetch clients. 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.
 
 ## Install
 
@@ -21,6 +23,9 @@ const zuuid = createZuuidClient({
   providers: {
     tmdb: {
       bearerToken: process.env.TMDB_BEARER_TOKEN!
+    },
+    openlibrary: {
+      // Open Library does not require credentials.
     }
   }
 });
@@ -29,98 +34,97 @@ const search = await zuuid.movie.tmdb?.search({ query: "Fight Club" });
 const selected = search?.results[0];
 const movie = selected ? await zuuid.movie.tmdb?.fetch({ id: selected.source.value }) : undefined;
 
-console.log(movie?.zuuid);
-```
-
-## Generate A ZUUID
-
-Zuuid generation is UUID v5:
-
-```txt
-uuid_v5(provider_namespace, "<normalized-category>:<external_id>")
+console.log(movie?.primaryTitle);
+// Fight Club
 ```
 
-```ts
-import { providerZuuid } from "@zivue/zuuid";
-
-const zuuid = await providerZuuid({
-  provider: "tmdb",
-  category: "movie",
-  externalId: "550"
-});
+## What You Get
 
-console.log(zuuid);
-// 1706d641-d381-5618-9425-d8cd8b35f898
-```
+The package has two main output shapes:
 
-`category` is trimmed and lowercased. `externalId` is trimmed but otherwise preserved.
+- `SearchResponse<ZuuidSearchResult>` for search/list screens.
+- `ZuuidData` for full fetched and transformed datasets.
 
-## Zuuid Dataset
+Search is lightweight and paginated. Fetch returns the full normalized dataset for a selected provider ID.
 
 ```ts
-import { createZuuidData } from "@zivue/zuuid";
-
-const dataset = createZuuidData({
-  zuuid: "1706d641-d381-5618-9425-d8cd8b35f898",
-  category: "movie",
-  primaryTitle: "Fight Club"
-});
-```
+const movies = await zuuid.movie.tmdb?.search({ query: "Fight Club" });
 
-The dataset shape is intentionally flat:
+console.log(movies?.pagination);
+// { page: 1, totalPages: 10, totalResults: 190 }
 
-```ts
-type ZuuidData = {
-  zuuid: string;
-  kind: EntityKind;
-  category: string;
-  primaryTitle: string;
-  primaryDate?: string;
-  rating?: number;
-  cover?: string;
-  aliases: Alias[];
-  descriptions: Description[];
-  details: Detail[];
-  media: MediaAsset[];
-  relations: EntityRelation[];
-  recommendations: RecommendationEdge[];
-  tags: string[];
-  externalIds: ExternalId[];
-  provenance: Provenance[];
-};
+console.log(movies?.results[0]);
+// {
+//   id: "1706d641-d381-5618-9425-d8cd8b35f898",
+//   zuuid: "1706d641-d381-5618-9425-d8cd8b35f898",
+//   category: "movie",
+//   title: "Fight Club",
+//   date: "1999-10-15",
+//   cover: "https://image.tmdb.org/t/p/w500/...",
+//   rating: 4.2,
+//   weight: 20.0,
+//   relationType: null,
+//   attribute: null,
+//   order: null,
+//   source: { source: "tmdb", category: "movie", value: "550" }
+// }
 ```
 
-Search results, relations, and recommendations use the same lightweight list item fields: `id`, `zuuid`, `category`, `title`, `date`, `cover`, `rating`, `weight`, `relationType`, `attribute`, and `order`. That lets transformed datasets and search results carry useful related-entity context before those related entities are fetched as full Zuuid datasets.
-
-Backend-only concerns such as record versions, flags, review state, index state, and object-store metadata are intentionally not part of this package's dataset shape.
-
-## Source Metadata
-
-Source records are provider records before they are transformed into canonical entities. They carry the external provider key, raw JSON payload, content hash, and observation timestamps.
+The full fetched dataset is flat and provider-normalized:
 
 ```ts
-import { attachSourceMetadata, createSourceRecord } from "@zivue/zuuid";
+const movie = await zuuid.movie.tmdb?.fetch({ id: "550" });
 
-const source = await createSourceRecord({
-  source: { provider: "tmdb", category: "movie", externalId: "550" },
-  payload: { title: "Fight Club" },
-  observedAt: "2026-05-21T00:00:00.000Z"
-});
-
-const withSource = attachSourceMetadata(dataset, source);
+console.log(movie);
+// {
+//   zuuid,
+//   kind: "watch",
+//   category: "movie",
+//   primaryTitle: "Fight Club",
+//   primaryDate: "1999-10-15",
+//   rating,
+//   cover,
+//   aliases,
+//   descriptions,
+//   details,
+//   media,
+//   relations,
+//   recommendations,
+//   tags,
+//   externalIds,
+//   provenance
+// }
 ```
 
-`attachSourceMetadata` returns a new dataset with `externalIds` and `provenance` updated.
+Search results, relations, and recommendations share the same lightweight list item fields: `id`, `zuuid`, `category`, `title`, `date`, `cover`, `rating`, `weight`, `relationType`, `attribute`, and `order`.
 
-## TMDB Movies, TV, And People
+Ratings are normalized to a `0-5` scale when the provider exposes a compatible numeric score. The original provider score is preserved in details as `provider_rating` for providers whose native scale differs.
 
-The first provider module supports fetching and transforming TMDB movies, TV shows, and people.
+## Supported Providers
 
 | Provider | Category | Search | Fetch | Transform |
 | --- | --- | --- | --- | --- |
 | TMDB | movie | yes | yes | yes |
 | TMDB | tv | yes | yes | yes |
 | 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 |
+| GamesDB | game, platform | no | no | yes |
+| Jikan | anime, manga, producer, magazine, character, person | no | no | yes |
+| MusicBrainz | release, release-group, recording, artist, label, work | no | no | yes |
+| OpenFoodFacts | product | no | no | yes |
+| OpenStreetMap | city, country, place, venue | no | no | 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 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.
+
+## TMDB Credentials
+
+`TmdbProvider` accepts either a TMDB API Read Access Token or a v3 API key:
 
 ```ts
 import { TmdbProvider } from "@zivue/zuuid/providers/tmdb";
@@ -129,240 +133,312 @@ const tmdb = new TmdbProvider({
   bearerToken: process.env.TMDB_BEARER_TOKEN!
 });
 
-const movie = await tmdb.fetchMovie({ id: 550 });
-const tv = await tmdb.fetchTv({ id: 1399 });
-const person = await tmdb.fetchPerson({ id: 287 });
-
-console.log(movie?.zuuid);
-// 1706d641-d381-5618-9425-d8cd8b35f898
+// or
+const tmdbWithApiKey = new TmdbProvider({
+  apiKey: process.env.TMDB_API_KEY!
+});
 ```
 
-You can also split fetching from transformation:
-
-```ts
-import { TmdbProvider, transformTmdbMovie, transformTmdbPerson, transformTmdbTv } from "@zivue/zuuid/providers/tmdb";
+TMDB bearer tokens usually start with `eyJ...`; v3 API keys are shorter hex-like strings.
 
-const source = await tmdb.fetchMovieSourceRecord({ id: 550 });
-const movie = source ? await transformTmdbMovie(source) : undefined;
+## Search
 
-const tvSource = await tmdb.fetchTvSourceRecord({ id: 1399 });
-const tv = tvSource ? await transformTmdbTv(tvSource) : undefined;
+Use the category-first client facade when your app may have several providers:
 
-const personSource = await tmdb.fetchPersonSourceRecord({ id: 287 });
-const person = personSource ? await transformTmdbPerson(personSource) : undefined;
+```ts
+const movies = await zuuid.movie.tmdb?.search({ query: "Fight Club" });
+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" });
 ```
 
-Search returns unified lightweight candidates. Use search to find candidate IDs, then fetch the selected item for the full transformed dataset:
+Provider methods are also available directly:
 
 ```ts
 const movies = await tmdb.searchMovies({ query: "Fight Club" });
 const tvShows = await tmdb.searchTv({ query: "Game of Thrones" });
 const people = await tmdb.searchPeople({ query: "Brad Pitt" });
+```
 
-console.log(movies.pagination);
-// { page: 1, totalPages: 10, totalResults: 190 }
-
-const selectedMovie = movies.results[0];
-console.log(selectedMovie);
-// {
-//   id: "1706d641-d381-5618-9425-d8cd8b35f898",
-//   zuuid: "1706d641-d381-5618-9425-d8cd8b35f898",
-//   category: "movie",
-//   title: "Fight Club",
-//   date: "1999-10-15",
-//   cover: "https://image.tmdb.org/t/p/w500/...",
-//   rating: 8.4,
-//   weight: 20.0,
-//   relationType: null,
-//   attribute: null,
-//   order: null,
-//   source: { source: "tmdb", category: "movie", value: "550" }
-// }
+```ts
+import { OpenLibraryProvider } from "@zivue/zuuid/providers/openlibrary";
 
-const fullMovie = selectedMovie ? await tmdb.fetchMovie({ id: selectedMovie.source.value }) : undefined;
+const openlibrary = new OpenLibraryProvider();
+const books = await openlibrary.searchBooks({ query: "The Lord of the Rings" });
+const authors = await openlibrary.searchAuthors({ query: "J. K. Rowling" });
 ```
 
-Raw search source records are also available:
+Search options include pagination and common TMDB filters:
 
 ```ts
-const rawMovies = await tmdb.searchMovieSourceRecords({ query: "Fight Club" });
+const movies = await tmdb.searchMovies({
+  query: "Fight Club",
+  page: 2,
+  includeAdult: false,
+  primaryReleaseYear: 1999
+});
 ```
 
-Category-specific imports are also available:
+If you need the raw TMDB search payload wrapped as source records:
 
 ```ts
-import { transformTmdbMovie } from "@zivue/zuuid/providers/tmdb/movie";
-import { transformTmdbTv } from "@zivue/zuuid/providers/tmdb/tv";
-import { transformTmdbPerson } from "@zivue/zuuid/providers/tmdb/person";
+const rawMovies = await tmdb.searchMovieSourceRecords({ query: "Fight Club" });
 ```
 
-`TmdbProvider` accepts either `{ bearerToken }` or `{ apiKey }`. TMDB bearer tokens are API Read Access Tokens and usually start with `eyJ...`; v3 API keys are shorter hex-like strings.
+## Fetch
 
-## Client Instantiation
-
-For applications with multiple providers, use `createZuuidClient` to wire provider config once:
+Fetch returns transformed `ZuuidData`:
 
 ```ts
-import { createZuuidClient } from "@zivue/zuuid";
-
-const zuuid = createZuuidClient({
-  providers: {
-    tmdb: {
-      bearerToken: process.env.TMDB_BEARER_TOKEN!
-    }
-    // Future movie providers can sit beside tmdb, e.g. omdb.
-  }
-});
-
 const movie = await zuuid.movie.tmdb?.fetch({ id: 550 });
 const tv = await zuuid.tv.tmdb?.fetch({ id: 1399 });
 const person = await zuuid.people.tmdb?.fetch({ id: 287 });
+const book = await zuuid.read.openlibrary?.fetch({ id: "OL82563W" });
+const author = await zuuid.people.openlibrary?.fetch({ id: "OL23919A" });
 ```
 
-The config is provider-keyed because apps usually manage credentials per provider. The client facade is category-first, so multiple movie providers can live under `zuuid.movie`:
+Direct provider methods are equivalent:
 
 ```ts
-zuuid.movie.tmdb?.fetch({ id: 550 });
-zuuid.tv.tmdb?.fetch({ id: 1399 });
-zuuid.people.tmdb?.fetch({ id: 287 });
+const movie = await tmdb.fetchMovie({ id: 550 });
+const tv = await tmdb.fetchTv({ id: 1399 });
+const person = await tmdb.fetchPerson({ id: 287 });
 
-zuuid.movie.tmdb?.search({ query: "Fight Club" });
-zuuid.tv.tmdb?.search({ query: "Game of Thrones" });
-zuuid.people.tmdb?.search({ query: "Brad Pitt" });
-// later: zuuid.movie.omdb?.fetch(...)
+const book = await openlibrary.fetchBook({ id: "OL82563W" });
+const author = await openlibrary.fetchAuthor({ id: "OL23919A" });
 ```
 
-The client is stateless: it does not cache, persist, schedule, or read environment variables. It only closes over provider configuration and exposes category/provider methods.
+## Raw Source Records And Transform
 
-## API
+For debugging, caching in your own layer, or custom transform timing, split fetch from transform:
 
-## Package Structure
+```ts
+import { transformTmdbMovie } from "@zivue/zuuid/providers/tmdb";
 
-The source is split by Zuuid responsibility:
+const source = await tmdb.fetchMovieSourceRecord({ id: 550 });
+const movie = source ? await transformTmdbMovie(source, tmdb.transformOptions()) : undefined;
+```
 
-- `identity.ts`: provider namespaces and UUID v5 ZUUID generation
-- `entity.ts`: flat Zuuid data types and category helpers
-- `client.ts`: stateless package instantiator for configured providers
-- `providers/<provider>/index.ts`: provider module barrel
-- `providers/<provider>/client.ts`: shared provider client/config
-- `providers/<provider>/<category>.ts`: category-specific fetch and transform helpers
-- `providers/tmdb/movie.ts`: TMDB movie fetch and transform helpers
-- `providers/tmdb/tv.ts`: TMDB TV fetch and transform helpers
-- `providers/tmdb/person.ts`: TMDB person fetch and transform helpers
-- `source.ts`: source records, external IDs, and provenance
-- `hash.ts`: stable payload hashing
-- `uuid.ts`: UUID parsing/normalization and UUID v5 internals
-- `types.ts`: shared JSON value types
-- `index.ts`: public barrel exports
+The source record contains the raw payload:
 
-### `providerZuuid(input)`
+```ts
+console.log(source?.payload);
+```
 
-Generates a deterministic ZUUID for a provider/category/external ID.
+The transform result is normalized `ZuuidData`:
 
-### `providerNamespace(provider)`
+```ts
+console.log(movie?.primaryTitle);
+console.log(movie?.externalIds);
+console.log(movie?.provenance);
+```
 
-Returns the UUID namespace configured for a known provider.
+For transformer-only providers:
 
-### `createZuuidData(input)`
+```ts
+import { createSourceRecord, transformGamesDbGame } from "@zivue/zuuid";
 
-Creates a normalized Zuuid dataset.
+const source = await createSourceRecord({
+  source: { provider: "gamesdb", category: "game", externalId: "17444" },
+  payload: rawGamesDbPayload
+});
 
-### `createSourceRecord(input)`
+const game = await transformGamesDbGame(source);
+```
 
-Creates a source record and computes the SHA-256 payload hash used for provenance.
+Category-specific imports are available:
 
-### `attachSourceMetadata(dataset, sourceRecord, confidence?)`
+```ts
+import { transformTmdbMovie } from "@zivue/zuuid/providers/tmdb/movie";
+import { transformTmdbTv } from "@zivue/zuuid/providers/tmdb/tv";
+import { transformTmdbPerson } from "@zivue/zuuid/providers/tmdb/person";
+import { transformOpenLibraryBook } from "@zivue/zuuid/providers/openlibrary/book";
+import { transformOpenLibraryAuthor } from "@zivue/zuuid/providers/openlibrary/author";
+import { transformMusicBrainzReleaseGroup } from "@zivue/zuuid/providers/musicbrainz/release-group";
+import { transformComicVineIssue } from "@zivue/zuuid/providers/comicvine/issue";
+import { transformJikanProducer } from "@zivue/zuuid/providers/jikan/producer";
+import { transformOpenStreetMapVenue } from "@zivue/zuuid/providers/openstreetmap/venue";
+import { transformWgerEquipment } from "@zivue/zuuid/providers/wger/equipment";
+```
 
-Returns a new dataset with external ID and provenance attached.
+## Data Model
 
-### `TmdbProvider`
+`ZuuidData` is the full normalized dataset:
 
-Fetches TMDB source records and transforms them into `ZuuidData`.
+```ts
+type ZuuidData = {
+  zuuid: string;
+  kind: EntityKind;
+  category: string;
+  primaryTitle: string;
+  primaryDate?: string;
+  rating?: number;
+  cover?: string;
+  aliases: Alias[];
+  descriptions: Description[];
+  details: Detail[];
+  media: MediaAsset[];
+  relations: EntityRelation[];
+  recommendations: RecommendationEdge[];
+  tags: string[];
+  externalIds: ExternalId[];
+  provenance: Provenance[];
+};
+```
 
-### `transformTmdbMovie(sourceRecord, options?)`
+`Detail.value` can be any JSON value, so details can hold strings, numbers, booleans, arrays, or structured objects without duplicating `value` and `data` fields.
 
-Transforms an already-fetched TMDB movie source record into `ZuuidData`.
+## ZUUIDs
 
-### `transformTmdbTv(sourceRecord, options?)`
+Every fetched dataset and unified search result includes a `zuuid`. This is a deterministic UUID v5 generated from the provider namespace, category, and external ID. It gives your app a stable cross-provider identifier while the provider's own ID remains available in `source` or `externalIds`.
 
-Transforms an already-fetched TMDB TV source record into `ZuuidData`.
+```ts
+import { providerZuuid } from "@zivue/zuuid";
 
-### `transformTmdbPerson(sourceRecord, options?)`
+const zuuid = await providerZuuid({
+  provider: "tmdb",
+  category: "movie",
+  externalId: "550"
+});
+```
 
-Transforms an already-fetched TMDB person source record into `ZuuidData`.
+Most applications do not need to call `providerZuuid` directly; search and fetch do it internally.
 
-### `categoryFor(value)`
+## Client Design
 
-Normalizes a category and derives its entity kind.
+The client is stateless. It does not cache, persist, schedule, read environment variables, or write files. It only closes over provider configuration and exposes category/provider methods:
 
-### `kindForCategory(category)`
+```ts
+zuuid.movie.tmdb?.search({ query: "Fight Club" });
+zuuid.movie.tmdb?.fetch({ id: 550 });
 
-Maps categories such as `movie`, `book`, `game`, `restaurant`, and `person` to broad kinds such as `watch`, `read`, `play`, `visit`, and `people`.
+zuuid.tv.tmdb?.search({ query: "Game of Thrones" });
+zuuid.tv.tmdb?.fetch({ id: 1399 });
 
-## Development
+zuuid.people.tmdb?.search({ query: "Brad Pitt" });
+zuuid.people.tmdb?.fetch({ id: 287 });
+zuuid.people.openlibrary?.search({ query: "J. K. Rowling" });
+zuuid.people.openlibrary?.fetch({ id: "OL23919A" });
 
-```sh
-npm install
-npm test
+zuuid.read.openlibrary?.search({ query: "The Lord of the Rings" });
+zuuid.read.openlibrary?.fetch({ id: "OL82563W" });
 ```
 
-## Try It
+## Example Scripts
 
-Fetch and transform TMDB movie `550`:
+The examples read `.env` from the repo root:
 
 ```sh
-TMDB_BEARER_TOKEN=... npm run example:tmdb-fetch -- movie 550
+TMDB_BEARER_TOKEN=...
+# or
+TMDB_READ_ACCESS_TOKEN=...
+# or
+TMDB_API_KEY=...
 ```
 
-or:
+Search a provider and print unified search results:
 
 ```sh
-TMDB_API_KEY=... npm run example:tmdb-fetch -- movie 550
+npm run example:search -- movie "Fight Club"
+npm run example:search -- tv "Game of Thrones"
+npm run example:search -- people "Brad Pitt"
+npm run example:search -- book "The Lord of the Rings"
+npm run example:search -- author "J. K. Rowling"
 ```
 
-Fetch and transform TMDB TV show `1399`:
+Fetch and transform a selected provider ID:
 
 ```sh
-TMDB_BEARER_TOKEN=... npm run example:tmdb-fetch -- tv 1399
+npm run example:fetch -- movie 550
+npm run example:fetch -- tv 1399
+npm run example:fetch -- people 287
+npm run example:fetch -- book OL82563W
+npm run example:fetch -- author OL23919A
 ```
 
-Fetch and transform TMDB person `287`:
+Fetch fixture-backed transformer examples:
 
 ```sh
-TMDB_BEARER_TOKEN=... npm run example:tmdb-fetch -- people 287
+npm run example:fetch -- gamesdb:game 17444
+npm run example:fetch -- gamesdb:platform 6
+npm run example:fetch -- musicbrainz:release-group aaa50249-1e6b-3910-b830-7e2fb622a8c4
+npm run example:fetch -- musicbrainz:recording 0b5d8c0f-4975-4e44-9e67-0a5f1b5939f6
+npm run example:fetch -- comicvine:issue 101
+npm run example:fetch -- comicvine:story_arc 201
+npm run example:fetch -- jikan:producer 14
+npm run example:fetch -- jikan:magazine 1
+npm run example:fetch -- openfoodfacts:product 3017620422003
+npm run example:fetch -- openstreetmap:venue W123456
+npm run example:fetch -- wger:equipment 7
 ```
 
-Search TMDB and print unified search results:
+`example:fetch` writes both raw and transformed JSON:
 
-```sh
-npm run example:tmdb-search -- movie "Fight Club"
-npm run example:tmdb-search -- tv "Game of Thrones"
-npm run example:tmdb-search -- people "Brad Pitt"
+```text
+data/<provider>/<category>/<id>.raw.json
+data/<provider>/<category>/<id>.zuuid.json
 ```
 
-The example also reads `.env` from the repo root:
+`example:search` writes raw and transformed search JSON:
 
-```sh
-TMDB_BEARER_TOKEN=...
-# or
-TMDB_READ_ACCESS_TOKEN=...
-# or
-TMDB_API_KEY=...
+```text
+data/<provider>/search/<category>/<query>.raw-search.json
+data/<provider>/search/<category>/<query>.zuuid-search.json
 ```
 
-If both token and API key are present, the example uses the bearer token first. TMDB's API Read Access Token usually starts with `eyJ...`; the v3 API key is a shorter hex-like string.
-
-If `TMDB_API_KEY` accidentally contains a token starting with `eyJ`, the example treats it as a bearer token and sends it as `Authorization: Bearer ...`.
+## API Reference
+
+Core exports:
+
+- `createZuuidClient(config)`
+- `providerZuuid(input)`
+- `providerNamespace(provider)`
+- `categoryFor(value)`
+- `kindForCategory(category)`
+- `createSourceRecord(input)`
+- `attachSourceMetadata(dataset, sourceRecord, confidence?)`
+
+Provider exports:
+
+- `TmdbProvider`
+- `OpenLibraryProvider`
+- `transformTmdbMovie(sourceRecord, options?)`
+- `transformTmdbTv(sourceRecord, options?)`
+- `transformTmdbPerson(sourceRecord, options?)`
+- `transformOpenLibraryBook(sourceRecord, options?)`
+- `transformOpenLibraryAuthor(sourceRecord, options?)`
+- `transformComicVine(sourceRecord)`
+- `transformGamesDbGame(sourceRecord, options?)`
+- `transformGamesDbPlatform(sourceRecord)`
+- `transformJikan(sourceRecord)`
+- `transformMusicBrainzRelease(sourceRecord, options?)`
+- `transformMusicBrainzReleaseGroup(sourceRecord, options?)`
+- `transformMusicBrainzRecording(sourceRecord)`
+- `transformMusicBrainzArtist(sourceRecord)`
+- `transformMusicBrainzLabel(sourceRecord)`
+- `transformMusicBrainzWork(sourceRecord)`
+- `transformOpenFoodFactsProduct(sourceRecord)`
+- `transformOpenStreetMapPlace(sourceRecord)`
+- `transformPodcast(sourceRecord)`
+- `transformSetlistFm(sourceRecord)`
+- `transformTicketmaster(sourceRecord)`
+- `transformWgerExercise(sourceRecord)`
+- `transformWgerEquipment(sourceRecord)`
+- `searchTmdbMovies(provider, input, options?)`
+- `searchTmdbTv(provider, input, options?)`
+- `searchTmdbPeople(provider, input, options?)`
+- `searchOpenLibraryBooks(provider, input, options?)`
+- `searchOpenLibraryAuthors(provider, input, options?)`
 
-The example writes debug output to:
+## Development
 
-```txt
-data/tmdb/movie/550.raw.json
-data/tmdb/movie/550.zuuid.json
-data/tmdb/tv/1399.raw.json
-data/tmdb/tv/1399.zuuid.json
-data/tmdb/people/287.raw.json
-data/tmdb/people/287.zuuid.json
-data/tmdb/search/movie/fight-club.zuuid-search.json
-data/tmdb/search/movie/fight-club.raw-search.json
+```sh
+npm install
+npm test
+npm pack --dry-run
 ```
+
+## Package Boundary
+
+This package intentionally does not include storage, caching, object-store metadata, record versions, review state, index state, or backend flags. Those concerns should live in the consuming application or service.