@mottosports/motto-video-player 1.0.1-rc.7 → 1.0.1-rc.8

package/README.md

@@ -1,6 +1,6 @@
 # Motto Video Player
 
-A modern, feature-rich video player built on top of Shaka Player with React support.
+React video player component for the Motto platform, powered by Shaka Player with TanStack Query integration.
 
 ## Features
 
@@ -17,220 +17,217 @@ A modern, feature-rich video player built on top of Shaka Player with React supp
 ## Installation
 
 ```bash
-npm install @motto/video-player
-# or
-yarn add @motto/video-player
-# or  
-pnpm add @motto/video-player
+npm install @motto-ui-components/motto-video-player @tanstack/react-query
 ```
 
-## Basic Usage
+## Quick Start
 
-```tsx
-import { Player } from '@motto/video-player';
+### Setup QueryClient (Required for Video wrapper)
 
-function MyVideoPlayer() {
-  return (
-    <Player
-      src="https://example.com/video.m3u8"
-      autoPlay={false}
-      controls={true}
-      width={800}
-      height={450}
-    />
-  );
-}
-```
-
-## Next.js Usage (SSR Support)
-
-If you're using Next.js, you need to handle server-side rendering (SSR) since Shaka Player requires browser APIs. Here are three approaches:
-
-### Option 1: Using next/dynamic (Recommended)
+```jsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
-```tsx
-import dynamic from 'next/dynamic';
+const queryClient = new QueryClient();
 
-const MottoPlayer = dynamic(
-  () => import('@motto/video-player').then((mod) => ({ default: mod.Player })),
-  { 
-    ssr: false,
-    loading: () => <div>Loading player...</div>
-  }
-);
-
-function MyVideoPage() {
+function App() {
   return (
-    <div>
-      <h1>My Video</h1>
-      <MottoPlayer
-        src="https://example.com/video.m3u8"
-        autoPlay={false}
-        controls={true}
-        width={800}
-        height={450}
-      />
-    </div>
+    <QueryClientProvider client={queryClient}>
+      <YourComponents />
+    </QueryClientProvider>
   );
 }
 ```
 
-### Option 2: Using the built-in ClientOnlyPlayer
+### Basic Usage
+
+#### VideoPlayer (Bare Component)
+For direct stream URL playback:
 
-```tsx
-import { ClientOnlyPlayer } from '@motto/video-player';
+```jsx
+import { VideoPlayer } from '@motto-ui-components/motto-video-player';
 
-function MyVideoPage() {
+function MyPlayer() {
   return (
-    <div>
-      <h1>My Video</h1>
-      <ClientOnlyPlayer
-        src="https://example.com/video.m3u8"
-        autoPlay={false}
-        controls={true}
-        width={800}
-        height={450}
-      />
-    </div>
+    <VideoPlayer
+      src="https://example.com/video.m3u8"
+      controls
+      aspectRatio={16/9}
+      onPlay={() => console.log('Playing')}
+      onError={(error) => console.error(error)}
+    />
   );
 }
 ```
 
-### Option 3: Using useEffect for client-side only rendering
-
-```tsx
-import { Player } from '@motto/video-player';
-import { useEffect, useState } from 'react';
+#### Video (Wrapper Component)
+For data fetching with TanStack Query:
 
-function MyVideoPage() {
-  const [isClient, setIsClient] = useState(false);
-
-  useEffect(() => {
-    setIsClient(true);
-  }, []);
-
-  if (!isClient) {
-    return <div>Loading player...</div>;
-  }
+```jsx
+import { Video } from '@motto-ui-components/motto-video-player';
 
+function MyPlayer() {
   return (
-    <div>
-      <h1>My Video</h1>
-      <Player
-        src="https://example.com/video.m3u8"
-        autoPlay={false}
-        controls={true}
-        width={800}
-        height={450}
-      />
-    </div>
+    <Video
+      videoId="your-video-id"
+      publicKey="your-public-key"
+      controls
+      refetchInterval={30000}
+      events={{
+        onVideoData: (video) => console.log('Video loaded:', video),
+        onError: (error) => console.error('Error:', error),
+        onPlay: () => console.log('Playing')
+      }}
+    />
   );
 }
 ```
 
-## Player Props
-
-The player accepts the following props:
+## Component Comparison
 
-- `src` (string, required): URL of the video manifest (HLS, DASH, etc.)
-- `autoPlay` (boolean, default: false): Whether to start playing automatically
-- `controls` (boolean, default: true): Whether to show player controls
-- `width` (number): Fixed width in pixels
-- `height` (number): Fixed height in pixels  
-- `aspectRatio` (number, default: 16/9): Aspect ratio for responsive sizing
-- `poster` (string): URL of poster image to show before video loads
-- `muted` (boolean, default: false): Whether to start muted
-- `loop` (boolean, default: false): Whether to loop the video
+| Feature | VideoPlayer | Video |
+|---------|-------------|-------|
+| **Use Case** | Direct stream URL | Data fetching with videoId |
+| **Data Fetching** | ❌ Manual | ✅ Automatic with TanStack Query |
+| **Caching** | ❌ None | ✅ Smart caching & background updates |
+| **Loading States** | ❌ Manual | ✅ Built-in loading indicators |
+| **Error Handling** | ❌ Manual | ✅ Automatic retry with exponential backoff |
+| **Performance** | ✅ Minimal overhead | ✅ Optimized with query deduplication |
 
 ## Advanced Configuration
 
-### Quality Control
-
-```tsx
-<Player
-  src="https://example.com/video.m3u8"
-  qualityConfig={{
-    enableAutoQuality: true,
-    preferredVideoHeight: 720,
-    preferredAudioLanguage: 'en'
+### TanStack Query Options
+
+```jsx
+<Video
+  videoId="123"
+  publicKey="key"
+  refetchInterval={30000}
+  queryOptions={{
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    retry: 3,
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000)
   }}
 />
 ```
 
-### DRM Configuration
+### Skip Controls
 
-```tsx
-<Player
-  src="https://example.com/protected-video.mpd"
-  drmConfig={{
-    servers: {
-      'com.widevine.alpha': 'https://license-server.com/widevine',
-      'com.microsoft.playready': 'https://license-server.com/playready'
-    }
+```jsx
+<VideoPlayer
+  src="..."
+  skipConfig={{
+    showSkipBack: true,
+    showSkipForward: true,
+    skipDuration: 15,
+    position: 'controls' // or 'overlay'
   }}
+  onSkipBack={(newTime) => console.log('Skipped to:', newTime)}
+  onSkipForward={(newTime) => console.log('Skipped to:', newTime)}
 />
 ```
 
-### Mux Analytics
+### Responsive Sizing
+
+```jsx
+// Default responsive 16:9
+<VideoPlayer src="..." />
 
-```tsx
-<Player
-  src="https://example.com/video.m3u8"
+// Custom aspect ratio
+<VideoPlayer src="..." aspectRatio={4/3} />
+
+// Fixed dimensions
+<VideoPlayer src="..." width={800} height={450} />
+```
+
+### Analytics Integration
+
+```jsx
+<VideoPlayer
+  src="..."
   muxConfig={{
-    envKey: 'your-mux-env-key',
-    metadata: {
-      video_title: 'My Video',
-      viewer_user_id: 'user123'
+    debug: false,
+    data: {
+      env_key: 'your-mux-env-key',
+      video_title: 'Video Title',
+      video_id: 'video-123',
+      player_name: 'Web Player',
+      viewer_user_id: 'user-456'
     }
   }}
+  onMuxReady={(monitor) => console.log('Mux ready')}
 />
 ```
 
-## Event Handling
-
-```tsx
-<Player
-  src="https://example.com/video.m3u8"
-  events={{
-    onPlay: () => console.log('Video started playing'),
-    onPause: () => console.log('Video paused'),
-    onEnded: () => console.log('Video ended'),
-    onError: (error) => console.error('Playback error:', error),
-    onQualityChange: (quality) => console.log('Quality changed:', quality)
-  }}
-/>
+## API Reference
+
+### VideoPlayer Props
+
+```typescript
+interface VideoPlayerProps {
+  src: string;                    // Video source URL
+  autoPlay?: boolean;            // Auto-play video
+  controls?: boolean;            // Show player controls
+  aspectRatio?: number;          // Video aspect ratio (default: 16/9)
+  width?: number;               // Fixed width
+  height?: number;              // Fixed height
+  skipConfig?: SkipConfig;      // Skip controls configuration
+  muxConfig?: MuxConfig;        // Mux analytics configuration
+  onPlay?: () => void;          // Play event callback
+  onPause?: () => void;         // Pause event callback
+  onError?: (error: any) => void; // Error event callback
+  // ... more props
+}
 ```
 
-## Responsive Design
+### Video Props
+
+```typescript
+interface VideoProps extends Omit<VideoPlayerProps, 'src'> {
+  videoId?: string;             // Video ID for data fetching
+  publicKey?: string;           // Public key for API authentication
+  videoData?: VideoData;        // Pre-loaded video data
+  refetchInterval?: number;     // Background refetch interval (ms)
+  queryOptions?: QueryOptions;  // TanStack Query configuration
+  events?: {
+    onVideoData?: (video: VideoData) => void;
+    onEmptyPlaylists?: () => void;
+    onError?: (error: Error) => void;
+    // ... player events
+  };
+}
+```
 
-For responsive video players, omit the `width` and `height` props and optionally set an `aspectRatio`:
+## TanStack Query Benefits
 
-```tsx
-<Player
-  src="https://example.com/video.m3u8"
-  aspectRatio={16/9}
-  containerClassName="w-full max-w-4xl"
-/>
-```
+### Caching & Performance
+- **Automatic Caching**: Videos are cached with configurable stale time
+- **Background Refetching**: Data stays fresh with background updates
+- **Request Deduplication**: Identical requests are automatically deduplicated
+- **Garbage Collection**: Memory-efficient cleanup of unused cache entries
 
-## Live Streaming
+### Resilience & UX
+- **Smart Retries**: Exponential backoff retry logic for failed requests
+- **Loading States**: Built-in loading indicators for better UX
+- **Error Recovery**: Automatic error handling and recovery mechanisms
+- **Optimistic Updates**: Support for optimistic UI updates
 
-The player automatically detects live streams and shows appropriate UI:
+## Examples
 
-```tsx
-<Player
-  src="https://example.com/live-stream.m3u8"
-  streamStartDate={new Date('2024-01-01T12:00:00Z')} // Optional: for absolute time display
-/>
-```
+Check out the [example app](../../apps/example) for comprehensive usage examples including:
+
+- Basic VideoPlayer usage
+- Video wrapper with TanStack Query
+- Pre-loaded data scenarios
+- Skip controls integration
+- Responsive design patterns
 
-## Browser Support
+## Contributing
 
-- Chrome 80+
-- Firefox 75+  
-- Safari 13+
-- Edge 80+
+1. Clone the repository
+2. Install dependencies: `pnpm install`
+3. Start development: `pnpm dev`
+4. Build: `pnpm build`
 
 ## License
 
-MIT 
+ISC 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import * as React from 'react';
-import React__default, { HTMLAttributes } from 'react';
+import React, { HTMLAttributes } from 'react';
+import { QueryClient } from '@tanstack/react-query';
 
 /**
  * Unified events interface for both Player and Video wrapper
@@ -225,17 +225,7 @@ interface PlayerProps extends Omit<HTMLAttributes<HTMLVideoElement>, 'src' | 'on
      * Event callbacks
      */
     events?: PlayerEvents;
-    /**
-     * CSS class name for the container element
-     */
     containerClassName?: string;
-    /**
-     * Optional manual override for stream start time
-     * If not provided, the player will attempt to auto-detect the stream start time
-     * from the manifest for live streams. When provided, shows elapsed time since
-     * stream started instead of the current playback position.
-     */
-    streamStartDate?: Date;
 }
 /**
  * Mux Analytics type definitions
@@ -330,7 +320,7 @@ interface MuxAnalyticsConfig {
     metadata?: MuxMetadata;
 }
 
-declare const Player: React__default.ForwardRefExoticComponent<PlayerProps & React__default.RefAttributes<HTMLVideoElement>>;
+declare const Player: React.ForwardRefExoticComponent<PlayerProps & React.RefAttributes<HTMLVideoElement>>;
 
 interface VideoData {
     id: string;
@@ -352,22 +342,6 @@ interface VideoListItem {
     }>;
     error?: string;
 }
-/**
- * Fetches video data from the Motto Streaming API
- * @param videoId - The ID of the video to fetch
- * @param publicKey - The public key for authentication
- * @param mottoToken - Optional motto token for authenticated requests
- * @returns Promise<VideoData> - The video data
- */
-declare const fetchVideoData: (videoId: string, publicKey: string, mottoToken?: string) => Promise<VideoData>;
-/**
- * Fetches multiple videos data from the Motto Streaming API
- * @param publicKey - The public key for authentication
- * @param videoIds - Array of video IDs to fetch
- * @param mottoToken - Optional motto token for authenticated requests
- * @returns Promise<VideoListItem[]> - Array of video data
- */
-declare function fetchVideosList(publicKey: string, videoIds: string[], mottoToken?: string, skip?: number, limit?: number): Promise<VideoListItem[]>;
 
 interface EventData {
     id: string;
@@ -383,7 +357,6 @@ declare enum EventsSortDirection {
     ASC = "asc",
     DESC = "desc"
 }
-declare function fetchEventData(publicKey: string, eventId: string, unused?: any, filter?: string, order?: EventsSortDirection, locale?: string): Promise<EventData>;
 
 interface CreativeWorkData {
     id: string;
@@ -399,7 +372,6 @@ declare enum CreativeWorksSortDirection {
     ASC = "asc",
     DESC = "desc"
 }
-declare function fetchCreativeWorkData(publicKey: string, creativeWorkId: string, unused?: any, filter?: string, order?: CreativeWorksSortDirection, locale?: string): Promise<CreativeWorkData>;
 
 interface VideoProps extends Omit<PlayerProps, 'src'> {
     videoId?: string;
@@ -420,7 +392,7 @@ interface VideoProps extends Omit<PlayerProps, 'src'> {
         onCanPlay?: () => void;
         onPlayerReady?: () => void;
     };
-    children?: React__default.ReactNode;
+    children?: React.ReactNode;
     className?: string;
     queryOptions?: {
         enabled?: boolean;
@@ -430,7 +402,7 @@ interface VideoProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const Video: React__default.FC<VideoProps>;
+declare const Video: React.FC<VideoProps>;
 
 interface EventProps extends Omit<PlayerProps, 'src'> {
     publicKey: string;
@@ -468,7 +440,7 @@ interface EventProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const Event: React__default.FC<EventProps>;
+declare const Event: React.FC<EventProps>;
 
 interface CreativeWorkProps extends Omit<PlayerProps, 'src'> {
     publicKey: string;
@@ -506,15 +478,12 @@ interface CreativeWorkProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const CreativeWork: React__default.FC<CreativeWorkProps>;
+declare const CreativeWork: React.FC<CreativeWorkProps>;
 
+declare const queryClient: QueryClient;
 interface QueryProviderProps {
-    children: React__default.ReactNode;
+    children: React.ReactNode;
 }
-declare const QueryProvider: React__default.FC<QueryProviderProps>;
-
-declare const _default: {
-    Player: React.ForwardRefExoticComponent<PlayerProps & React.RefAttributes<HTMLVideoElement>>;
-};
+declare const QueryProvider: React.FC<QueryProviderProps>;
 
-export { CreativeWork, type CreativeWorkData, type CreativeWorkProps, CreativeWorksSortDirection, Event, type EventData, type EventProps, EventsSortDirection, type MuxAnalyticsConfig, type MuxDataUpdatePayload, type MuxErrorTranslator, type MuxMetadata, Player, type PlayerEvents, type PlayerProps, QueryProvider, type SeekbarConfig, Video, type VideoData, type VideoListItem, type VideoProps, _default as default, fetchCreativeWorkData, fetchEventData, fetchVideoData, fetchVideosList };
+export { CreativeWork, type CreativeWorkData, type CreativeWorkProps, CreativeWorksSortDirection, Event, type EventData, type EventProps, EventsSortDirection, Player, type PlayerEvents, type PlayerProps, QueryProvider, Video, type VideoData, type VideoListItem, type VideoProps, queryClient };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import * as React from 'react';
-import React__default, { HTMLAttributes } from 'react';
+import React, { HTMLAttributes } from 'react';
+import { QueryClient } from '@tanstack/react-query';
 
 /**
  * Unified events interface for both Player and Video wrapper
@@ -225,17 +225,7 @@ interface PlayerProps extends Omit<HTMLAttributes<HTMLVideoElement>, 'src' | 'on
      * Event callbacks
      */
     events?: PlayerEvents;
-    /**
-     * CSS class name for the container element
-     */
     containerClassName?: string;
-    /**
-     * Optional manual override for stream start time
-     * If not provided, the player will attempt to auto-detect the stream start time
-     * from the manifest for live streams. When provided, shows elapsed time since
-     * stream started instead of the current playback position.
-     */
-    streamStartDate?: Date;
 }
 /**
  * Mux Analytics type definitions
@@ -330,7 +320,7 @@ interface MuxAnalyticsConfig {
     metadata?: MuxMetadata;
 }
 
-declare const Player: React__default.ForwardRefExoticComponent<PlayerProps & React__default.RefAttributes<HTMLVideoElement>>;
+declare const Player: React.ForwardRefExoticComponent<PlayerProps & React.RefAttributes<HTMLVideoElement>>;
 
 interface VideoData {
     id: string;
@@ -352,22 +342,6 @@ interface VideoListItem {
     }>;
     error?: string;
 }
-/**
- * Fetches video data from the Motto Streaming API
- * @param videoId - The ID of the video to fetch
- * @param publicKey - The public key for authentication
- * @param mottoToken - Optional motto token for authenticated requests
- * @returns Promise<VideoData> - The video data
- */
-declare const fetchVideoData: (videoId: string, publicKey: string, mottoToken?: string) => Promise<VideoData>;
-/**
- * Fetches multiple videos data from the Motto Streaming API
- * @param publicKey - The public key for authentication
- * @param videoIds - Array of video IDs to fetch
- * @param mottoToken - Optional motto token for authenticated requests
- * @returns Promise<VideoListItem[]> - Array of video data
- */
-declare function fetchVideosList(publicKey: string, videoIds: string[], mottoToken?: string, skip?: number, limit?: number): Promise<VideoListItem[]>;
 
 interface EventData {
     id: string;
@@ -383,7 +357,6 @@ declare enum EventsSortDirection {
     ASC = "asc",
     DESC = "desc"
 }
-declare function fetchEventData(publicKey: string, eventId: string, unused?: any, filter?: string, order?: EventsSortDirection, locale?: string): Promise<EventData>;
 
 interface CreativeWorkData {
     id: string;
@@ -399,7 +372,6 @@ declare enum CreativeWorksSortDirection {
     ASC = "asc",
     DESC = "desc"
 }
-declare function fetchCreativeWorkData(publicKey: string, creativeWorkId: string, unused?: any, filter?: string, order?: CreativeWorksSortDirection, locale?: string): Promise<CreativeWorkData>;
 
 interface VideoProps extends Omit<PlayerProps, 'src'> {
     videoId?: string;
@@ -420,7 +392,7 @@ interface VideoProps extends Omit<PlayerProps, 'src'> {
         onCanPlay?: () => void;
         onPlayerReady?: () => void;
     };
-    children?: React__default.ReactNode;
+    children?: React.ReactNode;
     className?: string;
     queryOptions?: {
         enabled?: boolean;
@@ -430,7 +402,7 @@ interface VideoProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const Video: React__default.FC<VideoProps>;
+declare const Video: React.FC<VideoProps>;
 
 interface EventProps extends Omit<PlayerProps, 'src'> {
     publicKey: string;
@@ -468,7 +440,7 @@ interface EventProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const Event: React__default.FC<EventProps>;
+declare const Event: React.FC<EventProps>;
 
 interface CreativeWorkProps extends Omit<PlayerProps, 'src'> {
     publicKey: string;
@@ -506,15 +478,12 @@ interface CreativeWorkProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const CreativeWork: React__default.FC<CreativeWorkProps>;
+declare const CreativeWork: React.FC<CreativeWorkProps>;
 
+declare const queryClient: QueryClient;
 interface QueryProviderProps {
-    children: React__default.ReactNode;
+    children: React.ReactNode;
 }
-declare const QueryProvider: React__default.FC<QueryProviderProps>;
-
-declare const _default: {
-    Player: React.ForwardRefExoticComponent<PlayerProps & React.RefAttributes<HTMLVideoElement>>;
-};
+declare const QueryProvider: React.FC<QueryProviderProps>;
 
-export { CreativeWork, type CreativeWorkData, type CreativeWorkProps, CreativeWorksSortDirection, Event, type EventData, type EventProps, EventsSortDirection, type MuxAnalyticsConfig, type MuxDataUpdatePayload, type MuxErrorTranslator, type MuxMetadata, Player, type PlayerEvents, type PlayerProps, QueryProvider, type SeekbarConfig, Video, type VideoData, type VideoListItem, type VideoProps, _default as default, fetchCreativeWorkData, fetchEventData, fetchVideoData, fetchVideosList };
+export { CreativeWork, type CreativeWorkData, type CreativeWorkProps, CreativeWorksSortDirection, Event, type EventData, type EventProps, EventsSortDirection, Player, type PlayerEvents, type PlayerProps, QueryProvider, Video, type VideoData, type VideoListItem, type VideoProps, queryClient };