@devix-technologies/react-gjirafa-vp-player 1.0.31-beta.3 → 1.0.31-beta.6

package/dist/index.d.ts

@@ -1,12 +1,86 @@
 import { CurrentVideoData as CurrentVideoData_2 } from '../../../../../../../src/types';
 import { DetailedHTMLProps } from 'react';
+import { ForwardRefExoticComponent } from 'react';
 import { HTMLAttributes } from 'react';
-import { JSX } from 'react/jsx-runtime';
+import { RefAttributes } from 'react';
 import { RefObject } from 'react';
 import { StyledComponent } from '@emotion/styled';
 import { Theme } from '@emotion/react';
 import { VPPlayerInstance as VPPlayerInstance_2 } from '../../../../../../../src/interfaces';
 import { VPPlayerProps as VPPlayerProps_2 } from '../../../../../../../src/interfaces';
+import { VPPlayerRef as VPPlayerRef_2 } from '../../../../../../../src/interfaces';
+
+/**
+ * Ad announcement configuration
+ */
+export declare interface AdAnnouncementConfig {
+    state: boolean;
+    timeBeforeAd: number;
+}
+
+/**
+ * Ad break configuration
+ */
+export declare interface AdBreak {
+    adTagUrl: string[];
+    breakType: "preroll" | "midroll" | "postroll";
+    breakTimingType: "time" | "percentage" | "playlist";
+    breakTimingValue: number;
+}
+
+/**
+ * Ad function configuration
+ */
+export declare interface AdFunction {
+    isDynamicKey: boolean;
+    isDynamicValue: boolean;
+    key: string;
+    order: number;
+    value: string;
+}
+
+/**
+ * Advertising configuration
+ */
+export declare interface AdsConfig {
+    skipAd?: AdSkipConfig;
+    vmap?: string;
+    VPAIDmode?: string;
+    enableProgrammability?: boolean;
+    functions?: AdFunction[];
+    bidding?: boolean;
+    afterMidrollBacktrack?: AfterMidrollBacktrack;
+    adBreaks?: AdBreak[];
+    bidders?: BidderConfig[];
+}
+
+/**
+ * Ad skip configuration
+ */
+export declare interface AdSkipConfig {
+    state: boolean;
+    skipFrom: number;
+}
+
+/**
+ * Ads localization
+ */
+export declare interface AdsLang {
+    ad?: string;
+    skip?: string;
+    skipIn?: string;
+    visit?: string;
+    info?: string;
+    simultaneousAds?: string;
+}
+
+/**
+ * After midroll backtrack configuration
+ */
+export declare interface AfterMidrollBacktrack {
+    state: boolean;
+    seconds: number;
+}
 
 /**
  * Appends the divId query parameter to a script URL.
@@ -21,6 +95,118 @@ import { VPPlayerProps as VPPlayerProps_2 } from '../../../../../../../src/inter
  */
 export declare const appendDivIdToUrl: (url: string, divId: string) => string;
 
+/**
+ * Autopause on viewable configuration
+ */
+export declare interface AutopauseOnViewableConfig {
+    state: boolean;
+    percentageViewable?: number;
+}
+
+/**
+ * Autoplay toggle skin
+ */
+export declare interface AutoplaySkin {
+    autoplayOn?: string;
+    autoplayOff?: string;
+}
+
+/**
+ * Autostart on load configuration
+ */
+export declare interface AutostartOnLoadConfig {
+    state: boolean;
+    onMobile?: boolean;
+    onData?: boolean;
+}
+
+/**
+ * Autostart on viewable configuration
+ */
+export declare interface AutostartOnViewableConfig {
+    state: boolean;
+    onMobile?: boolean;
+    onData?: boolean;
+    percentageViewable?: number;
+}
+
+/**
+ * Bidder configuration
+ */
+export declare interface BidderConfig {
+    name: string;
+    params: Record<string, string>;
+}
+
+/**
+ * Control bar skin configuration
+ */
+export declare interface ControlBarSkin {
+    background?: string;
+    text?: string;
+    icons?: IconsSkin;
+    timeslider?: TimesliderSkin;
+    volume?: VolumeSkin;
+    timesliderOnAd?: TimesliderSkin;
+}
+
+/**
+ * Controls visibility configuration
+ */
+export declare interface ControlsConfig {
+    theaterButton?: boolean;
+    settingsButton?: boolean;
+    chromecastButton?: boolean;
+    nextButton?: boolean;
+    fullscreenButton?: boolean;
+    airplayButton?: boolean;
+    bigPlayButton?: boolean;
+    pictureInPictureButton?: boolean;
+    relatedButton?: boolean;
+    volumeButton?: boolean;
+    shareButton?: boolean;
+    subtitlesButton?: boolean;
+    showCaptions?: boolean;
+    audioOnlyButton?: boolean;
+    rewindButton?: boolean;
+    forwardButton?: boolean;
+    chaptersButton?: boolean;
+    showHelperButton?: boolean | null;
+    helperButtonImage?: string;
+    showLiveIcon?: boolean | null;
+    delayLiveVideosTime?: number;
+    delayLiveVideos?: boolean | null;
+    showAutoPlay?: boolean | null;
+    showQualities?: boolean | null;
+}
+
+/**
+ * Controls localization
+ */
+export declare interface ControlsLang {
+    play?: string;
+    pause?: string;
+    next?: string;
+    replay?: string;
+    volume?: string;
+    mute?: string;
+    unmute?: string;
+    settings?: string;
+    theater?: string;
+    fullscreen?: string;
+    chromecast?: string;
+    airplay?: string;
+    pictureInPicture?: string;
+    related?: string;
+    skipIntro?: string;
+    skipAd?: string;
+    adAnnouncement?: string;
+    playlistTitle?: string;
+    upNext?: string;
+    live?: string;
+    continueAfterPause?: string;
+}
+
 /**
  * Represents data about the currently playing video.
  * Used in onVideoStarted callback.
@@ -46,6 +232,20 @@ export declare interface CurrentVideoData {
     description?: string;
 }
 
+/**
+ * VP Player Configuration Types
+ *
+ * Fully typed configuration based on VP Player documentation.
+ * @see {@link https://vp.gjirafa.tech/documentation/docs/web-player/setup-the-player/full-configuration}
+ * @see {@link https://vp.gjirafa.tech/documentation/docs/vertical-player/setup-the-player/configration}
+ */
+/**
+ * Deep partial utility type - makes all nested properties optional
+ */
+export declare type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+
 /**
  * Event callback refs interface for internal use
  * Prevents stale closures in event handlers
@@ -68,6 +268,28 @@ export declare interface EventCallbackRefs {
     onProgress20s?: (seconds: number) => void;
 }
 
+/**
+ * Float (picture-in-picture) configuration
+ */
+export declare interface FloatConfig {
+    state: boolean;
+    onMobile?: boolean;
+    position?: "TOP_LEFT" | "TOP_RIGHT" | "BOTTOM_LEFT" | "BOTTOM_RIGHT";
+    dismissible?: boolean;
+    requiresInteraction?: boolean;
+    toVideoThreshold?: number;
+    toFloatThreshold?: number;
+    style?: FloatStyleConfig;
+}
+
+/**
+ * Float style configuration
+ */
+export declare interface FloatStyleConfig {
+    width: number;
+    border?: string;
+}
+
 /**
  * Generates a full player DOM element ID based on provided playerId and videoId.
  * Falls back to "default" if playerId is not provided.
@@ -115,14 +337,74 @@ export declare const getPlayerScriptUrl: (playerVersion: string) => string;
 export declare const getVerticalPlayerScriptUrl: (scriptId: string) => string;
 
 /**
- * Manual playlist configuration
- * Used when you want to provide your own videos array instead of using GTech admin playlists
+ * Icons skin configuration
  */
-export declare interface ManualPlaylistConfig {
-    /** Array of videos to play */
-    videos: PlaylistVideoItem[];
-    /** Starting video index (0-based) */
-    startIndex?: number;
+export declare interface IconsSkin {
+    default?: string;
+    hover?: string;
+}
+
+/**
+ * Full localization configuration
+ */
+export declare interface LangConfig {
+    locale?: string;
+    controls?: ControlsLang;
+    settings?: SettingsLang;
+    ads?: AdsLang;
+}
+
+/**
+ * Logo configuration
+ */
+export declare interface LogoConfig {
+    state: boolean;
+    file?: string;
+    position?: "TOP_LEFT" | "TOP_RIGHT" | "BOTTOM_LEFT" | "BOTTOM_RIGHT";
+    defaultOpacity?: number;
+    inactiveOpacity?: number;
+    onClickURL?: string;
+}
+
+/**
+ * Menu background skin
+ */
+export declare interface MenuBackgroundSkin {
+    default?: string;
+    hover?: string;
+}
+
+/**
+ * Menu links skin
+ */
+export declare interface MenuLinksSkin {
+    default?: string;
+    hover?: string;
+}
+
+/**
+ * Menus skin configuration
+ */
+export declare interface MenusSkin {
+    background?: MenuBackgroundSkin;
+    links?: MenuLinksSkin;
+    autoplay?: AutoplaySkin;
+}
+
+/**
+ * Next video skin configuration
+ */
+export declare interface NextVideoSkin {
+    background?: string;
+    text?: string;
+    timeslider?: {
+        rail?: string;
+        progress?: string;
+    };
+    icons?: {
+        play?: PlayIconSkin;
+        close?: string;
+    };
 }
 
 /**
@@ -217,6 +499,36 @@ export declare interface PlayerObject {
     progress?: number;
 }
 
+/**
+ * Player settings configuration (the `config` object in VP Player)
+ */
+export declare interface PlayerSettingsConfig {
+    configId?: string;
+    size?: SizeConfig;
+    adAnnouncement?: AdAnnouncementConfig;
+    autoplay?: boolean;
+    autostartOnLoad?: AutostartOnLoadConfig;
+    autostartOnViewable?: AutostartOnViewableConfig;
+    autopauseOnViewable?: AutopauseOnViewableConfig;
+    pauseOtherVideos?: boolean;
+    focusOnAutostart?: boolean;
+    showRelatedOnPause?: ShowRelatedOnPauseConfig;
+    playbackRates?: number[];
+    volume?: number;
+    muted?: boolean;
+    loop?: boolean;
+    casting?: boolean;
+    debug?: boolean;
+    skipAmount?: number;
+    adsRequireInteraction?: boolean;
+    float?: FloatConfig;
+    controls?: ControlsConfig;
+    logo?: LogoConfig;
+    socialMedia?: unknown[];
+    lang?: LangConfig;
+    skin?: SkinConfig;
+}
+
 /**
  * Tracking metadata for analytics (available in v1.0.23+)
  */
@@ -243,6 +555,14 @@ as?: React.ElementType;
 className?: string;
 }, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 
+/**
+ * Play icon skin
+ */
+export declare interface PlayIconSkin {
+    default?: string;
+    hover?: string;
+}
+
 /**
  * API response structure for fetching playlist data.
  *
@@ -252,6 +572,47 @@ export declare interface PlaylistApiResponse {
     result: PlaylistItem[];
 }
 
+/**
+ * Playlist arrows skin
+ */
+export declare interface PlaylistArrowsSkin {
+    active?: string;
+    inactive?: string;
+}
+
+/**
+ * Playlist card duration skin
+ */
+export declare interface PlaylistCardDurationSkin {
+    text?: string;
+    background?: string;
+}
+
+/**
+ * Playlist card skin
+ */
+export declare interface PlaylistCardSkin {
+    background?: string;
+    title?: string;
+    duration?: PlaylistCardDurationSkin;
+    icons?: {
+        play?: PlayIconSkin;
+    };
+}
+
+/**
+ * Playlist configuration
+ */
+export declare interface PlaylistConfig {
+    state: boolean;
+    playlistId: string;
+    playlistVideoIndex: number;
+    highlightCurrentVideo?: boolean;
+    algorithm?: string;
+    title?: string;
+    videos: PlaylistVideoConfig[];
+}
+
 /**
  * Represents an item in a video playlist.
  *
@@ -272,35 +633,99 @@ export declare interface PlaylistItem {
 }
 
 /**
- * Video item for manual playlist
+ * Playlist skin configuration
+ */
+export declare interface PlaylistSkin {
+    background?: string;
+    text?: string;
+    icons?: {
+        arrows?: PlaylistArrowsSkin;
+        close?: string;
+    };
+    card?: PlaylistCardSkin;
+}
+
+/**
+ * Playlist video item in config
  */
-export declare interface PlaylistVideoItem {
-    /** Unique video identifier */
+export declare interface PlaylistVideoConfig {
     videoId: string;
-    /** Video title */
     title: string;
-    /** Video file URL (mp4, m3u8, etc.) */
     file: string;
-    /** Alternative: HLS URL */
-    hlsUrl?: string;
-    /** Thumbnail image URL */
     thumbnailUrl?: string;
-    /** Alternative: Thumbnail URL */
-    thumbnail?: string;
-    /** Video duration in seconds */
     duration?: number;
 }
 
+/**
+ * Settings localization
+ */
+export declare interface SettingsLang {
+    quality?: string;
+    subtitles?: string;
+    autoplay?: string;
+    playbackRate?: string;
+    auto?: string;
+    off?: string;
+    normal?: string;
+    share?: string;
+}
+
+/**
+ * Show related on pause configuration
+ */
+export declare interface ShowRelatedOnPauseConfig {
+    state: boolean;
+    onMobile?: boolean;
+    from?: number;
+}
+
+/**
+ * Size configuration
+ */
+export declare interface SizeConfig {
+    sizeType: "RESPONSIVE" | "FIXED";
+    aspectRatio?: "16:9" | "9:16" | "4:3" | "1:1";
+    width?: number;
+    height?: number;
+}
+
+/**
+ * Full skin configuration
+ */
+export declare interface SkinConfig {
+    controlBar?: ControlBarSkin;
+    menus?: MenusSkin;
+    nextVideo?: NextVideoSkin;
+    playlist?: PlaylistSkin;
+}
+
+/**
+ * Skip intro configuration
+ */
+export declare interface SkipIntroConfig {
+    state: boolean;
+    skipFrom: number;
+    skipTo: number;
+}
+
+/**
+ * Timeslider skin configuration
+ */
+export declare interface TimesliderSkin {
+    progress?: string;
+    rail?: string;
+    buffer?: string | null;
+    dragger?: string;
+}
+
 /**
  * VP Player logic hook
  *
  * Supports two modes:
  * 1. **Auto-init mode** (default): Load managed script that auto-initializes with GTech admin config
- * 2. **Manual playlist mode**: Build config and call setup() with custom videos array
- *
- * The manual playlist mode is required for vertical player when supplying your own videos.
+ * 2. **Config override mode**: Fetch config, merge user overrides, and call setup()
  */
-export declare const useVPPlayerLogic: ({ scriptId, videoId, scriptUrl, projectId, playlist, playerId, isVertical, isReels, onReady, onPlay, onPause, onResume, onComplete, onError, onVideoStarted, onTimeUpdate, onQuartile25, onQuartile50, onQuartile75, onNext, onPrevious, onProgress10s, onProgress20s, }: VPPlayerProps_2) => {
+export declare const useVPPlayerLogic: ({ scriptId, videoId, scriptUrl, projectId, config, playerId, isVertical, isReels, onReady, onPlay, onPause, onResume, onComplete, onError, onVideoStarted, onTimeUpdate, onQuartile25, onQuartile50, onQuartile75, onNext, onPrevious, onProgress10s, onProgress20s, }: VPPlayerProps_2) => {
     playerRef: RefObject<HTMLDivElement | null>;
     playerInstanceRef: RefObject<VPPlayerInstance_2 | null>;
     isScriptLoaded: boolean;
@@ -345,6 +770,33 @@ export declare interface VideoApiResponse {
     };
 }
 
+/**
+ * Video configuration
+ */
+export declare interface VideoConfig {
+    videoId?: string;
+    assetId?: string;
+    fpsCertificateUrl?: string;
+    widevineLicenseUrl?: string;
+    related?: string;
+    file?: string;
+    title?: string;
+    duration?: number;
+    description?: string;
+    live?: boolean;
+    liveType?: string;
+    thumbnail?: string;
+    filmstrip?: string;
+    tracks?: unknown[];
+    startTime?: number;
+    skipIntro?: SkipIntroConfig;
+    flags?: VideoFlag[];
+    playlist?: PlaylistConfig;
+    advertising?: boolean;
+    adId?: string;
+    ads?: AdsConfig;
+}
+
 /**
  * Result structure returned by the video data fetching logic.
  *
@@ -357,17 +809,34 @@ export declare interface VideoDataResult {
     error: string | null;
 }
 
+/**
+ * Video flag/tag
+ */
+export declare interface VideoFlag {
+    id: number;
+    name: string;
+}
+
+/**
+ * Volume skin configuration
+ */
+export declare interface VolumeSkin {
+    dragger?: string;
+    progress?: string;
+    rail?: string;
+    notifier?: string;
+}
+
 /**
  * Base URL for the VP Player host.
  */
 export declare const VP_PLAYER_BASE_URL = "https://host.vpplayer.tech";
 
 /**
- * VP Player Component (v2.0.0)
+ * VP Player Component
  *
  * A thin React wrapper for the GTech VP Player.
- * All configuration is managed through the GTech admin panel -
- * this wrapper just provides a DOM container, loads the script, and exposes events.
+ * Configuration can be managed through the GTech admin panel or via the `config` prop.
  *
  * ## Basic Usage
  *
@@ -386,23 +855,42 @@ export declare const VP_PLAYER_BASE_URL = "https://host.vpplayer.tech";
  * />
  * ```
  *
- * ## Manual Playlist Mode (Vertical Player)
+ * ## Using the ref for imperative control
  *
- * For vertical player with custom videos array:
+ * ```tsx
+ * const playerRef = useRef<VPPlayerRef>(null);
+ *
+ * <VPPlayer
+ *   ref={playerRef}
+ *   scriptId="ptkzurnx"
+ *   videoId="vjsobqhe"
+ * />
+ *
+ * // Later:
+ * playerRef.current?.seek(60);
+ * playerRef.current?.play();
+ * console.log(playerRef.current?.getPosition());
+ * ```
+ *
+ * ## Config Override Mode
+ *
+ * Override the fetched configuration with custom settings:
  *
  * ```tsx
  * <VPPlayer
- *   scriptId="rbqcdwzlg"
- *   projectId="agmipnzb"
- *   isVertical={true}
- *   playlist={{
- *     videos: [
- *       { videoId: "1", title: "Video 1", file: "https://...mp4", thumbnailUrl: "...", duration: 120 },
- *       { videoId: "2", title: "Video 2", file: "https://...mp4", thumbnailUrl: "...", duration: 150 },
- *     ],
- *     startIndex: 0,
+ *   scriptId="ptkzurnx"
+ *   videoId="vjsobqhe"
+ *   config={{
+ *     config: {
+ *       muted: true,
+ *       autoplay: true,
+ *       skin: {
+ *         controlBar: {
+ *           background: 'rgba(0,0,0,0.8)'
+ *         }
+ *       }
+ *     }
  *   }}
- *   onNext={() => console.log('Next video')}
  * />
  * ```
  *
@@ -422,42 +910,27 @@ export declare const VP_PLAYER_BASE_URL = "https://host.vpplayer.tech";
  *
  * @param props - VPPlayer configuration props
  */
-export declare const VPPlayer: ({ scriptId, videoId, scriptUrl, projectId, playlist, playerId, isVertical, isReels, thumbnailUrl, onClose, className, hiddenClasses, onReady, onPlay, onPause, onResume, onComplete, onError, onVideoStarted, onTimeUpdate, onQuartile25, onQuartile50, onQuartile75, onNext, onPrevious, onProgress10s, onProgress20s, }: VPPlayerProps_2) => JSX.Element;
+export declare const VPPlayer: ForwardRefExoticComponent<VPPlayerProps_2 & RefAttributes<VPPlayerRef_2>>;
 
 /**
- * VP Player Configuration Types (v2.0.0)
- *
- * NOTE: In v2.0.0, configuration is managed through the GTech admin panel.
- * These types are kept for reference only - the React wrapper does NOT
- * pass configuration to the SDK. The managed script auto-initializes
- * with all settings from the admin panel.
- *
- * @see {@link https://vp.gjirafa.tech/documentation/docs/web-player/setup-the-player/configuration}
- */
-/**
- * Advertising configuration interface (reference only)
- * Configured through GTech admin panel
+ * Full VP Player configuration
+ * This is the root configuration object passed to vpPlayer().setup()
  */
-export declare interface VPPlayerAdsConfig {
-    skipAd?: {
-        state: boolean;
-        skipFrom: number;
-    };
-    vmap?: string;
-    VPAIDmode?: string;
-    enableProgrammability?: boolean;
-    adBreaks?: Array<{
-        adTagUrl: string[];
-        breakType?: "preroll" | "midroll" | "postroll";
-        breakTimingType?: "time" | "percentage" | "playlist";
-        breakTimingValue?: number;
-    }>;
+export declare interface VPPlayerConfig {
+    projectId?: string;
+    biskoId?: string;
+    video?: VideoConfig;
+    config?: PlayerSettingsConfig;
 }
 
 /**
  * Interface representing an instance of the VP Player.
- * Based on VP Player API Reference: https://vp.gjirafa.tech/documentation/docs/web-player/api-reference
- * And VP Vertical Player API Reference: https://vp.gjirafa.tech/documentation/docs/vertical-player/api-reference
+ *
+ * NOTE: The VP Player SDK does not ship with TypeScript types.
+ * This is our own type definition based on the official API documentation.
+ *
+ * @see https://vp.gjirafa.tech/documentation/docs/web-player/api-reference
+ * @see https://vp.gjirafa.tech/documentation/docs/vertical-player/api-reference
  *
  * @interface VPPlayerInstance
  */
@@ -476,8 +949,6 @@ export declare interface VPPlayerInstance {
     exitFullScreen?: () => void;
     enterFullscreen?: () => void;
     exitFullscreen?: () => void;
-    enterPictureInPicture?: () => void;
-    exitPictureInPicture?: () => void;
     togglePlay?: () => void;
     toggleMute?: () => void;
     isMuted?: () => boolean;
@@ -519,10 +990,10 @@ export declare interface VPPlayerInstance {
 }
 
 /**
- * Simplified props interface for VPPlayer v2.0.0
+ * Simplified props interface for VPPlayer
  *
- * The wrapper is now a thin bridge to the GTech JS player.
- * All configuration is managed through the GTech admin panel.
+ * The wrapper is a thin bridge to the GTech JS player.
+ * Configuration can be managed through the GTech admin panel or via the `config` prop.
  *
  * @interface VPPlayerProps
  */
@@ -543,34 +1014,42 @@ export declare interface VPPlayerProps {
      */
     scriptUrl?: string;
     /**
-     * GTech project ID (required for manual playlist mode)
+     * GTech project ID
+     * Convenience prop that gets merged into config.projectId
+     * Can also be set directly in the config prop
      */
     projectId?: string;
     /**
-     * Manual playlist configuration - provide your own videos array.
-     * When provided, the wrapper will call setup() with the built config
-     * instead of relying on auto-initialization.
+     * Player configuration overrides.
+     * When provided, the wrapper will:
+     * 1. Try to fetch the JSON config from VP Player API
+     * 2. Deep merge your overrides into the fetched config
+     * 3. Call setup() with the merged configuration
      *
-     * IMPORTANT: This is required for vertical player when you want to
-     * supply your own videos (not using GTech admin playlists).
+     * If fetch fails, your config will be used directly.
      *
      * @example
      * ```tsx
      * <VPPlayer
-     *   scriptId="rbqcdwzlg"
-     *   projectId="agmipnzb"
-     *   isVertical={true}
-     *   playlist={{
-     *     videos: [
-     *       { videoId: "1", title: "Video 1", file: "https://...mp4", thumbnailUrl: "...", duration: 120 },
-     *       { videoId: "2", title: "Video 2", file: "https://...mp4", thumbnailUrl: "...", duration: 150 },
-     *     ],
-     *     startIndex: 0,
+     *   scriptId="ptkzurnx"
+     *   videoId="vjsobqhe"
+     *   config={{
+     *     config: {
+     *       muted: true,
+     *       autoplay: true,
+     *       skin: {
+     *         controlBar: {
+     *           background: 'rgba(0,0,0,0.8)'
+     *         }
+     *       }
+     *     }
      *   }}
      * />
      * ```
+     *
+     * @see {@link https://vp.gjirafa.tech/documentation/docs/web-player/setup-the-player/full-configuration}
      */
-    playlist?: ManualPlaylistConfig;
+    config?: DeepPartial<VPPlayerConfig>;
     /**
      * Custom container ID for the player div
      * Auto-generated if not provided
@@ -669,4 +1148,52 @@ export declare interface VPPlayerProps {
     onProgress20s?: (seconds: number) => void;
 }
 
+/**
+ * Interface for the imperative handle exposed by VPPlayer via ref.
+ * Use this to call player methods from parent components.
+ *
+ * @example
+ * ```tsx
+ * const playerRef = useRef<VPPlayerRef>(null);
+ *
+ * <VPPlayer ref={playerRef} scriptId="..." videoId="..." />
+ *
+ * // Later:
+ * playerRef.current?.seek(60);
+ * playerRef.current?.play();
+ * ```
+ */
+export declare interface VPPlayerRef {
+    play: () => void;
+    pause: () => void;
+    seek: (position: number) => void;
+    forward: () => void;
+    rewind: () => void;
+    replay: () => void;
+    mute: () => void;
+    unmute: () => void;
+    togglePlay: () => void;
+    toggleMute: () => void;
+    enterFullScreen: () => void;
+    exitFullScreen: () => void;
+    getPosition: () => number | null;
+    getDuration: () => number | null;
+    getVolume: () => number | null;
+    setVolume: (volume: number) => void;
+    isMuted: () => boolean;
+    isPlaying: () => boolean;
+    isPaused: () => boolean;
+    isFullscreen: () => boolean;
+}
+
+/**
+ * VP Vertical Player configuration
+ * Similar to VPPlayerConfig but optimized for vertical video
+ */
+export declare interface VPVerticalPlayerConfig {
+    projectId?: string;
+    video?: VideoConfig;
+    config?: PlayerSettingsConfig;
+}
+
 export { }