@flowplayer/spins 0.5.0 → 0.6.0

package/dist/types.d.ts

@@ -1,17 +1,67 @@
 import { Config } from '@flowplayer/player';
-import { PlayerIMAConfig } from '@flowplayer/player/plugins/ads';
+import { PlayerIMAConfig, AdBreakCompletedEventDetail, AdCompletedEventDetail, AdBasicInfo, AdPlaybackErrorEventDetail, AdPrerollFinishedEventDetail, AdProgressEventDetail, AdRequestErrorEventDetail, AdResumedEventDetail, AdStartedEventDetail, AdTearDownEventDetail, AdSkippedEventDetail, AdMutedEventDetail, AdVolumeChangedEventDetail, AdsPlayer } from '@flowplayer/player/plugins/ads';
 import { ConsentConfig } from '@flowplayer/player/plugins/consent';
 import { ShareConfig } from '@flowplayer/player/plugins/share';
 import { SubtitlesConfig } from '@flowplayer/player/plugins/subtitles';
 
-/**
- * Emitted when a new spin is created.
- */
-declare const SPIN_CREATED = "spin:created";
-/**
- * Emitted when a different spin enters the viewport.
- */
-declare const SPIN_IN_VIEWPORT = "spin:viewport";
+declare const spinEvents: {
+    /**
+     * Emitted when a new spin is created.
+     */
+    readonly SPIN_CREATED: "spin:created";
+    /**
+     * Emitted when a different spin enters the viewport.
+     */
+    readonly SPIN_IN_VIEWPORT: "spin:viewport";
+};
+declare const mediaEvents: {
+    /** Fired when the browser can start playing the media without stopping for buffering. */
+    readonly CAN_PLAY: "canplay";
+    /** Fired when the playback position changes (e.g. during playback or scrubbing). */
+    readonly TIME_UPDATE: "timeupdate";
+    /** Fired when playback is actively progressing after being paused or buffering. */
+    readonly PLAYING: "playing";
+    /** Fired when playback is delayed while the next frame is being loaded (buffering). */
+    readonly WAITING: "waiting";
+    /** Fired when playback has been paused by the user or programmatically. */
+    readonly PAUSE: "pause";
+    /** Fired when playback has been started or resumed. */
+    readonly PLAY: "play";
+    /** Fired when the user begins seeking to a new playback position. */
+    readonly SEEKING: "seeking";
+    /** Fired when playback has reached the end of the media resource. */
+    readonly ENDED: "ended";
+};
+declare const adEvents: {
+    /** Fired when the ad teardown/cleanup process occurs. */
+    readonly AD_TEARDOWN: "ad-teardown";
+    /** Fired when a single ad has finished playing. */
+    readonly AD_COMPLETED: "ad-completed";
+    /** Fired when an ad request fails due to a network or server error. */
+    readonly AD_REQUEST_ERROR: "ad-request-error";
+    /** Fired when an ad was received and starts playing. */
+    readonly AD_STARTED: "ad-started";
+    /** Internal or general ad error event. */
+    readonly AD_ERROR: "ad-error";
+    /** Fired when an ad request succeeds but the ad fails to play. */
+    readonly AD_PLAYBACK_ERROR: "ad-playback-error";
+    /** Fired when an ad break (a group of ads) has completed. */
+    readonly AD_BREAK_COMPLETED: "ad-break-completed";
+    /** Fired periodically as the ad progresses during playback. */
+    readonly AD_PROGRESS: "ad-progress";
+    /** Fired when an ad is paused. */
+    readonly AD_PAUSED: "ad-paused";
+    /** Fired when an ad resumes after being paused. */
+    readonly AD_RESUMED: "ad-resumed";
+    /** Fired when preroll playback (and possible postroll) is finished. */
+    readonly AD_PREROLL_FINSIHED: "ad-preroll-finished";
+    /** Fired when the skip button is clicked and the ad is skipped. */
+    readonly AD_SKIPPED: "ad-skipped";
+    /** Fired when the ad has been muted. */
+    readonly AD_MUTED: "ad-muted";
+    /** Fired when the ad volume changes during playback. */
+    readonly AD_VOLUME_CHANGED: "ad-volume-changed";
+};
 
 /**
  * All supported plugin identifiers for configuring the player.
@@ -107,32 +157,136 @@ type SpinEventData = {
      */
     index: number;
 };
+type MediaEventData = {
+    /**
+     * the index of the spin
+     */
+    spinIndex: number;
+    /**
+     * the length of the video in seconds
+     */
+    duration?: number;
+    /**
+     * the current playback time in seconds
+     */
+    currentTime: number;
+    /**
+     * the mediaId
+     */
+    mediaId?: string;
+    /**
+     * the full url of the media that is being played
+     */
+    url: string;
+};
+type AdEventData<K extends AdEvent> = {
+    spinIndex: number;
+} & AdEventsDetailMap[K];
+type SpinsAdPlayerConfig = {
+    poster?: Config["poster"];
+    /**
+     * Consent plugin configuration. A bitmask property where the possible values can be found from `Consent.tracking` and `Consent.storage` enumerations.
+     * @see https://developer.wowza.com/docs/wowza-flowplayer/plugins/consent/
+     */
+    consent?: ConsentConfig["consent"];
+    /**
+     * Sets the language of your preference.
+     * @default english
+     * @see https://developer.wowza.com/docs/wowza-flowplayer/player/translations/#configure-translations
+     */
+    lang?: Config["lang"];
+    /**
+     * Your token.
+     * @see https://developer.wowza.com/docs/wowza-flowplayer/player/configure/#token-configuration
+     */
+    token: string;
+    /**
+     * Ads configuration
+     * @see https://developer.wowza.com/docs/wowza-flowplayer/plugins/advertising/#ima-object-configuration
+     */
+    ima: PlayerIMAConfig;
+};
+type SpinEvent = (typeof spinEvents)[keyof typeof spinEvents];
+type MediaEvent = (typeof mediaEvents)[keyof typeof mediaEvents];
+type AdEvent = (typeof adEvents)[keyof typeof adEvents];
+type PlayerEvent = MediaEvent | AdEvent;
+type PlayerEventsDetailMap = {
+    [K in MediaEvent]: MediaEventData;
+} & {
+    [K in AdEvent]: AdEventData<K>;
+};
+type AdEventsDetailMap = {
+    [adEvents.AD_BREAK_COMPLETED]: AdBreakCompletedEventDetail;
+    [adEvents.AD_COMPLETED]: AdCompletedEventDetail;
+    [adEvents.AD_ERROR]: AdBasicInfo;
+    [adEvents.AD_PAUSED]: AdBasicInfo;
+    [adEvents.AD_PLAYBACK_ERROR]: AdPlaybackErrorEventDetail;
+    [adEvents.AD_PREROLL_FINSIHED]: AdPrerollFinishedEventDetail;
+    [adEvents.AD_PROGRESS]: AdProgressEventDetail;
+    [adEvents.AD_REQUEST_ERROR]: AdRequestErrorEventDetail;
+    [adEvents.AD_RESUMED]: AdResumedEventDetail;
+    [adEvents.AD_STARTED]: AdStartedEventDetail;
+    [adEvents.AD_TEARDOWN]: AdTearDownEventDetail;
+    [adEvents.AD_SKIPPED]: AdSkippedEventDetail;
+    [adEvents.AD_MUTED]: AdMutedEventDetail;
+    [adEvents.AD_VOLUME_CHANGED]: AdVolumeChangedEventDetail;
+};
 interface SpinsContainer extends HTMLElement {
     /**
-     * Adds a listener for the SpinsEvents["SPIN_CREATED"] event
+     * Adds a listener for any player event (media or ad).
      */
-    on(e: typeof SPIN_CREATED, handler: (e: CustomEvent<SpinEventData>) => void, options?: boolean | AddEventListenerOptions): void;
+    onPlayerEvent<K extends PlayerEvent>(e: K, handler: (event: CustomEvent<PlayerEventsDetailMap[K]>) => void): void;
     /**
-     * Adds a listener for the SpinsEvents["SPIN_IN_VIEWPORT"] event.
+     * Adds a listener for a SpinEvent.
      */
-    on(e: typeof SPIN_IN_VIEWPORT, handler: (e: CustomEvent<SpinEventData>) => void, options?: boolean | AddEventListenerOptions): void;
+    on(e: SpinEvent, handler: (e: CustomEvent<SpinEventData>) => void, options?: boolean | AddEventListenerOptions): void;
     /**
-     * Removes a listener for the SpinsEvents["SPIN_IN_VIEWPORT"] event
+     * Removes a listener for a SpinEvent
      */
-    off(e: typeof SPIN_IN_VIEWPORT, handler: (e?: CustomEvent<SpinEventData>) => void): void;
+    off(e: SpinEvent, handler: (e?: CustomEvent<SpinEventData>) => void): void;
     /**
-     * Removes a listener for the SpinsEvents["SPIN_CREATED"] event
+     * Removes a listener for any player event (media or ad).
      */
-    off(e: typeof SPIN_CREATED, handler: (e?: CustomEvent<SpinEventData>) => void): void;
+    offPlayerEvent<K extends PlayerEvent>(e: K, handler: (event: CustomEvent<PlayerEventsDetailMap[K]>) => void): void;
     /**
      * Add more spins dynamically.
      */
     addSpins(spins: SpinItem[]): void;
 }
-declare const events: {
-    SPIN_IN_VIEWPORT: typeof SPIN_IN_VIEWPORT;
-    SPIN_CREATED: typeof SPIN_CREATED;
-};
+
+interface SpinsAdPlayer extends HTMLElement {
+    /**
+     * The underlying ad player instance.
+     * Use this to listen to ad-related events directly.
+     *
+     * @see https://developer.wowza.com/docs/wowza-flowplayer/plugins/advertising/#listen-to-plugin-events
+     */
+    player: AdsPlayer;
+    /**
+     * Immediately terminates the component’s lifecycle by cleaning up
+     * all resources and removing it from the DOM.
+     *
+     * Use this when you want to stop playback and dispose of the component
+     * early, instead of letting it be removed automatically at the natural
+     * end of the ad lifecycle.
+     *
+     * Once destroyed, the instance should not be reused.
+     */
+    destroy(): void;
+    /**
+     * Requests and begins loading the ad into the player.
+     */
+    loadAd(): void;
+    /**
+     * Registers a callback to be executed immediately before the component
+     * is destroyed and removed from the DOM.
+     *
+     * The callback is guaranteed to be invoked only once, and after it
+     * runs the instance should be considered invalid — it must not be reused.
+     */
+    onBeforeDestroy(callback: () => void): void;
+}
 declare function createSpins(config: SpinsConfig): SpinsContainer;
+declare function createAdPlayer(config: SpinsAdPlayerConfig): SpinsAdPlayer | void;
 
-export { type SpinEventData, type SpinItem, type SpinsConfig, type SpinsContainer, createSpins, events };
+export { type AdEvent, type AdEventData, type AdEventsDetailMap, type MediaEvent, type MediaEventData, type PlayerEvent, type PlayerEventsDetailMap, type SpinEvent, type SpinEventData, type SpinItem, type SpinsAdPlayer, type SpinsAdPlayerConfig, type SpinsConfig, type SpinsContainer, adEvents, createAdPlayer, createSpins, mediaEvents, spinEvents };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flowplayer/spins",
   "module": "dist/index.js",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "types": "./dist/types.d.ts",
   "exports": {