@openverb/music-atlas 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,153 @@
+// src/index.ts
+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();
+export {
+  DEFAULT_BASE_URL,
+  EMBED_HEIGHT,
+  FOUNDING_EDITION,
+  OpenMusicAtlas,
+  OpenMusicAtlasError,
+  atlas
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.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/openverb.d.ts

@@ -0,0 +1,26 @@
+import * as openverb from 'openverb';
+import { VerbHandler, ActionResult, VerbLibrary } from 'openverb';
+import { OpenMusicAtlas } from '@openverb/music-atlas';
+
+declare const MUSIC_ATLAS_NAMESPACE = "openverb.music_atlas";
+/** The verb library: everything an AI may do with the World Music Atlas. */
+declare const musicAtlasLibrary: VerbLibrary;
+/** Anything handlers can be registered on — an OpenVerb executor, or your own registry. */
+interface VerbRegistrar {
+    register(verbName: string, handler: VerbHandler): void;
+}
+/**
+ * Register a handler for every Music Atlas verb on an executor, using the
+ * given client (by default, the one for https://openmusicatlas.org).
+ */
+declare function registerMusicAtlasVerbs(executor: VerbRegistrar, client?: OpenMusicAtlas): void;
+/** An OpenVerb executor with every Music Atlas verb registered and ready to run. */
+declare function createMusicAtlasExecutor(client?: OpenMusicAtlas): {
+    register(verbName: string, handler: VerbHandler): void;
+    execute(action: openverb.Action): Promise<ActionResult>;
+    getRegistry(): openverb.VerbRegistry;
+    getVerbs(): string[];
+    getVerb(name: string): openverb.Verb | undefined;
+};
+
+export { MUSIC_ATLAS_NAMESPACE, type VerbRegistrar, createMusicAtlasExecutor, musicAtlasLibrary, registerMusicAtlasVerbs };