Listen API: Podcast Search, Directory, and Insights API

/**
 * ListenAPIPodcastSearchDirectoryandInsightsAPI - generated by OmniStream from Listen API: Podcast Search, Directory, and Insights API's OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/listennotes";

export class ListenAPIPodcastSearchDirectoryandInsightsAPIError extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `ListenAPIPodcastSearchDirectoryandInsightsAPI error ${status}`);
    this.name = "ListenAPIPodcastSearchDirectoryandInsightsAPIError";
    this.status = status;
    this.code = code;
  }
}

export interface ListenAPIPodcastSearchDirectoryandInsightsAPIOptions {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class ListenAPIPodcastSearchDirectoryandInsightsAPI {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: ListenAPIPodcastSearchDirectoryandInsightsAPIOptions = {}) {
    if (!token) throw new Error("ListenAPIPodcastSearchDirectoryandInsightsAPI: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new ListenAPIPodcastSearchDirectoryandInsightsAPIError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** Fetch a list of best podcasts by genre */
  getBestPodcasts(params: { "X-ListenAPI-Key": string; "genre_id"?: string; "page"?: number; "region"?: string; "publisher_region"?: string; "language"?: string; "sort"?: string; "safe_mode"?: number }): Promise<any> {
    return this._request("GET", "/best_podcasts", { params });
  }

  /** Fetch curated lists of podcasts */
  getCuratedPodcasts(params: { "X-ListenAPI-Key": string; "page"?: number }): Promise<any> {
    return this._request("GET", "/curated_podcasts", { params });
  }

  /** Fetch a curated list of podcasts by id */
  getCuratedPodcastById(params: { "X-ListenAPI-Key": string; "id": string }): Promise<any> {
    return this._request("GET", "/curated_podcasts/{id}", { params });
  }

  /** Batch fetch basic meta data for episodes */
  getEpisodesInBatch(params: { "X-ListenAPI-Key": string }): Promise<any> {
    return this._request("POST", "/episodes", { params });
  }

  /** Fetch detailed meta data for an episode by id */
  getEpisodeById(params: { "X-ListenAPI-Key": string; "id": string; "show_transcript"?: number }): Promise<any> {
    return this._request("GET", "/episodes/{id}", { params });
  }

  /** Fetch recommendations for an episode */
  getEpisodeRecommendations(params: { "X-ListenAPI-Key": string; "id": string; "safe_mode"?: number }): Promise<any> {
    return this._request("GET", "/episodes/{id}/recommendations", { params });
  }

  /** Fetch a list of podcast genres */
  getGenres(params: { "X-ListenAPI-Key": string; "top_level_only"?: number }): Promise<any> {
    return this._request("GET", "/genres", { params });
  }

  /** Fetch a random podcast episode */
  justListen(params: { "X-ListenAPI-Key": string }): Promise<any> {
    return this._request("GET", "/just_listen", { params });
  }

  /** Fetch a list of supported languages for podcasts */
  getLanguages(params: { "X-ListenAPI-Key": string }): Promise<any> {
    return this._request("GET", "/languages", { params });
  }

  /** Fetch a list of your playlists. */
  getPlaylists(params: { "X-ListenAPI-Key": string; "sort"?: string; "page"?: number }): Promise<any> {
    return this._request("GET", "/playlists", { params });
  }

  /** Fetch a playlist's info and items (i.e., episodes or podcasts). */
  getPlaylistById(params: { "X-ListenAPI-Key": string; "id": string; "type"?: string; "last_timestamp_ms"?: number; "sort"?: string }): Promise<any> {
    return this._request("GET", "/playlists/{id}", { params });
  }

  /** Batch fetch basic meta data for podcasts */
  getPodcastsInBatch(params: { "X-ListenAPI-Key": string }): Promise<any> {
    return this._request("POST", "/podcasts", { params });
  }

  /** Submit a podcast to Listen Notes database */
  submitPodcast(params: { "X-ListenAPI-Key": string }): Promise<any> {
    return this._request("POST", "/podcasts/submit", { params });
  }

  /** Fetch detailed meta data and episodes for a podcast by id */
  getPodcastById(params: { "X-ListenAPI-Key": string; "id": string; "next_episode_pub_date"?: number; "sort"?: string }): Promise<any> {
    return this._request("GET", "/podcasts/{id}", { params });
  }

  /** Request to delete a podcast */
  deletePodcastById(params: { "X-ListenAPI-Key": string; "id": string; "reason"?: string }): Promise<any> {
    return this._request("DELETE", "/podcasts/{id}", { params });
  }

  /** Fetch audience demographics for a podcast */
  getPodcastAudience(params: { "X-ListenAPI-Key": string; "id": string }): Promise<any> {
    return this._request("GET", "/podcasts/{id}/audience", { params });
  }

  /** Fetch recommendations for a podcast */
  getPodcastRecommendations(params: { "X-ListenAPI-Key": string; "id": string; "safe_mode"?: number }): Promise<any> {
    return this._request("GET", "/podcasts/{id}/recommendations", { params });
  }

  /** Fetch a list of supported countries/regions for best podcasts */
  getRegions(params: { "X-ListenAPI-Key": string }): Promise<any> {
    return this._request("GET", "/regions", { params });
  }

  /** Fetch related search terms */
  getRelatedSearches(params: { "X-ListenAPI-Key": string; "q": string }): Promise<any> {
    return this._request("GET", "/related_searches", { params });
  }

  /** Full-text search */
  search(params: { "X-ListenAPI-Key": string; "q": string; "sort_by_date"?: number; "type"?: string; "offset"?: number; "len_min"?: number; "len_max"?: number; "episode_count_min"?: number; "episode_count_max"?: number; "update_freq_min"?: number; "update_freq_max"?: number; "genre_ids"?: string; "published_before"?: number; "published_after"?: number; "only_in"?: string; "language"?: string; "region"?: string; "ocid"?: string; "ncid"?: string; "safe_mode"?: number; "unique_podcasts"?: number }): Promise<any> {
    return this._request("GET", "/search", { params });
  }

  /** Spell check on a search term */
  spellcheck(params: { "X-ListenAPI-Key": string; "q": string }): Promise<any> {
    return this._request("GET", "/spellcheck", { params });
  }

  /** Fetch trending search terms */
  getTrendingSearches(params: { "X-ListenAPI-Key": string }): Promise<any> {
    return this._request("GET", "/trending_searches", { params });
  }

  /** Typeahead search */
  typeahead(params: { "X-ListenAPI-Key": string; "q": string; "show_podcasts"?: number; "show_genres"?: number; "safe_mode"?: number }): Promise<any> {
    return this._request("GET", "/typeahead", { params });
  }
}

export default ListenAPIPodcastSearchDirectoryandInsightsAPI;