BBC Nitro API

/**
 * BBCNitroAPI - generated by OmniStream from BBC Nitro 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/bbc";

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

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

export class BBCNitroAPI {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: BBCNitroAPIOptions = {}) {
    if (!token) throw new Error("BBCNitroAPI: 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 BBCNitroAPIError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** Get API definition */
  getAPI(): Promise<any> {
    return this._request("GET", "/", {});
  }

  /** Discover details of on-demand availability for programmes and their versions */
  listAvailability(params: { "sort"?: string; "sort_direction"?: string; "availability"?: unknown[]; "descendants_of"?: unknown[]; "media_set"?: unknown[]; "page"?: number; "page_size"?: number; "territory"?: unknown[]; "debug"?: boolean }): Promise<any> {
    return this._request("GET", "/availabilities", { params });
  }

  /** Build schedules and find metadata for TV and radio broadcasts */
  listBroadcasts(params: { "sort"?: string; "sort_direction"?: string; "mixin"?: unknown[]; "authority"?: unknown[]; "descendants_of"?: unknown[]; "end_from"?: string; "end_to"?: string; "format"?: unknown[]; "genre"?: unknown[]; "id"?: unknown[]; "item"?: unknown[]; "page"?: number; "page_size"?: number; "people"?: string; "pid"?: unknown[]; "q"?: string; "schedule_day"?: string; "schedule_day_from"?: string; "schedule_day_to"?: string; "service_master_brand"?: unknown[]; "sid"?: unknown[]; "start_from"?: string; "start_to"?: string; "version"?: unknown[] }): Promise<any> {
    return this._request("GET", "/broadcasts", { params });
  }

  /** Find metadata for curated groups: seasons, collections, galleries or franchises */
  listGroups(params: { "sort"?: string; "sort_direction"?: string; "mixin"?: unknown[]; "for_descendants_of"?: string; "for_programme"?: string; "group"?: string; "group_type"?: unknown[]; "member"?: string; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "pid"?: unknown[]; "q"?: string; "embargoed"?: string }): Promise<any> {
    return this._request("GET", "/groups", { params });
  }

  /** Find metadata for images */
  listImages(params: { "sort"?: string; "sort_direction"?: string; "group"?: string; "image_type"?: unknown[]; "is_alternate_image_for"?: string; "is_image_for"?: string; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "pid"?: unknown[]; "q"?: string; "embargoed"?: string }): Promise<any> {
    return this._request("GET", "/images", { params });
  }

  /** Look inside programmes to find segments: chapters, tracks and more */
  listItems(params: { "sort"?: string; "sort_direction"?: string; "mixin"?: unknown[]; "authority"?: string; "id"?: unknown[]; "id_type"?: string; "item_type"?: unknown[]; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "people"?: string; "pid"?: unknown[]; "programme"?: string; "q"?: string; "segment_event"?: string }): Promise<any> {
    return this._request("GET", "/items", { params });
  }

  /** List all Master Brands */
  listMasterbrands(params: { "sort"?: string; "sort_direction"?: string; "mixin"?: unknown[]; "mid"?: unknown[]; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "q"?: string }): Promise<any> {
    return this._request("GET", "/master_brands", { params });
  }

  /** Find the people behind and in programmes: cast, crew, guests and more */
  listPeople(params: { "authority"?: string; "has_external_id"?: unknown[]; "id"?: unknown[]; "id_type"?: string; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "pid"?: unknown[]; "programme"?: string; "q"?: string }): Promise<any> {
    return this._request("GET", "/people", { params });
  }

  /** Look inside pips entities */
  listPips(params: { "page"?: number; "page_size"?: number; "q"?: string }): Promise<any> {
    return this._request("GET", "/pips", { params });
  }

  /** Exposes programme information for a single pid */
  listProgrammeDetails(params: { "page"?: number; "page_size"?: number; "partner_pid"?: string; "pid"?: string }): Promise<any> {
    return this._request("GET", "/programme_details", { params });
  }

  /** Start here for programmes metadata: Brands, Series, Episodes and Clips */
  listProgrammes(params: { "sort"?: string; "sort_direction"?: string; "mixin"?: unknown[]; "audio_described"?: unknown[]; "availability"?: unknown[]; "availability_entity_type"?: unknown[]; "availability_from"?: string; "availability_type"?: unknown[]; "children_of"?: unknown[]; "descendants_of"?: unknown[]; "duration"?: unknown[]; "entity_type"?: unknown[]; "format"?: unknown[]; "genre"?: unknown[]; "group"?: string; "initial_letter"?: string; "initial_letter_end"?: string; "initial_letter_start"?: string; "initial_letter_strict"?: unknown[]; "item"?: unknown[]; "master_brand"?: unknown[]; "media_set"?: string; "media_type"?: unknown[]; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "payment_type"?: unknown[]; "people"?: string; "pid"?: unknown[]; "promoted_for"?: string; "q"?: string; "signed"?: unknown[]; "tag_name"?: string; "tag_scheme"?: string; "tleo"?: unknown[]; "version"?: unknown[]; "embargoed"?: string }): Promise<any> {
    return this._request("GET", "/programmes", { params });
  }

  /** Discover metadata for content promotions */
  listPromotions(params: { "mixin"?: unknown[]; "context"?: string; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "pid"?: unknown[]; "promoted_by"?: unknown[]; "promoted_for"?: unknown[]; "q"?: string; "status"?: unknown[] }): Promise<any> {
    return this._request("GET", "/promotions", { params });
  }

  /** Build schedules and find metadata for TV and radio broadcasts and webcasts */
  listSchedules(params: { "sort"?: string; "sort_direction"?: string; "mixin"?: unknown[]; "authority"?: unknown[]; "descendants_of"?: unknown[]; "end_from"?: string; "end_to"?: string; "format"?: unknown[]; "genre"?: unknown[]; "group"?: string; "id"?: unknown[]; "id_type"?: unknown[]; "item"?: unknown[]; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "people"?: string; "pid"?: unknown[]; "q"?: string; "repeat"?: boolean; "schedule_day"?: string; "schedule_day_from"?: string; "schedule_day_to"?: string; "service_master_brand"?: unknown[]; "sid"?: unknown[]; "start_from"?: string; "start_to"?: string; "version"?: unknown[] }): Promise<any> {
    return this._request("GET", "/schedules", { params });
  }

  /** Get Schema definition */
  getXSD(): Promise<any> {
    return this._request("GET", "/schema", {});
  }

  /** Information about the linear services used for broadcast transmissions */
  listServices(params: { "end_from"?: string; "end_to"?: string; "mid"?: unknown[]; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "q"?: string; "service_type"?: unknown[]; "sid"?: unknown[]; "start_from"?: string; "start_to"?: string }): Promise<any> {
    return this._request("GET", "/services", { params });
  }

  /** Get raw brand */
  getRawBrand(params: { "pid": string }): Promise<any> {
    return this._request("GET", "/v1/brands/{pid}", { params });
  }

  /** Get raw brand franchise */
  getRawBrandFranchises(params: { "pid": string }): Promise<any> {
    return this._request("GET", "/v1/brands/{pid}/franchises/", { params });
  }

  /** Get raw episode */
  getRawEpisode(params: { "pid": string }): Promise<any> {
    return this._request("GET", "/v1/episodes/{pid}", { params });
  }

  /** Get raw ancestors */
  getRawAncestors(params: { "pid": string }): Promise<any> {
    return this._request("GET", "/v1/episodes/{pid}/ancestors/", { params });
  }

  /** Get raw formats */
  getRawFormats(params: { "pid": string }): Promise<any> {
    return this._request("GET", "/v1/episodes/{pid}/formats/", { params });
  }

  /** Get raw genre groups */
  getRawGenreGroups(params: { "pid": string }): Promise<any> {
    return this._request("GET", "/v1/episodes/{pid}/genre_groups/", { params });
  }

  /** Get raw image */
  getRawImage(params: { "pid": string }): Promise<any> {
    return this._request("GET", "/v1/images/{pid}", { params });
  }

  /** Get raw masterbrand */
  getRawMasterbrand(params: { "mbid": string }): Promise<any> {
    return this._request("GET", "/v1/master_brands/{mbid}", { params });
  }

  /** Get raw promotion */
  getRawPromotion(params: { "pid": string }): Promise<any> {
    return this._request("GET", "/v1/promotions/{pid}", { params });
  }

  /** Metadata on editorial programme versions: original, signed, audio-described, etc */
  listVersions(params: { "availability"?: unknown[]; "descendants_of"?: unknown[]; "media_set"?: unknown[]; "page"?: number; "page_size"?: number; "partner_id"?: unknown[]; "partner_pid"?: unknown[]; "payment_type"?: unknown[]; "pid"?: unknown[]; "embargoed"?: string }): Promise<any> {
    return this._request("GET", "/versions", { params });
  }
}

export default BBCNitroAPI;