@lumra/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,240 @@
+import React$1 from 'react';
+import { Plugin, PlayerInstance, PlayerOptions } from '@lumra/core';
+import { LumraPurchaseOption, ChapterMark } from '@lumra/ui';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface LumraMediaInfo {
+    title?: string;
+    creator?: {
+        name: string;
+        avatarUrl?: string;
+    };
+}
+interface LumraTrack {
+    /** Path or URL to the .vtt file */
+    src: string;
+    kind: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+    /** BCP 47 language tag, e.g. "en", "es-419" */
+    srcLang: string;
+    label: string;
+    default?: boolean;
+}
+interface LumraPlayerPaywall {
+    /** Whether the current user is locked out of this content */
+    locked: boolean;
+    /** Called when the user clicks "Buy now" in the paywall overlay */
+    onUnlock: () => void | Promise<void>;
+    /** Multi-option mode: Buy / Rent / Custom — pricing comes from your platform API */
+    options?: LumraPurchaseOption[];
+    /** Override title shown in paywall overlay */
+    title?: string;
+    /** Override subtitle shown in paywall overlay */
+    subtitle?: string;
+    /** Custom paywall overlay component — defaults to the built-in PaywallOverlay */
+    overlay?: React$1.ComponentType<{
+        onUnlock: () => void;
+    }>;
+}
+interface LumraPlayerComponents {
+    /** @deprecated Pass `paywall` prop instead — it wires the preview gate automatically */
+    Paywall?: React$1.ComponentType<{
+        onUnlock: () => void;
+    }>;
+}
+interface LumraPlayerProps {
+    src?: string;
+    /** Poster image shown before the video loads */
+    poster?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    volume?: number;
+    loop?: boolean;
+    /**
+     * Paywall configuration. When provided:
+     * - Automatically registers `paywallGatePlugin` with `config.paywall.previewDuration`
+     * - Shows the paywall overlay after the gate fires
+     * - No manual plugin wiring needed in your component
+     */
+    paywall?: LumraPlayerPaywall;
+    /**
+     * Title + creator info displayed as an overlay at the top of the player.
+     * Data should come from your platform API, not hardcoded here.
+     */
+    mediaInfo?: LumraMediaInfo;
+    /**
+     * WebVTT subtitle / caption tracks.
+     * Maps directly to HTML <track> elements.
+     */
+    tracks?: LumraTrack[];
+    /**
+     * Chapter markers shown as dividers on the seek bar.
+     * Load from your platform API — e.g. `video.chapters` from your DB.
+     */
+    chapters?: ChapterMark[];
+    /**
+     * Normalized 0-1 heatmap values (one per seek-bar segment).
+     * Supply via heatmapPlugin's onData callback or directly from your API.
+     */
+    heatmapData?: number[];
+    /**
+     * Render only the <video> element with no built-in controls or overlays.
+     * Use when you want full UI control.
+     */
+    headless?: boolean;
+    /** Additional plugins (analytics, custom gates, etc.) */
+    plugins?: Plugin[];
+    /** @deprecated Use `paywall` prop for paywall overlay */
+    components?: LumraPlayerComponents;
+    className?: string;
+    style?: React$1.CSSProperties;
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onTimeUpdate?: (currentTime: number, duration: number) => void;
+    onError?: (code: number, message: string) => void;
+}
+declare const LumraPlayer: React$1.ForwardRefExoticComponent<LumraPlayerProps & React$1.RefAttributes<PlayerInstance>>;
+
+interface UsePlayerOptions extends Omit<PlayerOptions, 'target'> {
+}
+interface UsePlayerReturn {
+    player: PlayerInstance | null;
+    videoRef: React.RefObject<HTMLVideoElement>;
+    paused: boolean;
+    currentTime: number;
+    duration: number;
+    volume: number;
+    muted: boolean;
+}
+declare function usePlayer(options?: UsePlayerOptions): UsePlayerReturn;
+
+interface LumraTheme {
+    /** Progress bar fill + scrubber thumb colour (default: '#ffffff') */
+    accentColor?: string;
+    /** Icon + time display colour (default: '#ffffff') */
+    textColor?: string;
+    /** Controls bar background — any CSS value (default: black gradient) */
+    controlsBg?: string;
+    /** Player container border-radius (default: '0px') */
+    borderRadius?: string;
+}
+interface LumraControlsConfig {
+    /** Show play/pause button (default: true) */
+    play?: boolean;
+    /** Show seek bar (default: true) */
+    progress?: boolean;
+    /** Show volume control (default: true) */
+    volume?: boolean;
+    /** Show fullscreen button (default: true) */
+    fullscreen?: boolean;
+    /** Show Picture-in-Picture button (default: true) */
+    pip?: boolean;
+    /** Show current / duration timestamp (default: true) */
+    time?: boolean;
+    /** Hide toolbar after inactivity (default: true) */
+    autoHide?: boolean;
+    /** Milliseconds of inactivity before toolbar hides (default: 3000) */
+    autoHideDelay?: number;
+}
+interface LumraBehaviorConfig {
+    /** Disable right-click + nodownload attribute to discourage saving (default: false) */
+    blockDownload?: boolean;
+    autoplay?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+}
+interface LumraPaywallConfig {
+    /**
+     * Seconds of free preview before the gate fires and the paywall overlay appears.
+     * Controlled here so you never touch App.tsx — just change this number.
+     * (default: 5)
+     */
+    previewDuration?: number;
+}
+interface LumraAdConfig {
+    /**
+     * VAST 2.0 / 3.0 tag URL — the plugin fetches and parses the XML automatically.
+     * Supply either `vast` or `src`, not both.
+     */
+    vast?: string;
+    /** Direct video URL (MP4 / HLS) — bypasses VAST, used as a simple pre-baked ad */
+    src?: string;
+    /** Seconds of ad playback before the Skip button appears. 0 = not skippable. */
+    skipAfter?: number;
+    /** Override the click-through URL (ignored when VAST provides one) */
+    clickThroughUrl?: string;
+}
+interface LumraMidRollConfig extends LumraAdConfig {
+    /** Content timestamp (in seconds) at which this mid-roll fires */
+    at: number;
+}
+interface LumraAdsConfig {
+    /**
+     * Lumra Ads premium license key.
+     * Format: LUMRA-ADS-XXXXXXXX-XXXXXXXX
+     * Obtain a key at https://lumra.dev/premium
+     */
+    licenseKey: string;
+    /** Optional server endpoint to verify the license key */
+    verifyEndpoint?: string;
+    /** Ad that plays before the main content */
+    preRoll?: LumraAdConfig;
+    /** One or more ads that interrupt the main content at specific timestamps */
+    midRoll?: LumraMidRollConfig[];
+    /** Ad that plays after the main content ends */
+    postRoll?: LumraAdConfig;
+}
+interface LumraStorageConfig {
+    /**
+     * Base URL prepended to any relative `src` value.
+     * Swap between local dev and production CDN by changing this one line.
+     *
+     * @example
+     * // local dev
+     * baseUrl: 'http://localhost:9000/videos'
+     * // production
+     * baseUrl: 'https://your-cdn.com/videos'
+     */
+    baseUrl?: string;
+}
+interface LumraCloudConfig {
+    /**
+     * Called before every video load — return a signed or proxied URL.
+     * Works with AWS S3, Cloudflare R2 / Stream, Mux, Bunny CDN, etc.
+     *
+     * @example
+     * // AWS S3 presigned URL (via your own API)
+     * signUrl: async (src) => {
+     *   const res = await fetch(`/api/sign-url?src=${encodeURIComponent(src)}`)
+     *   const { url } = await res.json()
+     *   return url
+     * }
+     *
+     * @example
+     * // Cloudflare Stream signed URL
+     * signUrl: async (src) => {
+     *   const res = await fetch('/api/cf-sign', { method: 'POST', body: JSON.stringify({ src }) })
+     *   const { url } = await res.json()
+     *   return url
+     * }
+     */
+    signUrl?: (src: string) => Promise<string>;
+}
+interface LumraConfig {
+    theme?: LumraTheme;
+    controls?: LumraControlsConfig;
+    behavior?: LumraBehaviorConfig;
+    paywall?: LumraPaywallConfig;
+    ads?: LumraAdsConfig;
+    storage?: LumraStorageConfig;
+    cloud?: LumraCloudConfig;
+}
+/** Type-safe helper — returns the config unchanged but provides IDE autocomplete */
+declare function defineLumraConfig(config: LumraConfig): LumraConfig;
+declare function LumraConfigProvider({ config, children, }: {
+    config: LumraConfig;
+    children: React$1.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useLumraConfig(): LumraConfig;
+
+export { type LumraAdConfig, type LumraAdsConfig, type LumraBehaviorConfig, type LumraCloudConfig, type LumraConfig, LumraConfigProvider, type LumraControlsConfig, type LumraMediaInfo, type LumraMidRollConfig, type LumraPaywallConfig, LumraPlayer, type LumraPlayerComponents, type LumraPlayerPaywall, type LumraPlayerProps, type LumraStorageConfig, type LumraTheme, type LumraTrack, type UsePlayerOptions, type UsePlayerReturn, defineLumraConfig, useLumraConfig, usePlayer };

package/dist/index.d.ts

@@ -0,0 +1,240 @@
+import React$1 from 'react';
+import { Plugin, PlayerInstance, PlayerOptions } from '@lumra/core';
+import { LumraPurchaseOption, ChapterMark } from '@lumra/ui';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface LumraMediaInfo {
+    title?: string;
+    creator?: {
+        name: string;
+        avatarUrl?: string;
+    };
+}
+interface LumraTrack {
+    /** Path or URL to the .vtt file */
+    src: string;
+    kind: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+    /** BCP 47 language tag, e.g. "en", "es-419" */
+    srcLang: string;
+    label: string;
+    default?: boolean;
+}
+interface LumraPlayerPaywall {
+    /** Whether the current user is locked out of this content */
+    locked: boolean;
+    /** Called when the user clicks "Buy now" in the paywall overlay */
+    onUnlock: () => void | Promise<void>;
+    /** Multi-option mode: Buy / Rent / Custom — pricing comes from your platform API */
+    options?: LumraPurchaseOption[];
+    /** Override title shown in paywall overlay */
+    title?: string;
+    /** Override subtitle shown in paywall overlay */
+    subtitle?: string;
+    /** Custom paywall overlay component — defaults to the built-in PaywallOverlay */
+    overlay?: React$1.ComponentType<{
+        onUnlock: () => void;
+    }>;
+}
+interface LumraPlayerComponents {
+    /** @deprecated Pass `paywall` prop instead — it wires the preview gate automatically */
+    Paywall?: React$1.ComponentType<{
+        onUnlock: () => void;
+    }>;
+}
+interface LumraPlayerProps {
+    src?: string;
+    /** Poster image shown before the video loads */
+    poster?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    volume?: number;
+    loop?: boolean;
+    /**
+     * Paywall configuration. When provided:
+     * - Automatically registers `paywallGatePlugin` with `config.paywall.previewDuration`
+     * - Shows the paywall overlay after the gate fires
+     * - No manual plugin wiring needed in your component
+     */
+    paywall?: LumraPlayerPaywall;
+    /**
+     * Title + creator info displayed as an overlay at the top of the player.
+     * Data should come from your platform API, not hardcoded here.
+     */
+    mediaInfo?: LumraMediaInfo;
+    /**
+     * WebVTT subtitle / caption tracks.
+     * Maps directly to HTML <track> elements.
+     */
+    tracks?: LumraTrack[];
+    /**
+     * Chapter markers shown as dividers on the seek bar.
+     * Load from your platform API — e.g. `video.chapters` from your DB.
+     */
+    chapters?: ChapterMark[];
+    /**
+     * Normalized 0-1 heatmap values (one per seek-bar segment).
+     * Supply via heatmapPlugin's onData callback or directly from your API.
+     */
+    heatmapData?: number[];
+    /**
+     * Render only the <video> element with no built-in controls or overlays.
+     * Use when you want full UI control.
+     */
+    headless?: boolean;
+    /** Additional plugins (analytics, custom gates, etc.) */
+    plugins?: Plugin[];
+    /** @deprecated Use `paywall` prop for paywall overlay */
+    components?: LumraPlayerComponents;
+    className?: string;
+    style?: React$1.CSSProperties;
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onTimeUpdate?: (currentTime: number, duration: number) => void;
+    onError?: (code: number, message: string) => void;
+}
+declare const LumraPlayer: React$1.ForwardRefExoticComponent<LumraPlayerProps & React$1.RefAttributes<PlayerInstance>>;
+
+interface UsePlayerOptions extends Omit<PlayerOptions, 'target'> {
+}
+interface UsePlayerReturn {
+    player: PlayerInstance | null;
+    videoRef: React.RefObject<HTMLVideoElement>;
+    paused: boolean;
+    currentTime: number;
+    duration: number;
+    volume: number;
+    muted: boolean;
+}
+declare function usePlayer(options?: UsePlayerOptions): UsePlayerReturn;
+
+interface LumraTheme {
+    /** Progress bar fill + scrubber thumb colour (default: '#ffffff') */
+    accentColor?: string;
+    /** Icon + time display colour (default: '#ffffff') */
+    textColor?: string;
+    /** Controls bar background — any CSS value (default: black gradient) */
+    controlsBg?: string;
+    /** Player container border-radius (default: '0px') */
+    borderRadius?: string;
+}
+interface LumraControlsConfig {
+    /** Show play/pause button (default: true) */
+    play?: boolean;
+    /** Show seek bar (default: true) */
+    progress?: boolean;
+    /** Show volume control (default: true) */
+    volume?: boolean;
+    /** Show fullscreen button (default: true) */
+    fullscreen?: boolean;
+    /** Show Picture-in-Picture button (default: true) */
+    pip?: boolean;
+    /** Show current / duration timestamp (default: true) */
+    time?: boolean;
+    /** Hide toolbar after inactivity (default: true) */
+    autoHide?: boolean;
+    /** Milliseconds of inactivity before toolbar hides (default: 3000) */
+    autoHideDelay?: number;
+}
+interface LumraBehaviorConfig {
+    /** Disable right-click + nodownload attribute to discourage saving (default: false) */
+    blockDownload?: boolean;
+    autoplay?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+}
+interface LumraPaywallConfig {
+    /**
+     * Seconds of free preview before the gate fires and the paywall overlay appears.
+     * Controlled here so you never touch App.tsx — just change this number.
+     * (default: 5)
+     */
+    previewDuration?: number;
+}
+interface LumraAdConfig {
+    /**
+     * VAST 2.0 / 3.0 tag URL — the plugin fetches and parses the XML automatically.
+     * Supply either `vast` or `src`, not both.
+     */
+    vast?: string;
+    /** Direct video URL (MP4 / HLS) — bypasses VAST, used as a simple pre-baked ad */
+    src?: string;
+    /** Seconds of ad playback before the Skip button appears. 0 = not skippable. */
+    skipAfter?: number;
+    /** Override the click-through URL (ignored when VAST provides one) */
+    clickThroughUrl?: string;
+}
+interface LumraMidRollConfig extends LumraAdConfig {
+    /** Content timestamp (in seconds) at which this mid-roll fires */
+    at: number;
+}
+interface LumraAdsConfig {
+    /**
+     * Lumra Ads premium license key.
+     * Format: LUMRA-ADS-XXXXXXXX-XXXXXXXX
+     * Obtain a key at https://lumra.dev/premium
+     */
+    licenseKey: string;
+    /** Optional server endpoint to verify the license key */
+    verifyEndpoint?: string;
+    /** Ad that plays before the main content */
+    preRoll?: LumraAdConfig;
+    /** One or more ads that interrupt the main content at specific timestamps */
+    midRoll?: LumraMidRollConfig[];
+    /** Ad that plays after the main content ends */
+    postRoll?: LumraAdConfig;
+}
+interface LumraStorageConfig {
+    /**
+     * Base URL prepended to any relative `src` value.
+     * Swap between local dev and production CDN by changing this one line.
+     *
+     * @example
+     * // local dev
+     * baseUrl: 'http://localhost:9000/videos'
+     * // production
+     * baseUrl: 'https://your-cdn.com/videos'
+     */
+    baseUrl?: string;
+}
+interface LumraCloudConfig {
+    /**
+     * Called before every video load — return a signed or proxied URL.
+     * Works with AWS S3, Cloudflare R2 / Stream, Mux, Bunny CDN, etc.
+     *
+     * @example
+     * // AWS S3 presigned URL (via your own API)
+     * signUrl: async (src) => {
+     *   const res = await fetch(`/api/sign-url?src=${encodeURIComponent(src)}`)
+     *   const { url } = await res.json()
+     *   return url
+     * }
+     *
+     * @example
+     * // Cloudflare Stream signed URL
+     * signUrl: async (src) => {
+     *   const res = await fetch('/api/cf-sign', { method: 'POST', body: JSON.stringify({ src }) })
+     *   const { url } = await res.json()
+     *   return url
+     * }
+     */
+    signUrl?: (src: string) => Promise<string>;
+}
+interface LumraConfig {
+    theme?: LumraTheme;
+    controls?: LumraControlsConfig;
+    behavior?: LumraBehaviorConfig;
+    paywall?: LumraPaywallConfig;
+    ads?: LumraAdsConfig;
+    storage?: LumraStorageConfig;
+    cloud?: LumraCloudConfig;
+}
+/** Type-safe helper — returns the config unchanged but provides IDE autocomplete */
+declare function defineLumraConfig(config: LumraConfig): LumraConfig;
+declare function LumraConfigProvider({ config, children, }: {
+    config: LumraConfig;
+    children: React$1.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useLumraConfig(): LumraConfig;
+
+export { type LumraAdConfig, type LumraAdsConfig, type LumraBehaviorConfig, type LumraCloudConfig, type LumraConfig, LumraConfigProvider, type LumraControlsConfig, type LumraMediaInfo, type LumraMidRollConfig, type LumraPaywallConfig, LumraPlayer, type LumraPlayerComponents, type LumraPlayerPaywall, type LumraPlayerProps, type LumraStorageConfig, type LumraTheme, type LumraTrack, type UsePlayerOptions, type UsePlayerReturn, defineLumraConfig, useLumraConfig, usePlayer };