@openverb/music-atlas 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+First release of `@openverb/music-atlas`, for the Open Music Atlas API v1.
+
+- `OpenMusicAtlas` client and the ready-made `atlas` instance
+- `places()` with continent, region and kind filters; `place()`; `editions()`; `edition()`; `geojson()`
+- `find()` / `country()` by slug, ISO code or name; `search()`
+- `embedUrl()`, `embedHtml()` and, in the browser, `createEmbed()`
+- `OpenMusicAtlasError` with `status` and `retryAfter`
+- TypeScript types for every API shape; ES modules and CommonJS
+- OpenVerb: the `openverb.music_atlas` verb library (eight read-only verbs), `createMusicAtlasExecutor()` and `registerMusicAtlasVerbs()` at `@openverb/music-atlas/openverb`, with `openverb` as an optional peer dependency

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Open Music Atlas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This license covers the software in this package only. The World Music Atlas
+data and music served by Open Music Atlas are licensed separately; see
+https://openmusicatlas.org/developers.

package/README.md

@@ -0,0 +1,162 @@
+# @openverb/music-atlas
+
+The official SDK for [Open Music Atlas](https://openmusicatlas.org) — the world, mapped in music. Every place in the **World Music Atlas**, its song, editions, GeoJSON and embeddable players, in your code. Part of the [OpenVerb](https://openverb.org) developer ecosystem.
+
+- A thin, typed wrapper around the [Open Music Atlas API v1](https://openmusicatlas.org/developers)
+- No dependencies. Works in Node 18+, browsers, Deno and Bun
+- ES modules and CommonJS, with TypeScript types
+- OpenVerb verbs, so AI agents can explore the atlas
+
+```bash
+npm install @openverb/music-atlas
+```
+
+## Quick start
+
+```js
+import { atlas } from "@openverb/music-atlas"
+
+const jamaica = await atlas.country("Jamaica")
+// { slug: "jamaica", name: "Jamaica", isoCode: "JM", continent: "Americas",
+//   region: "Caribbean", coordinates: [-77.32, 18.14], ... }
+
+const { entries } = await atlas.place("jamaica")
+console.log(entries[0].entry.title)     // "Island of One People"
+console.log(entries[0].entry.embedUrl)  // the embeddable player
+```
+
+CommonJS works too:
+
+```js
+const { atlas } = require("@openverb/music-atlas")
+```
+
+## Places
+
+```js
+const all = await atlas.places()                          // every place, in listening order
+const caribbean = await atlas.places({ region: "Caribbean" })
+const africa = await atlas.places({ continent: "Africa" })
+
+await atlas.find("JM")              // by ISO code
+await atlas.find("cote d'ivoire")   // by name — case- and accent-insensitive
+await atlas.search("guinea")        // Guinea, Guinea-Bissau, Equatorial Guinea, Papua New Guinea
+```
+
+`places()` is fetched once per client and served from memory afterwards, so `find()` and `search()` are cheap.
+
+Regions and continents follow the UN M49 scheme. Where a place's classification is contested, its `kind` is `"place"` and `isDisputed` is `true`; inclusion in the atlas is not a statement about sovereignty. See the [curatorial policy](https://openmusicatlas.org/curatorial-policy).
+
+## Editions
+
+An edition gives every place a song. Once published, an edition is frozen: its songs never change.
+
+```js
+const editions = await atlas.editions()
+const founding = await atlas.edition()          // defaults to the 2026 Founding Edition
+founding.entries.forEach(({ place, entry }) => console.log(place.name, "—", entry.title))
+```
+
+## GeoJSON
+
+One point per place, with the place and its song as properties.
+
+```js
+const geo = await atlas.geojson()   // FeatureCollection
+
+// Leaflet: every place a marker, every popup a player
+L.geoJSON(geo, {
+  onEachFeature: (feature, layer) => {
+    const p = feature.properties
+    layer.bindPopup(`<b>${p.name}</b><br>${p.title}<br>` + atlas.embedHtml(p.slug, p.edition, { width: 300 }))
+  },
+}).addTo(map)
+
+// MapLibre / Mapbox
+map.addSource("atlas", { type: "geojson", data: geo })
+```
+
+## Embedding the player
+
+Songs are heard through the Open Music Atlas player. It runs in its own protected frame and links back to the place's page.
+
+```js
+atlas.embedUrl("jamaica")    // "https://openmusicatlas.org/embed/jamaica/2026-founding"
+atlas.embedHtml("jamaica")   // an <iframe> string, for servers, templates and popups
+
+// In the browser
+document.querySelector("#player").append(atlas.createEmbed("jamaica"))
+```
+
+The player fits a frame 212px tall (`EMBED_HEIGHT`) without scrolling.
+
+## For AI agents: OpenVerb
+
+The package ships an [OpenVerb](https://openverb.org) verb library, `openverb.music_atlas`, that describes what an AI may do with the atlas — find places, get a place's song or its player, list editions, get GeoJSON. Every verb is read-only.
+
+```bash
+npm install openverb
+```
+
+```js
+import { createMusicAtlasExecutor } from "@openverb/music-atlas/openverb"
+
+const executor = createMusicAtlasExecutor()
+
+await executor.execute({ verb: "get_place_song", params: { place: "Jamaica" } })
+// { verb: "get_place_song", status: "success",
+//   data: { place: {...}, edition: {...}, entry: { title: "Island of One People", embedUrl: "..." } } }
+
+await executor.execute({ verb: "list_places", params: { region: "Caribbean" } })
+```
+
+| Verb | What it does |
+|---|---|
+| `find_place` | One place by name, ISO code or slug |
+| `search_places` | Places whose name contains the query |
+| `list_places` | Places, optionally by continent, region or kind |
+| `get_place_song` | A place's song in an edition |
+| `get_embed_player` | A place's player URL and iframe |
+| `list_editions` | Every published edition |
+| `get_edition` | An edition and all its songs |
+| `get_geojson` | An edition as GeoJSON |
+
+The library itself is `@openverb/music-atlas/openverb.music_atlas.json`, or `musicAtlasLibrary` in code, ready to hand to a model as its list of available actions. Already have an executor? `registerMusicAtlasVerbs(executor)` adds the handlers to it.
+
+The OpenVerb integration is ES-module only, because `openverb` is. Everything else also works with `require()`.
+
+## Errors and limits
+
+`place()`, `edition()` and `geojson()` return `null` for something that doesn't exist. Other failures throw an `OpenMusicAtlasError`, which carries the HTTP `status` and, when the API gives one, `retryAfter` in seconds. (OpenVerb verbs report failures as `status: "error"` results instead.)
+
+```js
+import { OpenMusicAtlasError } from "@openverb/music-atlas"
+
+try {
+  await atlas.editions()
+} catch (e) {
+  if (e instanceof OpenMusicAtlasError && e.status === 429) console.log(`Wait ${e.retryAfter}s`)
+}
+```
+
+The API allows each caller 300 requests every 10 minutes, and responses are cached for an hour. Keep one client and reuse it.
+
+## Options
+
+```js
+import { OpenMusicAtlas } from "@openverb/music-atlas"
+
+const client = new OpenMusicAtlas({
+  baseUrl: "https://openmusicatlas.org",  // the default
+  fetch: customFetch,                     // optional; defaults to the global fetch
+  headers: { "X-App": "my-museum-kiosk" },
+})
+```
+
+## What's included — and what isn't
+
+The API and this package give you places, coordinates, songs' titles, descriptions and styles, editions, page links and embeddable players. They give you **no audio files, no downloadable audio links and no audio-provider identifiers**: songs are always heard through the player.
+
+## License
+
+The code in this package is MIT-licensed. The atlas's data and its music are licensed separately: the music is not licensed for download or reuse, and the terms for the data are published at [openmusicatlas.org/developers](https://openmusicatlas.org/developers). Please credit "World Music Atlas, openmusicatlas.org" and link to the place pages.

package/dist/index.cjs

@@ -0,0 +1,183 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  EMBED_HEIGHT: () => EMBED_HEIGHT,
+  FOUNDING_EDITION: () => FOUNDING_EDITION,
+  OpenMusicAtlas: () => OpenMusicAtlas,
+  OpenMusicAtlasError: () => OpenMusicAtlasError,
+  atlas: () => atlas
+});
+module.exports = __toCommonJS(src_exports);
+var DEFAULT_BASE_URL = "https://openmusicatlas.org";
+var FOUNDING_EDITION = "2026-founding";
+var EMBED_HEIGHT = 212;
+var OpenMusicAtlasError = class extends Error {
+  constructor(message, status, retryAfter = null) {
+    super(message);
+    this.name = "OpenMusicAtlasError";
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+};
+var fold = (s) => s.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().trim();
+var escapeAttr = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+var slugOf = (place) => typeof place === "string" ? place : place.slug;
+var OpenMusicAtlas = class {
+  constructor(options = {}) {
+    this.placesRequest = null;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.customFetch = options.fetch;
+    this.headers = { Accept: "application/json", ...options.headers };
+  }
+  /* ----------------------------------------------------------------- data */
+  /**
+   * Every place in the atlas, in listening order (continent, region, name).
+   * Fetched once per client and then served from memory; pass a filter to
+   * narrow it.
+   */
+  async places(filter = {}) {
+    if (!this.placesRequest) {
+      this.placesRequest = this.request("/api/v1/places").then((d) => d.places);
+      this.placesRequest.catch(() => this.placesRequest = null);
+    }
+    const all = await this.placesRequest;
+    const continent = filter.continent ? fold(filter.continent) : null;
+    const region = filter.region ? fold(filter.region) : null;
+    return all.filter(
+      (p) => (!continent || fold(p.continent ?? "") === continent) && (!region || fold(p.region ?? "") === region) && (!filter.kind || p.kind === filter.kind)
+    );
+  }
+  /** A place and its song in every published edition, or null if there is no such place. */
+  async place(place) {
+    return this.request(`/api/v1/places/${encodeURIComponent(slugOf(place))}`, { nullOn404: true });
+  }
+  /** Every published edition, newest first. */
+  async editions() {
+    return (await this.request("/api/v1/editions")).editions;
+  }
+  /** An edition and all its songs in listening order, or null if there is no such edition. */
+  async edition(slug = FOUNDING_EDITION) {
+    return this.request(`/api/v1/editions/${encodeURIComponent(slug)}`, { nullOn404: true });
+  }
+  /**
+   * An edition as a GeoJSON FeatureCollection — one point per place, with the
+   * place and its song as properties. Loads straight into Leaflet, MapLibre,
+   * Mapbox, OpenLayers or QGIS.
+   */
+  async geojson(slug = FOUNDING_EDITION) {
+    return this.request(`/api/v1/editions/${encodeURIComponent(slug)}.geojson`, {
+      nullOn404: true
+    });
+  }
+  /* -------------------------------------------------------------- finding */
+  /**
+   * One place by slug ("jamaica"), ISO code ("JM") or name ("Jamaica",
+   * "cote d'ivoire"), or null. Case- and accent-insensitive; an exact match
+   * wins over a name that merely starts with the query.
+   */
+  async find(query) {
+    const q = fold(query);
+    if (!q) return null;
+    const all = await this.places();
+    return all.find((p) => p.slug === q) ?? all.find((p) => p.isoCode !== null && p.isoCode.toLowerCase() === q) ?? all.find((p) => fold(p.name) === q) ?? all.find((p) => fold(p.name).startsWith(q)) ?? null;
+  }
+  /** The same as find(), named for the common case: `atlas.country("Jamaica")`. */
+  country(query) {
+    return this.find(query);
+  }
+  /** Places whose name contains the query, names starting with it first. */
+  async search(query) {
+    const q = fold(query);
+    if (!q) return [];
+    const all = await this.places();
+    return all.filter((p) => fold(p.name).includes(q)).sort((a, b) => Number(!fold(a.name).startsWith(q)) - Number(!fold(b.name).startsWith(q)) || a.name.localeCompare(b.name));
+  }
+  /* --------------------------------------------------------------- embeds */
+  /** The embeddable player's address for a place's song. No network request. */
+  embedUrl(place, edition = FOUNDING_EDITION) {
+    return `${this.baseUrl}/embed/${encodeURIComponent(slugOf(place))}/${encodeURIComponent(edition)}`;
+  }
+  /** An `<iframe>` for the embeddable player, as HTML — for server rendering, templates and map popups. */
+  embedHtml(place, edition = FOUNDING_EDITION, options = {}) {
+    const a = this.embedAttributes(place, edition, options);
+    return `<iframe src="${escapeAttr(a.src)}" width="${escapeAttr(a.width)}" height="${escapeAttr(a.height)}" loading="${a.loading}" style="${a.style}" allow="${a.allow}" title="${escapeAttr(a.title)}"></iframe>`;
+  }
+  /** An `<iframe>` element for the embeddable player, ready to append. Browser only. */
+  createEmbed(place, edition = FOUNDING_EDITION, options = {}) {
+    if (typeof document === "undefined") {
+      throw new Error("createEmbed() needs a browser. On the server, use embedHtml().");
+    }
+    const a = this.embedAttributes(place, edition, options);
+    const frame = document.createElement("iframe");
+    frame.src = a.src;
+    frame.width = a.width;
+    frame.height = a.height;
+    frame.loading = a.loading;
+    frame.setAttribute("style", a.style);
+    frame.allow = a.allow;
+    frame.title = a.title;
+    return frame;
+  }
+  embedAttributes(place, edition, options) {
+    const name = typeof place === "string" ? place : "name" in place ? String(place.name) : place.slug;
+    return {
+      src: this.embedUrl(place, edition),
+      width: String(options.width ?? "100%"),
+      height: String(options.height ?? EMBED_HEIGHT),
+      loading: options.loading ?? "lazy",
+      style: "border:0;border-radius:12px",
+      allow: "autoplay; encrypted-media",
+      title: options.title ?? `${name} \u2014 World Music Atlas`
+    };
+  }
+  async request(path, options = {}) {
+    const fetcher = this.customFetch ?? globalThis.fetch;
+    if (typeof fetcher !== "function") {
+      throw new Error("No fetch is available. Use Node 18 or later, or pass `fetch` in the client options.");
+    }
+    const res = await fetcher(`${this.baseUrl}${path}`, { headers: this.headers });
+    if (res.status === 404 && options.nullOn404) return null;
+    if (!res.ok) {
+      let message = `Open Music Atlas API responded with ${res.status}`;
+      try {
+        const body = await res.json();
+        if (body?.error) message = body.error;
+      } catch {
+      }
+      const retry = res.headers.get("retry-after");
+      throw new OpenMusicAtlasError(message, res.status, retry !== null && retry !== "" ? Number(retry) : null);
+    }
+    return await res.json();
+  }
+};
+var atlas = new OpenMusicAtlas();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BASE_URL,
+  EMBED_HEIGHT,
+  FOUNDING_EDITION,
+  OpenMusicAtlas,
+  OpenMusicAtlasError,
+  atlas
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n  AtlasFeatureCollection,\n  ClientOptions,\n  Edition,\n  EditionDetail,\n  EmbedOptions,\n  Place,\n  PlaceDetail,\n  PlaceFilter,\n} from \"./types\"\n\nexport type * from \"./types\"\n\n/** The public home of the World Music Atlas. */\nexport const DEFAULT_BASE_URL = \"https://openmusicatlas.org\"\n\n/** The first edition: the World Music Atlas — 2026 Founding Edition. */\nexport const FOUNDING_EDITION = \"2026-founding\"\n\n/** The height, in pixels, at which the embeddable player fits without scrolling. */\nexport const EMBED_HEIGHT = 212\n\n/** A failed request to the Open Music Atlas API. */\nexport class OpenMusicAtlasError extends Error {\n  /** The HTTP status, e.g. 429 when rate-limited. */\n  readonly status: number\n  /** Seconds to wait before retrying, when the API says so. */\n  readonly retryAfter: number | null\n\n  constructor(message: string, status: number, retryAfter: number | null = null) {\n    super(message)\n    this.name = \"OpenMusicAtlasError\"\n    this.status = status\n    this.retryAfter = retryAfter\n  }\n}\n\ntype PlaceRef = string | Pick<Place, \"slug\">\n\n/** Lower-case and strip accents, so \"Côte d'Ivoire\" matches \"cote d'ivoire\". */\nconst fold = (s: string) =>\n  s\n    .normalize(\"NFKD\")\n    .replace(/[̀-ͯ]/g, \"\")\n    .toLowerCase()\n    .trim()\n\nconst escapeAttr = (s: string) =>\n  s.replace(/&/g, \"&amp;\").replace(/\"/g, \"&quot;\").replace(/</g, \"&lt;\").replace(/>/g, \"&gt;\")\n\nconst slugOf = (place: PlaceRef) => (typeof place === \"string\" ? place : place.slug)\n\n/**\n * A client for the Open Music Atlas API (v1).\n *\n * ```ts\n * import { atlas } from \"@openverb/music-atlas\"\n *\n * const jamaica = await atlas.country(\"Jamaica\")\n * const song = await atlas.place(\"jamaica\")\n * ```\n */\nexport class OpenMusicAtlas {\n  readonly baseUrl: string\n  private readonly customFetch?: typeof fetch\n  private readonly headers: Record<string, string>\n  private placesRequest: Promise<Place[]> | null = null\n\n  constructor(options: ClientOptions = {}) {\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\")\n    this.customFetch = options.fetch\n    this.headers = { Accept: \"application/json\", ...options.headers }\n  }\n\n  /* ----------------------------------------------------------------- data */\n\n  /**\n   * Every place in the atlas, in listening order (continent, region, name).\n   * Fetched once per client and then served from memory; pass a filter to\n   * narrow it.\n   */\n  async places(filter: PlaceFilter = {}): Promise<Place[]> {\n    if (!this.placesRequest) {\n      this.placesRequest = this.request<{ places: Place[] }>(\"/api/v1/places\").then((d) => d.places)\n      // A failed load shouldn't be remembered.\n      this.placesRequest.catch(() => (this.placesRequest = null))\n    }\n    const all = await this.placesRequest\n    const continent = filter.continent ? fold(filter.continent) : null\n    const region = filter.region ? fold(filter.region) : null\n    return all.filter(\n      (p) =>\n        (!continent || fold(p.continent ?? \"\") === continent) &&\n        (!region || fold(p.region ?? \"\") === region) &&\n        (!filter.kind || p.kind === filter.kind)\n    )\n  }\n\n  /** A place and its song in every published edition, or null if there is no such place. */\n  async place(place: PlaceRef): Promise<PlaceDetail | null> {\n    return this.request<PlaceDetail>(`/api/v1/places/${encodeURIComponent(slugOf(place))}`, { nullOn404: true })\n  }\n\n  /** Every published edition, newest first. */\n  async editions(): Promise<Edition[]> {\n    return (await this.request<{ editions: Edition[] }>(\"/api/v1/editions\")).editions\n  }\n\n  /** An edition and all its songs in listening order, or null if there is no such edition. */\n  async edition(slug: string = FOUNDING_EDITION): Promise<EditionDetail | null> {\n    return this.request<EditionDetail>(`/api/v1/editions/${encodeURIComponent(slug)}`, { nullOn404: true })\n  }\n\n  /**\n   * An edition as a GeoJSON FeatureCollection — one point per place, with the\n   * place and its song as properties. Loads straight into Leaflet, MapLibre,\n   * Mapbox, OpenLayers or QGIS.\n   */\n  async geojson(slug: string = FOUNDING_EDITION): Promise<AtlasFeatureCollection | null> {\n    return this.request<AtlasFeatureCollection>(`/api/v1/editions/${encodeURIComponent(slug)}.geojson`, {\n      nullOn404: true,\n    })\n  }\n\n  /* -------------------------------------------------------------- finding */\n\n  /**\n   * One place by slug (\"jamaica\"), ISO code (\"JM\") or name (\"Jamaica\",\n   * \"cote d'ivoire\"), or null. Case- and accent-insensitive; an exact match\n   * wins over a name that merely starts with the query.\n   */\n  async find(query: string): Promise<Place | null> {\n    const q = fold(query)\n    if (!q) return null\n    const all = await this.places()\n    return (\n      all.find((p) => p.slug === q) ??\n      all.find((p) => p.isoCode !== null && p.isoCode.toLowerCase() === q) ??\n      all.find((p) => fold(p.name) === q) ??\n      all.find((p) => fold(p.name).startsWith(q)) ??\n      null\n    )\n  }\n\n  /** The same as find(), named for the common case: `atlas.country(\"Jamaica\")`. */\n  country(query: string): Promise<Place | null> {\n    return this.find(query)\n  }\n\n  /** Places whose name contains the query, names starting with it first. */\n  async search(query: string): Promise<Place[]> {\n    const q = fold(query)\n    if (!q) return []\n    const all = await this.places()\n    return all\n      .filter((p) => fold(p.name).includes(q))\n      .sort((a, b) => Number(!fold(a.name).startsWith(q)) - Number(!fold(b.name).startsWith(q)) || a.name.localeCompare(b.name))\n  }\n\n  /* --------------------------------------------------------------- embeds */\n\n  /** The embeddable player's address for a place's song. No network request. */\n  embedUrl(place: PlaceRef, edition: string = FOUNDING_EDITION): string {\n    return `${this.baseUrl}/embed/${encodeURIComponent(slugOf(place))}/${encodeURIComponent(edition)}`\n  }\n\n  /** An `<iframe>` for the embeddable player, as HTML — for server rendering, templates and map popups. */\n  embedHtml(place: PlaceRef, edition: string = FOUNDING_EDITION, options: EmbedOptions = {}): string {\n    const a = this.embedAttributes(place, edition, options)\n    return (\n      `<iframe src=\"${escapeAttr(a.src)}\" width=\"${escapeAttr(a.width)}\" height=\"${escapeAttr(a.height)}\"` +\n      ` loading=\"${a.loading}\" style=\"${a.style}\" allow=\"${a.allow}\" title=\"${escapeAttr(a.title)}\"></iframe>`\n    )\n  }\n\n  /** An `<iframe>` element for the embeddable player, ready to append. Browser only. */\n  createEmbed(place: PlaceRef, edition: string = FOUNDING_EDITION, options: EmbedOptions = {}): HTMLIFrameElement {\n    if (typeof document === \"undefined\") {\n      throw new Error(\"createEmbed() needs a browser. On the server, use embedHtml().\")\n    }\n    const a = this.embedAttributes(place, edition, options)\n    const frame = document.createElement(\"iframe\")\n    frame.src = a.src\n    frame.width = a.width\n    frame.height = a.height\n    frame.loading = a.loading\n    frame.setAttribute(\"style\", a.style)\n    frame.allow = a.allow\n    frame.title = a.title\n    return frame\n  }\n\n  private embedAttributes(place: PlaceRef, edition: string, options: EmbedOptions) {\n    const name = typeof place === \"string\" ? place : \"name\" in place ? String((place as Place).name) : place.slug\n    return {\n      src: this.embedUrl(place, edition),\n      width: String(options.width ?? \"100%\"),\n      height: String(options.height ?? EMBED_HEIGHT),\n      loading: options.loading ?? \"lazy\",\n      style: \"border:0;border-radius:12px\",\n      allow: \"autoplay; encrypted-media\",\n      title: options.title ?? `${name} — World Music Atlas`,\n    }\n  }\n\n  /* -------------------------------------------------------------- transport */\n\n  private async request<T>(path: string): Promise<T>\n  private async request<T>(path: string, options: { nullOn404: true }): Promise<T | null>\n  private async request<T>(path: string, options: { nullOn404?: boolean } = {}): Promise<T | null> {\n    const fetcher = this.customFetch ?? (globalThis as { fetch?: typeof fetch }).fetch\n    if (typeof fetcher !== \"function\") {\n      throw new Error(\"No fetch is available. Use Node 18 or later, or pass `fetch` in the client options.\")\n    }\n\n    const res = await fetcher(`${this.baseUrl}${path}`, { headers: this.headers })\n    if (res.status === 404 && options.nullOn404) return null\n    if (!res.ok) {\n      let message = `Open Music Atlas API responded with ${res.status}`\n      try {\n        const body = (await res.json()) as { error?: string }\n        if (body?.error) message = body.error\n      } catch {\n        // Not JSON; keep the generic message.\n      }\n      const retry = res.headers.get(\"retry-after\")\n      throw new OpenMusicAtlasError(message, res.status, retry !== null && retry !== \"\" ? Number(retry) : null)\n    }\n    return (await res.json()) as T\n  }\n}\n\n/** A ready-made client for https://openmusicatlas.org. */\nexport const atlas = new OpenMusicAtlas()\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,212 @@
+/**
+ * The shapes of the Open Music Atlas API, v1.
+ *
+ * v1 is a stable contract: fields may be added, never removed or renamed.
+ * Responses carry Open Music Atlas URLs and descriptive metadata only — no
+ * internal database ids, no provider identifiers and no audio files. Songs
+ * are heard through the embeddable player (`embedUrl`).
+ */
+/** What kind of place a record is. "place" is used where classification itself is contested. */
+type PlaceKind = "country" | "territory" | "continent" | "place" | "city" | "region" | "landmark";
+/** A place in the atlas. Places are permanent; each edition gives a place a song. */
+interface Place {
+    /** Stable identifier, e.g. "jamaica". */
+    slug: string;
+    name: string;
+    /** ISO 3166-1 alpha-2 code where one applies, e.g. "JM". */
+    isoCode: string | null;
+    kind: PlaceKind;
+    /** UN M49 continent, e.g. "Americas". */
+    continent: string | null;
+    /** UN M49 region, e.g. "Caribbean". */
+    region: string | null;
+    /** A representative point, [longitude, latitude]. */
+    coordinates: [number, number] | null;
+    /** Disputed or partially recognised. Inclusion is not a statement about sovereignty. */
+    isDisputed: boolean;
+    /** The place's page on Open Music Atlas. */
+    pageUrl: string;
+}
+/** A published edition of the atlas, e.g. the 2026 Founding Edition. */
+interface Edition {
+    slug: string;
+    name: string;
+    /** The collection it belongs to, e.g. "world-music-atlas". */
+    collection: string;
+    year: number;
+    version: number;
+    /** The artistic constraint for the whole edition, if any. */
+    styleConstraint: string | null;
+    /** When the edition was frozen (ISO 8601). A frozen edition's songs never change. */
+    frozenAt: string | null;
+    entryCount: number;
+    pageUrl: string;
+}
+/** The edition an entry belongs to, as it appears alongside a place. */
+interface EditionRef {
+    slug: string;
+    name: string;
+    year: number;
+    version: number;
+    frozenAt: string | null;
+}
+/** A place's song in one edition. */
+interface Entry {
+    title: string;
+    description: string | null;
+    /** The song's musical style. */
+    style: string | null;
+    curatorsSelection: boolean;
+    /** The place's page on Open Music Atlas. */
+    pageUrl: string;
+    /** The embeddable player for this song. */
+    embedUrl: string;
+}
+/** A place and its song in every published edition. */
+interface PlaceDetail {
+    place: Place;
+    entries: {
+        edition: EditionRef;
+        entry: Entry;
+    }[];
+}
+/** An edition and every song in it, in listening order. */
+interface EditionDetail {
+    edition: Edition;
+    entries: {
+        place: Place;
+        entry: Entry;
+    }[];
+}
+/** The properties of one point in an edition's GeoJSON. */
+interface AtlasFeatureProperties {
+    slug: string;
+    name: string;
+    isoCode: string | null;
+    kind: PlaceKind;
+    continent: string | null;
+    region: string | null;
+    isDisputed: boolean;
+    /** The edition's slug. */
+    edition: string;
+    title: string;
+    description: string | null;
+    style: string | null;
+    curatorsSelection: boolean;
+    pageUrl: string;
+    embedUrl: string;
+}
+interface AtlasFeature {
+    type: "Feature";
+    id: string;
+    geometry: {
+        type: "Point";
+        coordinates: [number, number];
+    };
+    properties: AtlasFeatureProperties;
+}
+/** An edition as a GeoJSON FeatureCollection: one point per place. */
+interface AtlasFeatureCollection {
+    type: "FeatureCollection";
+    name: string;
+    edition: Edition;
+    features: AtlasFeature[];
+}
+interface ClientOptions {
+    /** Defaults to https://openmusicatlas.org. */
+    baseUrl?: string;
+    /** A fetch implementation. Defaults to the global fetch (Node 18+, browsers, Deno, Bun). */
+    fetch?: typeof fetch;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+}
+interface PlaceFilter {
+    /** UN M49 continent, e.g. "Africa" (case-insensitive). */
+    continent?: string;
+    /** UN M49 region, e.g. "Caribbean" (case-insensitive). */
+    region?: string;
+    kind?: PlaceKind;
+}
+interface EmbedOptions {
+    /** Defaults to "100%". */
+    width?: number | string;
+    /** Defaults to 212, which fits the player without scrolling. */
+    height?: number | string;
+    /** The frame's accessible title. Defaults to "<place> — World Music Atlas". */
+    title?: string;
+    /** Defaults to "lazy". */
+    loading?: "lazy" | "eager";
+}
+
+/** The public home of the World Music Atlas. */
+declare const DEFAULT_BASE_URL = "https://openmusicatlas.org";
+/** The first edition: the World Music Atlas — 2026 Founding Edition. */
+declare const FOUNDING_EDITION = "2026-founding";
+/** The height, in pixels, at which the embeddable player fits without scrolling. */
+declare const EMBED_HEIGHT = 212;
+/** A failed request to the Open Music Atlas API. */
+declare class OpenMusicAtlasError extends Error {
+    /** The HTTP status, e.g. 429 when rate-limited. */
+    readonly status: number;
+    /** Seconds to wait before retrying, when the API says so. */
+    readonly retryAfter: number | null;
+    constructor(message: string, status: number, retryAfter?: number | null);
+}
+type PlaceRef = string | Pick<Place, "slug">;
+/**
+ * A client for the Open Music Atlas API (v1).
+ *
+ * ```ts
+ * import { atlas } from "@openverb/music-atlas"
+ *
+ * const jamaica = await atlas.country("Jamaica")
+ * const song = await atlas.place("jamaica")
+ * ```
+ */
+declare class OpenMusicAtlas {
+    readonly baseUrl: string;
+    private readonly customFetch?;
+    private readonly headers;
+    private placesRequest;
+    constructor(options?: ClientOptions);
+    /**
+     * Every place in the atlas, in listening order (continent, region, name).
+     * Fetched once per client and then served from memory; pass a filter to
+     * narrow it.
+     */
+    places(filter?: PlaceFilter): Promise<Place[]>;
+    /** A place and its song in every published edition, or null if there is no such place. */
+    place(place: PlaceRef): Promise<PlaceDetail | null>;
+    /** Every published edition, newest first. */
+    editions(): Promise<Edition[]>;
+    /** An edition and all its songs in listening order, or null if there is no such edition. */
+    edition(slug?: string): Promise<EditionDetail | null>;
+    /**
+     * An edition as a GeoJSON FeatureCollection — one point per place, with the
+     * place and its song as properties. Loads straight into Leaflet, MapLibre,
+     * Mapbox, OpenLayers or QGIS.
+     */
+    geojson(slug?: string): Promise<AtlasFeatureCollection | null>;
+    /**
+     * One place by slug ("jamaica"), ISO code ("JM") or name ("Jamaica",
+     * "cote d'ivoire"), or null. Case- and accent-insensitive; an exact match
+     * wins over a name that merely starts with the query.
+     */
+    find(query: string): Promise<Place | null>;
+    /** The same as find(), named for the common case: `atlas.country("Jamaica")`. */
+    country(query: string): Promise<Place | null>;
+    /** Places whose name contains the query, names starting with it first. */
+    search(query: string): Promise<Place[]>;
+    /** The embeddable player's address for a place's song. No network request. */
+    embedUrl(place: PlaceRef, edition?: string): string;
+    /** An `<iframe>` for the embeddable player, as HTML — for server rendering, templates and map popups. */
+    embedHtml(place: PlaceRef, edition?: string, options?: EmbedOptions): string;
+    /** An `<iframe>` element for the embeddable player, ready to append. Browser only. */
+    createEmbed(place: PlaceRef, edition?: string, options?: EmbedOptions): HTMLIFrameElement;
+    private embedAttributes;
+    private request;
+}
+/** A ready-made client for https://openmusicatlas.org. */
+declare const atlas: OpenMusicAtlas;
+
+export { type AtlasFeature, type AtlasFeatureCollection, type AtlasFeatureProperties, type ClientOptions, DEFAULT_BASE_URL, EMBED_HEIGHT, type Edition, type EditionDetail, type EditionRef, type EmbedOptions, type Entry, FOUNDING_EDITION, OpenMusicAtlas, OpenMusicAtlasError, type Place, type PlaceDetail, type PlaceFilter, type PlaceKind, atlas };