@flowplayer/spins 0.5.1 → 0.7.0

package/README.md

@@ -2,10 +2,12 @@
 
 A TypeScript library for creating Flowplayer playlist components optimized for short-form video content like Reels and Shorts.
 
+## Quick Start
+
 ```typescript
 import { createSpins } from "@flowplayer/spins";
 
-const spinsContainer = createSpins({ 
+const spinsContainer = createSpins({
   playlist: "your-playlist-id",
   token: "your-token",
   lang: "en",
@@ -13,30 +15,6 @@ const spinsContainer = createSpins({
 document.body.appendChild(spinsContainer);
 ```
 
-### React Usage
-
-```tsx
-import { createSpins, type SpinsConfig } from "@flowplayer/spins";
-import { useEffect, useRef } from "react";
-
-function SpinsPlayer({ playlistId }: { playlistId: string }) {
-  const containerRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (containerRef.current) {
-      const spinsContainer = createSpins({ 
-        playlist: playlistId,
-        token: "your-token",
-        lang: "en",
-      });
-      containerRef.current.appendChild(spinsContainer);
-    }
-  }, [playlistId]);
-
-  return <div ref={containerRef} className="spins-container" />;
-}
-```
-
 ## Features
 
 - 🎯 **Type-safe** - Built with TypeScript and Zod schema validation
@@ -56,20 +34,76 @@ bun add @flowplayer/spins
 
 ## Usage
 
+### Basic Usage
+
 ```typescript
-import { spins, type SpinsConfig } from "@flowplayer/spins";
+import { createSpins, type SpinsConfig } from "@flowplayer/spins";
 
-// Create a playlist component for short-form content
 const config: SpinsConfig = {
   playlist: "your-playlist-id", // or array of SpinItem objects
   token: "your-flowplayer-token",
   lang: "en"
 };
 
-const spinsContainer = spins(config);
+const spinsContainer = createSpins(config);
 document.body.appendChild(spinsContainer);
 ```
 
+### React Integration
+
+```tsx
+import { createSpins, type SpinsConfig } from "@flowplayer/spins";
+import { useEffect, useRef } from "react";
+
+function SpinsPlayer({ playlistId }: { playlistId: string }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const spinsContainer = createSpins({
+      playlist: playlistId,
+      token: "your-token",
+      lang: "en",
+    });
+
+    containerRef.current.appendChild(spinsContainer);
+
+    return () => {
+      spinsContainer.remove();
+    };
+  }, [playlistId]);
+
+  return <div ref={containerRef} className="spins-container" />;
+}
+```
+
+### With Custom Playlist
+
+```typescript
+import { createSpins, type SpinItem } from "@flowplayer/spins";
+
+const customPlaylist: SpinItem[] = [
+  {
+    url: "https://example.com/video1.mp4",
+    title: "First Video",
+    poster: "https://example.com/poster1.jpg",
+    description: "Description of first video"
+  },
+  {
+    url: { src: "https://example.com/video2.mp4", type: "video/mp4" },
+    title: "Second Video",
+    poster: "https://example.com/poster2.jpg"
+  }
+];
+
+const spinsContainer = createSpins({
+  playlist: customPlaylist,
+  token: "your-token",
+  lang: "en"
+});
+```
+
 ## Short-Form Video Content
 
 This library is specifically designed to handle short-form video playlists, making it easy to create engaging vertical video experiences similar to:
@@ -86,106 +120,297 @@ The component automatically handles playlist loading and provides the structure
 
 Creates a Flowplayer playlist component container optimized for short-form video content.
 
-#### Parameters
+#### Configuration Options
 
-- `config.playlist: string | Array<SpinConfig>` - The playlist ID or array of spin configurations
-- `config.token: string` - Your Flowplayer token
-- `config.lang: string` - Language code (e.g., "en", "es")
+```typescript
+interface SpinsConfig {
+  playlist: string | Array<SpinItem>;  // Playlist ID or array of SpinItem
+  token?: string;                       // Your Flowplayer token
+  lang?: string;                        // Language code (e.g., "en", "es")
+  ui?: number;                          // UI configuration bitmask
+  ima?: PlayerIMAConfig;                // IMA ads configuration
+  adsFrequency?: number;                // Show ads every Nth spin (default: 10)
+  share?: ShareConfig;                  // Share plugin configuration
+  consent?: number;                     // Consent plugin configuration
+  plugins?: string[];                   // List of plugins to enable
+}
+```
 
 #### Returns
 
-Returns a `SpinsContainer` (extends `HTMLElement`) with event handling capabilities:
-- `on(event, handler)` - Subscribe to events
-- `off(event, handler)` - Unsubscribe from events
+A `SpinsContainer` instance (extends `HTMLElement`) with the following methods:
 
-#### Events
+##### Event Handling
 
-- `SPIN_CREATED` - Fired when a new spin is created
-- `SPIN_IN_VIEWPORT` - Fired when a spin enters the viewport
+```typescript
+// Listen to spin lifecycle events
+spinsContainer.on(spinEvents.SPIN_CREATED, (e) => {
+  console.log('Spin created:', e.detail.config, e.detail.index);
+});
 
-#### Error Handling
+spinsContainer.on(spinEvents.SPIN_IN_VIEWPORT, (e) => {
+  console.log('Spin in viewport:', e.detail.index);
+});
+
+// Listen to player events (media events)
+spinsContainer.onPlayerEvent(mediaEvents.PLAY, (e) => {
+  console.log('Video playing:', e.detail.spinIndex, e.detail.currentTime);
+});
+
+spinsContainer.onPlayerEvent(mediaEvents.ENDED, (e) => {
+  console.log('Video ended:', e.detail.spinIndex);
+});
+
+// Listen to ad events
+spinsContainer.onPlayerEvent(adEvents.AD_STARTED, (e) => {
+  console.log('Ad started:', e.detail.spinIndex);
+});
+
+// Remove event listeners
+spinsContainer.off(spinEvents.SPIN_CREATED, handler);
+spinsContainer.offPlayerEvent(mediaEvents.PLAY, handler);
+```
+
+##### Dynamic Content
+
+```typescript
+// Add more spins dynamically
+spinsContainer.addSpins([
+  {
+    url: "https://example.com/video3.mp4",
+    title: "New Video",
+    poster: "https://example.com/poster3.jpg"
+  }
+]);
+```
 
-The function gracefully handles:
-- Network errors (API unavailable, timeout, etc.)
-- Invalid playlist configurations
-- HTTP errors (404, 500, etc.)
+### Events
+
+#### Spin Events (`spinEvents`)
+
+- `SPIN_CREATED` - Fired when a new spin is created
+  - `detail.config`: SpinItem configuration
+  - `detail.spin`: The spin container HTMLElement
+  - `detail.index`: Spin index
+
+- `SPIN_IN_VIEWPORT` - Fired when a spin enters the viewport
+  - `detail.config`: SpinItem configuration
+  - `detail.spin`: The spin container HTMLElement
+  - `detail.index`: Spin index
+
+#### Media Events (`mediaEvents`)
+
+- `PLAY` - Playback started/resumed
+- `PAUSE` - Playback paused
+- `PLAYING` - Actively playing
+- `WAITING` - Buffering
+- `CAN_PLAY` - Ready to play
+- `TIME_UPDATE` - Playback position changed
+- `SEEKING` - User seeking
+- `ENDED` - Playback ended
+
+All media events include:
+- `detail.spinIndex`: Index of the spin
+- `detail.currentTime`: Current playback time in seconds
+- `detail.duration`: Video duration in seconds
+- `detail.mediaId`: Media ID (if available)
+- `detail.url`: Full URL of the media
+
+#### Ad Events (`adEvents`)
+
+- `AD_STARTED` - Ad playback started
+- `AD_COMPLETED` - Ad finished playing
+- `AD_PROGRESS` - Ad playback progress
+- `AD_PAUSED` - Ad paused
+- `AD_RESUMED` - Ad resumed
+- `AD_SKIPPED` - Ad skipped by user
+- `AD_ERROR` - Ad error occurred
+- `AD_REQUEST_ERROR` - Ad request failed
+- `AD_PLAYBACK_ERROR` - Ad playback error
+- `AD_BREAK_COMPLETED` - Ad break finished
+- `AD_TEARDOWN` - Ad cleanup
+- `AD_MUTED` - Ad muted
+- `AD_VOLUME_CHANGED` - Ad volume changed
+- `AD_PREROLL_FINSIHED` - Preroll ad finished
+
+All ad events include:
+- `detail.spinIndex`: Index of the spin where the ad is shown
 
 ## TypeScript Support
 
-The library exports TypeScript types for full type safety:
+The library is fully typed with TypeScript. Import types for full type safety:
 
 ```typescript
-import { type SpinsConfig, type SpinItem, type SpinsContainer } from "@flowplayer/spins";
+import {
+  createSpins,
+  createAdPlayer,
+  spinEvents,
+  mediaEvents,
+  adEvents,
+  type SpinsConfig,
+  type SpinItem,
+  type SpinsContainer,
+  type SpinsAdPlayer,
+  type SpinsAdPlayerConfig,
+  type SpinEvent,
+  type MediaEvent,
+  type AdEvent,
+  type PlayerEvent,
+  type SpinEventData,
+  type MediaEventData,
+  type AdEventData,
+  type PlayerEventsDetailMap,
+  type AdEventsDetailMap,
+} from "@flowplayer/spins";
 ```
 
-### `SpinsConfig`
+### Key Type Definitions
+
+#### `SpinsConfig`
 
-The main configuration interface:
+Main configuration for creating a spins container:
 
 ```typescript
 interface SpinsConfig {
   playlist: string | Array<SpinItem>;
-  token: string;
-  lang: string;
+  token?: string;
+  lang?: string;
+  ui?: number;
+  ima?: PlayerIMAConfig;
+  adsFrequency?: number;
+  share?: ShareConfig;
+  consent?: number;
+  plugins?: string[];
 }
 ```
 
-### `SpinItem`
+#### `SpinItem`
 
-Individual spin configuration:
+Individual video configuration:
 
 ```typescript
 interface SpinItem {
-  src: Config["src"];
+  url: string | { src: string; type: string };
   title?: string;
   poster?: string;
   description?: string;
-  subtitles?: SubtitlesConfig["subtitles"];
+  subtitles?: SubtitlesConfig;
 }
 ```
 
-## CSS Styling
+#### `SpinsContainer`
 
-The component includes default CSS styling optimized for short-form video content. Styles are imported from:
-You can override styles by targeting the spins container and its children:
+The container element with event handling:
 
-```css
-.spins-container {
-  /* Base spins container styles */
+```typescript
+interface SpinsContainer extends HTMLElement {
+  on(event: SpinEvent, handler: (e: CustomEvent<SpinEventData>) => void): void;
+  off(event: SpinEvent, handler: (e: CustomEvent<SpinEventData>) => void): void;
+  onPlayerEvent<K extends PlayerEvent>(
+    event: K,
+    handler: (e: CustomEvent<PlayerEventsDetailMap[K]>) => void
+  ): void;
+  offPlayerEvent<K extends PlayerEvent>(
+    event: K,
+    handler: (e: CustomEvent<PlayerEventsDetailMap[K]>) => void
+  ): void;
+  addSpins(spins: SpinItem[]): void;
+}
+```
+
+#### Event Data Types
+
+```typescript
+interface SpinEventData {
+  config: SpinItem;
+  spin: HTMLElement;
+  index: number;
 }
 
-flowplayer-spin {
-  /* Individual spin container styles */
+interface MediaEventData {
+  spinIndex: number;
+  duration?: number;
+  currentTime: number;
+  mediaId?: string;
+  url: string;
 }
+
+type AdEventData<K extends AdEvent> = {
+  spinIndex: number;
+} & AdEventsDetailMap[K];
 ```
 
-## Development
+## Advanced Usage
 
-### Prerequisites
+### Listening to All Events
 
-- [Bun](https://bun.sh/) runtime
-- TypeScript 5+
+```typescript
+import {
+  createSpins,
+  spinEvents,
+  mediaEvents,
+  adEvents,
+  type SpinEventData,
+  type MediaEventData
+} from "@flowplayer/spins";
+
+const container = createSpins({
+  playlist: "your-playlist-id",
+  token: "your-token",
+  lang: "en",
+  adsFrequency: 5  // Show ads every 5th spin
+});
 
-### Scripts
+// Spin lifecycle events
+container.on(spinEvents.SPIN_CREATED, (e) => {
+  console.log(`Spin ${e.detail.index} created:`, e.detail.config);
+});
 
-```bash
-# Development with Storybook
-bun run dev
+container.on(spinEvents.SPIN_IN_VIEWPORT, (e) => {
+  console.log(`Spin ${e.detail.index} is now visible`);
+});
 
-# Build the library
-bun run build
+// Media playback events
+container.onPlayerEvent(mediaEvents.PLAY, (e) => {
+  console.log(`Playing spin ${e.detail.spinIndex}`);
+});
 
-# Build TypeScript declarations
-bun run build:dts
+container.onPlayerEvent(mediaEvents.TIME_UPDATE, (e) => {
+  console.log(`Progress: ${e.detail.currentTime}/${e.detail.duration}`);
+});
 
-# Run tests
-bun run test
+container.onPlayerEvent(mediaEvents.ENDED, (e) => {
+  console.log(`Spin ${e.detail.spinIndex} finished`);
+});
 
-# Lint and format code
-bun run lint
+// Ad events
+container.onPlayerEvent(adEvents.AD_STARTED, (e) => {
+  console.log(`Ad started at spin ${e.detail.spinIndex}`);
+});
 
-# Build Storybook for production
-bun run build-storybook
+container.onPlayerEvent(adEvents.AD_COMPLETED, (e) => {
+  console.log(`Ad completed at spin ${e.detail.spinIndex}`);
+});
+
+document.body.appendChild(container);
+```
+
+### Advertising Configuration
+
+```typescript
+import { createSpins } from "@flowplayer/spins";
+
+const container = createSpins({
+  playlist: "your-playlist-id",
+  token: "your-token",
+  lang: "en",
+  adsFrequency: 3,  // Show ads every 3rd spin
+  ima: {
+    ads: [{
+      adTag: "https://pubads.g.doubleclick.net/gampad/ads?...",
+      time: 0
+    }]}
+});
 ```
 
 ## Contributing
@@ -196,6 +421,7 @@ This project uses:
 - **Vitest** with **Playwright** for browser testing
 - **Storybook** for component development and documentation
 - **Lit** for custom web components
+- **Zod** for runtime schema validation
 
 ## License