@firebolt-js/discovery-sdk/dist/lib/firebolt-discovery.d.ts

The Firebolt Discovery JS SDK

/*
 * Copyright 2021 Comcast Cable Communications Management, LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

export module Settings {
  type LogLevel = 'WARN' | 'INFO' | 'DEBUG' | 'ERROR'
  function setLogLevel(logLevel: LogLevel): void
  function getLogLevel(): LogLevel
}

export module Log {
  function info(...args: any[]): void
  function debug(...args: any[]): void
  function error(...args: any[]): void
  function warn(...args: any[]): void
}

export module Events {
  function listen(...args: any[]): Promise<number>
  function once(...args: any[]): Promise<number>
  function clear(...args: any[]): boolean
}

export module Content {
  type Event = 'userInterest'

  // Types

  /**
   *
   */
  enum InterestType {
    INTEREST = 'interest',
    DISINTEREST = 'disinterest',
  }

  /**
   *
   */
  enum InterestReason {
    PLAYLIST = 'playlist',
    REACTION = 'reaction',
    RECORDING = 'recording',
  }

  /**
   * The offering type of the WayToWatch.
   */
  enum OfferingType {
    FREE = 'free',
    SUBSCRIBE = 'subscribe',
    BUY = 'buy',
    RENT = 'rent',
  }

  /**
   *
   */
  enum AudioProfile {
    STEREO = 'stereo',
    DOLBY_DIGITAL_5_1 = 'dolbyDigital5.1',
    DOLBY_DIGITAL_5_1_PLUS = 'dolbyDigital5.1+',
    DOLBY_ATMOS = 'dolbyAtmos',
  }

  /**
   * In the case of a music `entityType`, specifies the type of music entity.
   */
  enum MusicType {
    SONG = 'song',
    ALBUM = 'album',
  }

  /**
     * The ContentIdentifiers object is how the app identifies an entity or asset to
the Firebolt platform. These ids are used to look up metadata and deep link into
the app.

Apps do not need to provide all ids. They only need to provide the minimum
required to target a playable stream or an entity detail screen via a deep link.
If an id isn't needed to get to those pages, it doesn't need to be included.
     */
  type ContentIdentifiers = {
    assetId?: string // Identifies a particular playable asset. For example, the HD version of a particular movie separate from the UHD version.
    entityId?: string // Identifies an entity, such as a Movie, TV Series or TV Episode.
    seasonId?: string // The TV Season for a TV Episode.
    seriesId?: string // The TV Series for a TV Episode or TV Season.
    appContentData?: string // App-specific content identifiers.
  }

  /**
   *
   */
  type MusicEntity = {
    entityType: 'music'
    musicType: MusicType // In the case of a music `entityType`, specifies the type of music entity.
    entityId: string
  }

  /**
   *
   */
  type ChannelEntity = {
    entityType: 'channel'
    channelType: 'streaming' | 'overTheAir'
    entityId: string // ID of the channel, in the target App's scope.
    appContentData?: string
  }

  /**
   *
   */
  type UntypedEntity = {
    entityId: string
    assetId?: string
    appContentData?: string
  }

  /**
   * A Firebolt compliant representation of a Playlist entity.
   */
  type PlaylistEntity = {
    entityType: 'playlist'
    entityId: string
    assetId?: string
    appContentData?: string
  }

  /**
   * A Firebolt compliant representation of a Movie entity.
   */
  type MovieEntity = {
    entityType: 'program'
    programType: 'movie'
    entityId: string
    assetId?: string
    appContentData?: string
  }

  /**
     * A ContentRating represents an age or content based of an entity. Supported rating schemes and associated types are below.

## United States

`US-Movie` (MPAA):

Ratings: `NR`, `G`, `PG`, `PG13`, `R`, `NC17`

Advisories: `AT`, `BN`, `SL`, `SS`, `N`, `V`

`US-TV` (Vchip):

Ratings: `TVY`, `TVY7`, `TVG`, `TVPG`, `TV14`, `TVMA`

Advisories: `FV`, `D`, `L`, `S`, `V`

## Canada

`CA-Movie` (OFRB):

Ratings: `G`, `PG`, `14A`, `18A`, `R`, `E`

`CA-TV` (AGVOT)

Ratings: `E`, `C`, `C8`, `G`, `PG`, `14+`, `18+`

Advisories: `C`, `C8`, `G`, `PG`, `14+`, `18+`

`CA-Movie-Fr` (Canadian French language movies):

Ratings: `G`, `8+`, `13+`, `16+`, `18+`

`CA-TV-Fr` (Canadian French language TV):

Ratings: `G`, `8+`, `13+`, `16+`, `18+`

     */
  type ContentRating = {
    scheme:
      | 'CA-Movie'
      | 'CA-TV'
      | 'CA-Movie-Fr'
      | 'CA-TV-Fr'
      | 'US-Movie'
      | 'US-TV' // The rating scheme.
    rating: string // The content rating.
    advisories?: string[] // Optional list of subratings or content advisories.
  }

  /**
     * A WayToWatch describes a way to watch a video program. It may describe a single
streamable asset or a set of streamable assets. For example, an app provider may
describe HD, SD, and UHD assets as individual WayToWatch objects or rolled into
a single WayToWatch.

If the WayToWatch represents a single streamable asset, the provided
ContentIdentifiers must be sufficient to play back the specific asset when sent
via a playback intent or deep link. If the WayToWatch represents multiple
streamable assets, the provided ContentIdentifiers must be sufficient to
playback one of the assets represented with no user action. In this scenario,
the app SHOULD choose the best asset for the user based on their device and
settings. The ContentIdentifiers MUST also be sufficient for navigating the user
to the appropriate entity or detail screen via an entity intent.

The app should set the `entitled` property to indicate if the user can watch, or
not watch, the asset without making a purchase. If the entitlement is known to
expire at a certain time (e.g., a rental), the app should also provide the
`entitledExpires` property. If the entitlement is not expired, the UI will use
the `entitled` property to display watchable assets to the user, adjust how
assets are presented to the user, and how intents into the app are generated.
For example, the the Aggregated Experience could render a "Watch" button for an
entitled asset versus a "Subscribe" button for an non-entitled asset.

The app should set the `offeringType` to define how the content may be
authorized. The UI will use this to adjust how content is presented to the user.

A single WayToWatch cannot represent streamable assets available via multiple
purchase paths. If, for example, an asset has both Buy, Rent and Subscription
availability, the three different entitlement paths MUST be represented as
multiple WayToWatch objects.

`price` should be populated for WayToWatch objects with `buy` or `rent`
`offeringType`. If the WayToWatch represents a set of assets with various price
points, the `price` provided must be the lowest available price.
     */
  type WayToWatch = {
    identifiers: ContentIdentifiers // The ContentIdentifiers object is how the app identifies an entity or asset to
    expires?: string // Time when the WayToWatch is no longer available.
    entitled?: boolean // Specify if the user is entitled to watch the entity.
    entitledExpires?: string // Time when the entity is no longer entitled.
    offeringType?: OfferingType // The offering type of the WayToWatch.
    hasAds?: boolean // True if the streamable asset contains ads.
    price?: number // For "buy" and "rent" WayToWatch, the price to buy or rent in the user's preferred currency.
    videoQuality?: 'SD' | 'HD' | 'UHD'[] // List of the video qualities available via the WayToWatch.
    audioProfile: AudioProfile[] // List of the audio types available via the WayToWatch.
    audioLanguages?: string[] // List of audio track languages available on the WayToWatch. The first is considered the primary language. Languages are expressed as ISO 639 1/2 codes.
    closedCaptions?: string[] // List of languages for which closed captions are available on the WayToWatch. Languages are expressed as ISO 639 1/2 codes.
    subtitles?: string[] // List of languages for which subtitles are available on the WayToWatch. Languages are expressed as ISO 639 1/2 codes.
    audioDescriptions?: string[] // List of languages for which audio descriptions (DVD) as available on the WayToWatch. Languages are expressed as ISO 639 1/2 codes.
  }

  /**
   * A Firebolt compliant representation of a TV Episode entity.
   */
  type TVEpisodeEntity = {
    entityType: 'program'
    programType: 'episode'
    entityId: string
    seriesId: string
    seasonId: string
    assetId?: string
    appContentData?: string
  }

  /**
   * A Firebolt compliant representation of a TV Season entity.
   */
  type TVSeasonEntity = {
    entityType: 'program'
    programType: 'season'
    entityId: string
    seriesId: string
    assetId?: string
    appContentData?: string
  }

  /**
   * A Firebolt compliant representation of a TV Series entity.
   */
  type TVSeriesEntity = {
    entityType: 'program'
    programType: 'series'
    entityId: string
    assetId?: string
    appContentData?: string
  }

  /**
   * A Firebolt compliant representation of the remaining program entity types.
   */
  type AdditionalEntity = {
    entityType: 'program'
    programType:
      | 'concert'
      | 'sportingEvent'
      | 'preview'
      | 'other'
      | 'advertisement'
      | 'musicVideo'
      | 'minisode'
      | 'extra'
    entityId: string
    assetId?: string
    appContentData?: string
  }

  /**
   *
   */
  type ProgramEntity =
    | MovieEntity
    | TVEpisodeEntity
    | TVSeasonEntity
    | TVSeriesEntity
    | AdditionalEntity

  /**
   *
   */
  type Entity =
    | ProgramEntity
    | MusicEntity
    | ChannelEntity
    | UntypedEntity
    | PlaylistEntity

  /**
   *
   */
  type Metadata = {
    title?: string // Title of the entity.
    synopsis?: string // Short description of the entity.
    seasonNumber?: number // For TV seasons, the season number. For TV episodes, the season that the episode belongs to.
    seasonCount?: number // For TV series, seasons, and episodes, the total number of seasons.
    episodeNumber?: number // For TV episodes, the episode number.
    episodeCount?: number // For TV seasons and episodes, the total number of episodes in the current season.
    releaseDate?: string // The date that the program or entity was released or first aired.
    contentRatings?: ContentRating[] // A ContentRating represents an age or content based of an entity. Supported rating schemes and associated types are below.
  }

  /**
   *
   */
  type EntityDetails = {
    identifiers: Entity
    info?: Metadata
    waysToWatch?: WayToWatch[] // A WayToWatch describes a way to watch a video program. It may describe a single
  }

  /**
   *
   */
  type InterestResult = {
    appId: string
    entity: EntityDetails
  }

  /**
   *
   */
  type InterestEvent = {
    appId: string
    type: InterestType
    reason: InterestReason
    entity: EntityDetails
  }

  /**
   * Turn off all listeners previously registered from this module.
   */
  function clear(): boolean

  /**
   * Clear a specific listen by the listener ID.
   *
   * @param {number} id The id of the listener to clear
   */
  function clear(id: number): boolean

  /**
   * Listen to all events dispatched by this module.
   *
   * @param {Function} callback
   */
  function listen(
    callback: (event: string, data: object) => void,
  ): Promise<number>
  /**
   * Listen for the first of any and all events dispatched by this module.
   *
   * @param {Function} callback
   */
  function once(
    callback: (event: string, data: object) => void,
  ): Promise<number>
  /**
   * Provide information about the entity currently displayed or selected on the screen.
   *
   * @param {'userInterest'} event
   * @param {Function} callback
   */
  function listen(
    event: 'userInterest',
    callback: (data: InterestEvent) => void,
  ): Promise<number>

  /**
   * Provide information about the entity currently displayed or selected on the screen.
   * When using `once` the callback method will only fire once, and then disconnect your listener
   *
   * @param {'userInterest'} event
   * @param {Function} callback
   */
  function once(
    event: 'userInterest',
    callback: (data: InterestEvent) => void,
  ): Promise<number>

  /**
   * Provide information about the entity currently displayed or selected on the screen.
   *
   * @param {InterestType} type
   * @param {InterestReason} reason
   */
  function requestUserInterest(
    type: InterestType,
    reason: InterestReason,
  ): Promise<InterestResult>
}