/**
 * Publisher-facing ad event names.
 * Duplicated here so consumers do not take a dependency on `@socialvibe/shared`.
 */
export declare const TruexAdEventType: {
  /**
   * This event fires when the TrueX UI is being constructed and added to the web page.
   */
  readonly AD_STARTED: 'adStarted',

  /**
   * This event fires once the TrueX UI is loaded and visible, i.e., all image assets are loaded, etc.
   * This is useful if the host app is implementing its own loading indicator UX (i.e., its own loading spinner),
   * and needs to know when the ad UI is actually ready to be disabled without delays.
   */
  readonly AD_DISPLAYED: 'adDisplayed',

  /**
   * This is a `terminal event`. This event will fire when the TrueX unit is finished with its activities.
   * at this point, the app should resume playback and remove the TrueX ad renderer from its UI
   *
   * Here are some examples where adCompleted will fire:
   * - The user opts for normal video ads (not TrueX)
   * - The choice card timeout runs out
   * - The user completes the TrueX ad unit
   * - After a "skip card" has been shown to a user for its duration
   */
  readonly AD_COMPLETED: 'adCompleted',

  /**
   * This is a `terminal event`. This event will fire when the TrueX unit has encountered an unrecoverable error.
   * The host app code should handle this the same way as an `adCompleted` event.
   * - resume playback and remove the TrueX ad renderer from its UI.
   */
  readonly AD_ERROR: 'adError',

  /**
   * This event will fire when the user has earned a credit with TrueX.
   * The host app code should notate that this event has fired but should not take any further action.
   * Upon receiving a terminal event:
   * - if `adFreePod` was fired, the app should skip all remaining ads in the current slot.
   * - if `adFreePod` was not fired, the app should resume playback without skipping any ads,
   *   so the user receives a normal video ad payload.
   */
  readonly AD_FREE_POD: 'adFreePod',

  /**
   * This event fires when the TrueX ad request is successfully completed and the ad is ready to be presented.
   * The host app may use this event to facilitate a loading screen for pre-rolls or to facilitate an ad request timeout for mid-rolls.
   *
   * **For example**: init is called for the pre-roll slot, and the host app code shows a loading indicator while waiting for adFetchCompleted.
   * Then, either the event is received (and the app can call start) or a specific timeout is reached
   * (and the app can discard the TruexAdRenderer instance and resume playback of normal video ads).
   *
   * **Another example**: init is called well before a mid-roll slot to give the renderer a chance to preload its ad.
   * - If `adFetchCompleted` is received before the mid-roll slot is encountered, then the app can call start to immediately present the TrueX ad.
   * - If not, the app can wait for a specific timeout (if not already reached, in case the user has seeked to activate the mid-roll)
   *   before removing the TruexAdRenderer instance and resuming playback with normal video ads.
   */
  readonly AD_FETCH_COMPLETED: 'adFetchCompleted',

  /**
   * This is a `terminal` event. This event will fire when the TrueX unit has determined it has no ads available to show the current user.
   * The host app code should handle this the same way as an `adCompleted` event
   * - resume playback and remove the TrueX ad renderer from its UI.
   */
  readonly NO_ADS_AVAILABLE: 'noAdsAvailable',

  /**
   * This event will fire if the user selects to interact with the TrueX interactive ad.
   * **Note** that this event may be fired multiple times if a user opts in to the TrueX interactive ad and subsequently backs out.
   */
  readonly OPT_IN: 'optIn',

  /**
   * This event will fire if the user opts for a normal video ad experience.
   */
  readonly OPT_OUT: 'optOut',

  /**
   * This event will fire anytime a "skip card" is shown to a user as a result of completing a `TrueX Sponsored Stream`
   * interactive in an earlier pre-roll.
   */
  readonly SKIP_CARD_SHOWN: 'skipCardShown',

  /**
   * This event will fire when a user backs out of the TrueX interactive ad unit after having opted in.
   * This would be achieved by tapping the "Yes" link to the "Are you sure you want to go back and
   * choose a different "ad experience" prompt inside the TrueX interactive ad.
   * The user will be subsequently taken back to the Choice Card (with the countdown timer reset to full).
   *
   * **Note** that after a `userCancel`, the user can opt-in and engage with an interactive ad again,
   * so more optIn or optOut events may then be fired.
   */
  readonly USER_CANCEL: 'userCancel',

  /**
   * This is a `terminal event`, and is only enabled when the `supportsUserCancelStream` property is set to true when triggering the init action.
   * When enabled, the renderer will fire this event when the user intends to exit the stream entirely.
   * The app, at this point, should treat this the same way it would handle any other "exit" action from within the stream,
   * - in most cases this will result in the user being returned to an episode/series detail page.
   *
   * If this event is not enabled, the renderer will emit an adCompleted event instead.
   */
  readonly USER_CANCEL_STREAM: 'userCancelStream',

  /**
   * This event fires for TrueX ad creatives that their own fallback extended videos built in.
   *
   * From the host app's perspective, nothing more is needed to be done, and the regular ad event flow processing will occur,
   * just with the extended ad content instead.
   */
  readonly XTENDED_VIEW_STARTED: 'xtendedViewStarted',

  /**
   * On mobile platforms, ad units with links to external websites fire this event when the user clicks on the web site link,
   * e.g., typically via a "Learn More" link.
   * On mobile platforms, navigating to an external website means leaving the current application.
   * As such, this ad event is used to communicate the user's intention, and the host app needs to open the external web page as appropriate for the platform.
   * e.g., for Android, intent is raised to open the web page in the phone's browser.
   */
  readonly POPUP_WEBSITE: 'popupWebsite'
};

/** Choice card finished constructing and was added to the page. */
type TruexAdStartedEvent = { type: typeof TruexAdEventType.AD_STARTED };

/** Choice card is visible and its image assets have loaded. */
type TruexAdDisplayedEvent = { type: typeof TruexAdEventType.AD_DISPLAYED };

/** User earned a TrueX credit. Wait for a terminal event before resuming playback. */
type TruexAdFreePodEvent = { type: typeof TruexAdEventType.AD_FREE_POD };

/** Ad request finished and the unit is ready for `start`. */
type TruexAdFetchCompletedEvent = { type: typeof TruexAdEventType.AD_FETCH_COMPLETED };

/** No TrueX ad is available for this user. Terminal. */
type TruexNoAdsAvailableEvent = { type: typeof TruexAdEventType.NO_ADS_AVAILABLE };

/** User backed out of an engagement and returned to the choice card. */
type TruexUserCancelEvent = { type: typeof TruexAdEventType.USER_CANCEL };

/** User chose to leave the stream. Terminal. Requires `supportsUserCancelStream`. */
type TruexUserCancelStreamEvent = { type: typeof TruexAdEventType.USER_CANCEL_STREAM };

/** Creative started its built-in extended fallback video. */
type TruexXTendedViewStartedEvent = { type: typeof TruexAdEventType.XTENDED_VIEW_STARTED };

/** A skip card is on screen after an earlier sponsored-stream completion. */
type TruexSkipCardShownEvent = { type: typeof TruexAdEventType.SKIP_CARD_SHOWN };

/** TrueX unit is finished. Terminal. */
type TruexAdCompletedEvent = {
  type: typeof TruexAdEventType.AD_COMPLETED,

  /** Seconds the user spent in the TrueX unit. */
  timeSpent: number
};

/** Renderer hit an unrecoverable error. Terminal. */
type TruexAdErrorEvent = {
  type: typeof TruexAdEventType.AD_ERROR,

  /**
   * A description of the cause of the error.
   */
  errorMessage: string
};

/** User chose the interactive ad. */
type TruexOptInEvent = {
  type: typeof TruexAdEventType.OPT_IN,

  /**
   * This will be set to `true` if this was actively selected by the user,
   * `false` if the user simply allowed the choice card countdown to expire.
   */
  userInitiated: boolean
};

/** User chose a normal video ad, or the choice-card countdown expired. */
type TruexOptOutEvent = {
  type: typeof TruexAdEventType.OPT_OUT,

  /**
   * This will be set to `true` if this was actively selected by the user,
   * `false` if the user simply allowed the choice card countdown to expire.
   */
  userInitiated: boolean
};

/** User clicked an external site link. The host app opens `url`. */
type TruexPopupWebsiteEvent = {
  type: typeof TruexAdEventType.POPUP_WEBSITE,

  /**
   * Indicates the web page to navigate to.
   */
  url: string
};

/** An ad event passed to a `subscribe` callback. */
export type TruexAdEvent =
  | TruexAdStartedEvent
  | TruexAdDisplayedEvent
  | TruexAdCompletedEvent
  | TruexAdErrorEvent
  | TruexAdFreePodEvent
  | TruexAdFetchCompletedEvent
  | TruexNoAdsAvailableEvent
  | TruexOptInEvent
  | TruexOptOutEvent
  | TruexSkipCardShownEvent
  | TruexUserCancelEvent
  | TruexUserCancelStreamEvent
  | TruexXTendedViewStartedEvent
  | TruexPopupWebsiteEvent
;

/** `event.type` string for a publisher-facing ad event. */
export type TruexAdEventName = TruexAdEvent['type'];

/** Callback invoked for every ad event. */
export type TruexAdEventHandler = (event: TruexAdEvent) => unknown;

/** Optional settings for a renderer instance. Forwarded to the choice card. */
export type TruexAdRendererOptions = {
  /**
   * if true (default), a loading indicator is shown while the
   * choice card display elements are loading, i.e., while waiting for image assets to load, etc.
   */
  showLoadingSpinner?: boolean,

  /**
   * The id used for user ad tracking.
   *   If omitted, the existing network_user_id in the vast config url is used.
   *   If that is missing, the fallbackAdvertisingId is used.
   */
  userAdvertisingId?: string,

  /**
   * The id used for user ad tracking when no explicit user ad id is
   * provided or available from the platform. By default, it is a randomly generated UUID. Specifying allows one to
   * control if limited ad tracking is truly random per ad, or else shared across multiple TAR ad sessions.
   */
  fallbackAdvertisingId?: string,

  /**
   * if true, enables the userCancelStream event when the user presses `back` on the remote
   * from the choice card. Defaults to false, which means back actions cause optOut/adCompleted events instead.
   */
  supportsUserCancelStream?: boolean,

  /**
   * When set, overrides the platform's auto-detected history-API back handling.
   * Omit it to keep that default. `false` handles the raw back key
   * (LG apps with `disableBackHistoryAPI: true`). `true` waits for `popstate`.
   * Forwarded to the choice card on init.
   */
  useHistoryBackActions?: boolean,

  /**
   * url to load the choice card script from.
   */
  choiceCardUrlOverride?: string,

  /**
   * url to load the container for the engagement ad.
   */
  containerUrlOverride?: string,

  /**
   * override value to set opt out tracking
   */
  optOutTrackingEnabled?: boolean,

  /**
   * set the application id/ package name for tracking
   */
  appId?: string,

  /**
   * set the host integration name and version for tracking.
   * Can be an array to track multiple integrations (e.g., TAR Android using TAR Web Bridge).
   */
  useIntegration?: IntegrationMetadata | IntegrationMetadata[],

  /**
   * if true and running on the PS4, all ad videos are played via the WebMAF API,
   * to work around any WebMAF load failures due to the creation of HTML5 Video elements.
   */
  useWebMAF?: boolean,

  /**
   * provides a map keyed by input actions that describe the key codes
   * to use to map key events to input actions. This will override the platform's built-in support and is intended
   * to allow the use of the TruexAdRenderer on unsupported platforms where the key mapping has not been
   * implemented yet in TAR itself. E.g.
   *
   * @example
   * {
   *     select: [32, 13], // space or enter
   *     back: [27, 8, 127], // esc or backspace or del
   *     moveUp: 38,
   *     moveDown: 40,
   *     moveLeft: 37,
   *     moveRight: 39
   * }
   */
  keyMapOverrides?: {
    /** Key codes that activate the focused control. */
    select?: number | number[];
    /** Key codes for the back action. */
    back?: number | number[];
    /** Key codes that move focus up. */
    moveUp?: number | number[];
    /** Key codes that move focus down. */
    moveDown?: number | number[];
    /** Key codes that move focus left. */
    moveLeft?: number | number[];
    /** Key codes that move focus right. */
    moveRight?: number | number[];
  },

  /** Called for each tracking event the renderer records. */
  trackingObserver?: (category: string, name: string, value: any) => void,

  /** When set, overrides the renderer's own check for whether this device can run TAR. */
  deviceCanRunTAR?: boolean,
}

/** Shared renderer behavior. Public subclasses fix `mode`. */
declare class TruexAdRendererBase<T extends TruexAdRendererMode> {
  /**
   * @param parameters Vast config URL, `{ vast_config_url }`, or a vast config object.
   * @param options Optional renderer settings.
   * @param mode Platform flags. The public subclasses set this.
   */
  constructor(
    parameters: string | TruexAdRendererParameters | TruexAdRequestResponse,
    options?: TruexAdRendererOptions,
    mode?: Partial<T>
  );

  /** TAR build version. */
  readonly version: string;

  /** Platform flags fixed by the subclass: CTV, desktop, or mobile. */
  readonly mode: T;

  /**
   * @deprecated Use {@link TruexAdEventType}.
   */
  readonly adEvents: TruexAdEvents;

  /**
   * Requests the vast config from the TrueX ad server.
   * Resolves with that config and fires `adFetchCompleted`.
   */
  init(): Promise<TruexAdRequestResponse>;

  /**
   * Shows the choice card. Call after {@link TruexAdRendererBase.init}, or pass a vast config directly.
   * @param vastConfig Defaults to the config from `init`.
   * @param parentElement Element that receives the ad overlay. Defaults to `document.documentElement`.
   */
  start(vastConfig?: TruexAdRequestResponse, parentElement?: HTMLElement): Promise<HTMLElement>;

  /** Closes the ad. Call this if the host app must reset while an ad is on screen. */
  stop(): void;

  /** Pauses ad video and countdowns while the host app is suspended. */
  pause(): void;

  /** Resumes a paused ad. */
  resume(): void;

  /** Listen for every ad event. */
  subscribe(callback: TruexAdEventHandler): void;

  /**
   * Listen for one ad event. The callback argument is narrowed to that event.
   */
  subscribe<K extends TruexAdEventName>(
    type: K,
    callback: (event: Extract<TruexAdEvent, { type: K }>) => unknown
  ): void;

  /** Stop a callback that was registered for every ad event. */
  unsubscribe(callback: TruexAdEventHandler): void;

  /** Stop a callback that was registered for one ad event. */
  unsubscribe<K extends TruexAdEventName>(
    type: K,
    callback: (event: Extract<TruexAdEvent, { type: K }>) => unknown
  ): void;

  /** Sets choice-card voiceover volume, from 0 to 100. */
  setAdVolume(volume: number): void;

  /**
   * @deprecated Use {@link TruexAdEventType}.
   */
  static adEvents: TruexAdEvents;
}

/** Renderer for connected-TV web views. Ad tracking is recorded as CTV. */
export class TruexAdRendererCTV extends TruexAdRendererBase<{ ctv: true, desktop: false, mobile: false }> {
  /**
   * @param parameters Vast config URL, `{ vast_config_url }`, or a vast config object.
   * @param options Optional renderer settings.
   */
  constructor(
    parameters: TruexAdRendererParameters,
    options?: TruexAdRendererOptions,
  );
}

/** Renderer for desktop web. Ad tracking is recorded as desktop. */
export class TruexAdRendererDesktop extends TruexAdRendererBase<{ ctv: false, desktop: true, mobile: false }> {
  /**
   * @param parameters Vast config URL, `{ vast_config_url }`, or a vast config object.
   * @param options Optional renderer settings.
   */
  constructor(
    parameters: TruexAdRendererParameters,
    options?: TruexAdRendererOptions,
  );
}

/** Renderer for mobile web. Ad tracking is recorded as mobile. */
export class TruexAdRendererMobile extends TruexAdRendererBase<{ ctv: false, desktop: false, mobile: true }> {
  /**
   * @param parameters Vast config URL, `{ vast_config_url }`, or a vast config object.
   * @param options Optional renderer settings.
   */
  constructor(
    parameters: TruexAdRendererParameters,
    options?: TruexAdRendererOptions,
  );
}

/**
 * @deprecated Use {@link TruexAdRendererCTV}. This name is the CTV renderer.
 */
export const TruexAdRenderer: typeof TruexAdRendererCTV;

/** Same value as {@link TruexAdRenderer}. */
export default TruexAdRenderer;

/** Fields that identify which vast config to download. */
export type TruexAdRequestParameters = {
  /** Network user id. Omitted values fall through to the advertising-id options. */
  user_id?: string;

  /** URL the renderer calls to download the vast config. */
  vast_config_url: string;
};

/** Constructor input: a vast config, a request descriptor, or a vast config URL. */
export type TruexAdRendererParameters = TruexAdRequestResponse | TruexAdRequestParameters | string;

/** Which client surface this renderer instance targets. */
export type TruexAdRendererMode = {
  /** Connected TV. */
  ctv: boolean,

  /** Desktop web. */
  desktop: boolean,

  /** Mobile web. */
  mobile: boolean
};

/**
 * @deprecated Use {@link TruexAdEventType}.
 * Legacy map of publisher-facing event names.
 */
export type TruexAdEvents = {
  adStarted: 'adStarted',
  adDisplayed: 'adDisplayed',
  adCompleted: 'adCompleted',
  adError: 'adError',
  noAdsAvailable: 'noAdsAvailable',
  adFreePod: 'adFreePod',
  adFetchCompleted: 'adFetchCompleted',
  userCancelStream: 'userCancelStream',
  optIn: 'optIn',
  optOut: 'optOut',
  skipCardShown: 'skipCardShown',
  userCancel: 'userCancel',
  xtendedViewStarted: 'xtendedViewStarted',
  popupWebsite: "popupWebsite"
};

/** Host integration name and version, sent as tracking. */
export type IntegrationMetadata = {
  /** Integration name, for example `TAR Android`. */
  name: string,

  /** Integration version. */
  version: string,
};

/** Vast config returned by the ad server and by `init`. */
export type TruexAdRequestResponse = {
  /** Creative tag kind. `skip` selects the skip card. */
  tag_type: string,

  /** Viewer identity from the ad response. */
  user: {
    /** Network user id. */
    id: string,
  };

  /** Placement this request was served for. */
  placement: {
    /** Placement id. */
    id: string;

    /** Partner id. */
    partner_id: string;

    /** Placement hash used in the vast config URL path. */
    identifier_hash: string;
  },

  /** Ad request id. */
  request_id: string,

  /** Session id for this vast response. */
  vast_session_id: string,

  /** TrueX service base URL. */
  service_url: string,

  /** Default URL of the choice-card script. */
  card_creative_url: string,

  /** Extra arguments for the choice card. */
  card_creative_args: Record<string, string | boolean | number | object>,

  /** Choice-card variants. More than one enables an A/B pick. */
  card_configurations: TruexAdRequestCardConfiguration[],

  /** Engagement ads available for this response. */
  ads: TruexAdRequestFilledAd[],

  /** Fallback extended-view ads. */
  xtended_view_fill: TruexAdRequestFilledAd[],
};

/** One filled engagement or extended-view ad. */
export type TruexAdRequestFilledAd = {
  /** Ad id. */
  id: string,

  /** Container URL for this ad. */
  window_url: string,
};

/** One choice-card variant in an A/B set. */
export type TruexAdRequestCardConfiguration = {
  /** Variant name, appended to tracking categories. */
  name: string,
};