@tivio/sdk-react 9.2.0-alpha.3 → 9.2.0

package/README.md.bak

@@ -4,315 +4,6 @@
 above Tivio Studio. You can comfortably manage all you videos, settings such as application's screens and rows and also monetization
 settings in the administration of Tivio Studio while having the freedom to build your own application.
 
-## Changelog
-* 9.2.0-alpha.0
-  * minor: add renderWebPlayer method for rendering outside of React
-  * minor: "expose createTivio" 
-
-* 9.1.7
-  * patch: update remote controller component API
-
-* 9.1.6
-  * minor: add remote controller
-
-* 9.1.5
-  * patch: expose purchase loyalty points through types
-  * patch: enable setUser check
-
-* 9.1.4
-  * patch: disable setUser check
-  * patch: rollback "add renderWebPlayer method for rendering outside of React"
-  * patch: rollback "expose createTivio"
-
-* 9.1.3
-  * patch: add renderWebPlayer method for rendering outside of React
-  * patch: expose createTivio
-
-* 9.1.4
-  * patch: disable setUser check
-
-* 9.1.3
-  * minor: add renderWebPlayer method for rendering outside of React
-  * minor: expose createTivio
-
-* 9.1.2
-  * patch: update PurchaseEndpointPayload type (cityName, externalId, geoPoint)
-
-* 9.1.1
-  * patch: fix changelog
-
-* 9.1.0
-    * patch: add gateway to Purchase type
-    * minor: add QerkoPaymentWebhookByApiKeyRequest to exported types
-
-* 9.0.0
-    * patch: remove i18next and react-i18next from externals and dependencies
-    * patch: do not send react-spring to core-react-dom bundle, remove react-spring from dependencies
-    * patch: clean-up externals in webpack config
-    * patch: send only required dependencies to the bundle
-    * major: change purchase statuses lifecycle
-    * minor: add originalPurchaseId to PurchaseEndpointPayload
-
-* 8.0.0
-    * major: deprecated usePurchasesWithVideos hook removed
-    * patch: add id to user type
-    * patch: add @types/react to peerDependencies
-
-* 7.1.0
-    * minor: export useTvChannelHook
-    * patch: bump "react-i18next", "i18next" versions.
-
-* 7.0.1
-    * patch: fix dependency to @tivio/common
-
-* 7.0.0
-    * major: delete deprecated useWatchWithoutAdsOffer hook
-    * major: consolidate duplicated source types
-    * patch: add new properties to PlayerInterface
-    * patch: expose getSeekingMatrixPreviewByTime in Video interface
-    * major: delete deprecated useBetOffer hook
-    * major: rework of source types
-    * major: make useChannelSource deprecated
-
-* 6.0.1
-    * patch: fix dependency to @tivio/common
-
-* 6.0.0
-    * major: delete usePlayerEvent hook
-    * major: replace uri attributes in types with url
-    * major: delete uri attributes from types
-    * minor: add purchase expiration to PurchaseEndpointPayload
-    * minor: add optional videoId parameter to useOrganizationSubscription hook
-
-* 5.0.2
-    * patch: export hook useChannelSource
-
-* 5.0.1
-    * patch: move changelog
-
-* 5.0.0
-    * major: upgrade to React 18, change react and react-dom peer dependencies to 17.x || 18.x
-    * major: fix typing for useReferralInfo, now correctly showing that `null` can be returned
-    * major: fix typing for `WebRowProps.onTileClick`, now correctly showing that `null` can be accepted
-    * minor: add analytics
-    * minor: add getSourceUrl function to video and tv channel types
-    * minor: add uri property to tv channel type
-    * minor: add useChannelSource to hooks
-
-* 4.5.0
-    * minor: extend PurchaseEndpointPayload type with purchase previousStatus and newStatus fields
-
-* 4.4.1
-    * patch: added waitForTags param in useSearch hook for videos
-
-* 4.4.0
-    * minor: PrimaryButton component props type set to any for now
-    * patch: isPurchasableAsVoucher added to PurchasableMonetization
-    * patch: voucherPurchase flag added to purchase overlays
-    * patch: item added to MonetizationsSelectOverlayData
-    * minor: added hungarian language to `LangCode` enum
-
-* 4.3.0:
-    * minor: add GetPurchaseInfoResponse and PurchaseEndpointPayload to exported types
-    * minor: support for disabling purchase of specified subscriptions (new param in useOrganizationSubscriptions hook)
-    * minor: more specific PurchasableMonetization type usage instead of Monetization
-    * minor: monetization property deleted from Video type
-    * minor: monetization now has originalPrice and promotion properties available
-    * patch: remove not used OrganizationSubscriptionsContext, **this change requires bundle 3.20.0 or newer**
-
-* 4.2.0:
-    * minor: fix useSearch loading type
-    * patch: added italian language to `LangCode` enum
-
-* 4.1.0
-    * patch: added italian language to `LangCode` enum
-    * minor: fixed spanish language code in `LangCode` enum (`sp` -> `es`)
-    * minor: other misc type changes
-
-* 4.0.1
-    * patch: added setBundleVersion setter to bundle type
-    * patch: added setStorageManager setter to bundle type
-    * patch: `Purchase.isPurchased` is deprecated
-    * patch: fill `useSearch` field `hasNextPage` with proper value
-
-* 4.0.0
-    * minor: Types cleanup
-    * MAJOR: Remove deprecated and unused stuff
-        * auth
-            * changePassword
-            * changeUserPhoto
-            * removeUserPhoto
-            * getPurchasedVodsWithInitializedVideos
-            * initializeUser
-            * createFreePurchase
-        * components
-            * videoAdBanner
-        * getters
-            * getExportedConfig
-            * getChannelById
-            * getSectionById
-            * getWidgetById
-        * hooks
-            * useLastVideoByWidgetId
-            * useScreen
-            * useFreePurchase
-            * useWidget
-            * useChannel
-            * useSection
-            * useVideosInSection
-            * useSectionsInChannel
-            * useChannelsInWidget
-        * subscriptions
-            * subscribeToWidget
-            * subscribeToChannel
-            * subscribeToSection
-            * subscribeToVideosInSection
-            * subscribeToSectionsInChannel
-            * subscribeToChannelsInWidget
-            * subscribeToScreen
----
-_Versions <= v3.7.0 requires core-react-dom bundle < v3.0.0 (because sdk-react used some sdk API deleted in core-react-dom@4.0.0)_
-
-* 3.7.0
-    * minor: purchase contains created and updated
-
-* 3.6.3
-    * patch: improve README.md
-
-* 3.6.2
-    * patch: Fix types
-
-* 3.6.1
-    * patch: Fix README
-
-* 3.6.0
-    * minor: Update types
-
-* 3.5.2
-    * patch: All types are available again.
-
-* 3.5.1
-    * patch: remove incorrect dependency (@tivio/types)
-
-* 3.5.0
-    * minor: Types change - Video.price and Video.detailedPrice can be null
-    * minor: Types change - Video.cover is marked as deprecated
-
-* 3.4.0
-    * minor: more precise type for errors in usePurchaseRecovery and usePurchaseRecovery
-    * patch: jsdocs for usePurchaseRecovery and usePurchaseRecovery
-    * minor: inviteCodeReset in useApplyInviteCode
-    * minor: Reset forgotten password
-    * minor: Consolidating monetization logic
-* 3.3.2
-    * patch: Adding new optional parameters (where, orderBy) to useTaggedVideos hook
-* 3.3.1
-    * patch: Fixed types of `setUser`
-* 3.3.0
-    * minor: Add getPlayerCapabilities to getters.
-    * patch: Added option to log out via `setUser(null)`, requires @tivio/core-react-dom@2.17.9
-* 3.2.5
-    * patch: added recovery flag to QerkoPaymentInfo type
-    * patch: bundle.types changes - internal.components.WebVideoScreen
-    * patch: types changes - add new onBack prop to WebPlayerProps
-    * patch: Refactor useVideo hook, now uses hook from core-react
-* 3.2.4
-    * minor: added useApplyInviteCode
-    * minor: better errors from useVoucher
-* 3.2.3
-    * minor: added usePurchaseRecovery hook
-    * patch: deprecated `useLastVideoByWidgetId`
-* 3.2.2
-    * minor: useRowsInScreen, useItemsInRow, useTaggedVideos - hasNextPage and loading added to pagination
-    * minor: useRowsInScreen, useItemsInRow, useTaggedVideos - implementation moved to remote bundle
-    * patch: Fixed Tivio startup on Tizen 6
-    * minor: Added `forceCloudFnResolver` option
-* 3.2.1
-    * patch: fix of @tivio/common version
-* 3.2.0
-    * minor: Added `capabilitiesOptions` for finer configuration of device capabilities
-    * minor: tag names are returned in correct language (the one from tivio config); language value should be one from enum "LangCode"
-* 3.1.3
-    * patch: Hotfix made sure disabled Tivio does not break React Native
-* 3.1.2
-    * patch: Allow `conf` prop of `TivioProvider` to be `null` or `undefined` in order to turn off Tivio
-* 3.1.1
-    * patch: fixed `setUser()` crash when bundle fails to load
-* 3.1.0
-    * patch: `useAdSegment()` now returns null if no monetization is configured, ad segments are not managed in that situation
-    * minor: enriched `AdSegment` type from `useAdSegment()`
-    * minor: Added `setUser()` function for login and logout
-* 3.0.0
-    * minor: Added hook `useWatchWithoutAdsOffer` to trigger purchase dialog to "watch without ads", if available
-    * patch: fix peerDependency declaration for react, react-dom
-    * major: TivioProvider requires deviceCapabilities
-    * major: TivioProvider requires currency
-    * minor: add voucher support (see usePurchaseSubscription and useTransactionPayment hooks)
-    * minor: device limit support
-    * minor: drm (Widevine, PlayReady) support
-    * minor: watermarking support
-    * minor: add useSearch hook
-    * patch: price on video is 0 when purchased
-* 2.4.2
-    * patch: added back changelog
-* 2.4.1
-    * patch: improved doc about player wrapper
-* 2.4.0
-    * patch: improved Player wrapper types
-    * minor: added Tivio DOM events `tivio_key_input_handling_change`, `tivio_context_switch` and `tivio_request_goto`
-    * patch: added support for remote code on browsers that do not implement [indexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
-    * patch: added support for browsers that do not implement [indexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
-* 2.3.4
-    * patch: fix of usePurchaseSubscription not reactive
-* 2.3.3
-    * patch: fix of useUser not updating
-* 2.3.2
-    * patch: next app doesn't fail anymore due to "self is not defined"
-* 2.3.1
-    * patch: fix of @tivio/common dependency
-* 2.3.0
-    * minor: add useTaggedVideos that allows to fetch videos with given tags
-    * minor: add option to fetch tags (on hook useItemsInRow), useVideo always fetching videos tags
-* 2.2.1
-    * patch: disable Sentry when no config is supplied to `TivioProvider`
-* 2.2.0
-    * patch: reduced bundle size
-    * minor: disable Sentry when no config is supplied to `TivioProvider` or when Tivio is disabled `{ enable: false }`, or when Sentry is disabled via config `{ enableSentry: false }`
-* 2.1.5
-    * patch fix of `useVideosInSection` hook (fetching video's monetizations)
-* 2.1.4
-    * patch: fix re-rendering of `useAd` during non-skippable ads (requires core-react-dom@2.1.9)
-* 2.1.3
-    * patch: fix changelog
-* 2.1.2
-    * patch: Fixed exported types
-* 2.1.1
-    * patch: TivioWidget now correctly reports `false` via `onEnabled` callback when in invalid internal state
-* 2.1.0
-    * patch: fix of useItemsInRow hook
-    * patch: fix of useScreen hook
-    * add: useRowsInScreen hook
-* 2.0.3
-    * patch: fix of useItemsInRow hook
-* 2.0.2
-    * patch: screen and row IDs fixed
-        * `TivioBundle.subscriptions.subscribeToItemsInRow` now accepts user-defined ID via studio.tiv.io
-        * `TivioBundle.subscriptions.subscribeToScreen` now accepts user-defined ID via studio.tiv.io
-        * `Screen` and `Row` types returned by `useScreen()` return their user-defined IDs (`.id`) correctly
-* 2.0.1
-    * no changes
-* 2.0.0
-    * major: video.channelId can now be `string | null` used to be `string`
-    * minor: added data API and hooks for screens (screens, rows of screen and row items)
-        * hooks: `useScreen()`,  `useItemsInRow()`
-        * api: `TivioBundle.subscriptions.subscribeToScreen`,  `TivioBundle.subscriptions.subscribeToItemsInRow`
-* 1.3.6
-    * ?
-* 1.3.5
-    * minor: added WebPlayer props (canReplay, showMarkers, customShortcuts, enableKeyboardShortcuts, source.poster)
-* 1.3.4
-    * ...
-
 ## Installation
 
 Install @tivio/sdk-react along with its peer dependencies
@@ -503,9 +194,266 @@ function CustomPlayer() {
 }
 ```
 
-## Data hooks
+## JavaScript Methods for Rendering Players
+
+### renderWebPlayer
+
+The `renderWebPlayer` method allows you to render a Tivio player outside of React components. This is useful for scenarios where you need to integrate the player into non-React environments.
+
+The method is asynchronous and returns a VideoController instance that provides comprehensive control over playback.
+
+```typescript
+import { renderWebPlayer } from '@tivio/sdk-react'
+
+// Example usage
+const videoController = await renderWebPlayer(
+    document.getElementById('video-player'),
+    {
+        id: 'player-main',
+        source: 'videos/ID',
+    }
+)
+
+// Control playback
+videoController.play()
+videoController.pause()
+videoController.togglePause()
+
+// Seeking
+videoController.seekToAbsolutePosition(30000) // Seek to 30 seconds
+videoController.seekBy(5000) // Seek forward by 5 seconds
+videoController.seekToPercent(50) // Seek to 50% of video
+videoController.seekToLive() // Seek to live position (for live streams)
+
+// Volume control
+videoController.changeVolume(0.8) // Set volume to 80%
+videoController.volumeUp() // Increase volume by 5%
+videoController.volumeDown() // Decrease volume by 5%
+videoController.mute()
+videoController.unmute()
+videoController.toggleMute()
+
+// Get current source
+console.log('Current source:', videoController.currentSource)
+
+// Change source
+videoController.setSource('videos/newVideoId') // Change to a different video
+videoController.setSource('tvChannels/channelId') // Change to a TV channel
+videoController.setSource(null) // Stop playback
+
+// Event handling
+videoController.addEventListener('video_unit_ended', () => {
+    console.log('Video playback ended')
+})
+
+videoController.addEventListener('timeupdate', (currentTime) => {
+    console.log('Current time:', currentTime)
+})
+
+// Cleanup
+videoController.destroy()
+```
+
+#### VideoController Methods
+
+The VideoController returned by `renderWebPlayer` provides the following methods:
+
+**Playback Control:**
+- `play()` - Resume playback from paused state
+- `pause()` - Pause the current playback
+- `togglePause()` - Toggle between play and pause states
+- `replay()` - Replay the current video from the beginning
+- `retry()` - Retry playback if it failed to start
+
+**Seeking:**
+- `seekToAbsolutePosition(ms: number)` - Seek to absolute position in milliseconds
+- `seekBy(ms: number)` - Seek relative to current position
+- `seekToPercent(percentage: number)` - Seek to percentage of video duration
+- `seekToLive()` - Seek to live position (for live streams)
+
+**Volume Control:**
+- `changeVolume(value: number)` - Set volume (0-1)
+- `volumeUp()` - Increase volume by 5%
+- `volumeDown()` - Decrease volume by 5%
+- `mute()` - Mute audio
+- `unmute()` - Unmute audio
+- `toggleMute()` - Toggle mute state
+
+**Source Management:**
+- `setSource(source: WebPlayerProps['source'])` - Change the current source to a new one (updates player props)
+- `currentSource` - Currently playing source or null if no source is loaded
+
+#### Source Types
+
+The Tivio player supports different types of sources:
+
+**VOD_EXTERNAL** - External video-on-demand content from third-party URLs
+- Used for playing videos that are hosted outside of Tivio's infrastructure
+- Supports various streaming protocols (HLS, DASH, MP4)
+- Example usage:
+```typescript
+const externalSource = {
+    type: SourceType.VOD_EXTERNAL,
+    url: 'https://example.com/video.m3u8',
+    sourcePlayMode: SourcePlayMode.ON_DEMAND,
+    poster: 'https://example.com/poster.jpg',
+    name: 'External Video',
+    autoplay: false,
+    continuePositionMs: 10000, // Start at 10 seconds (optional)
+}
+```
+
+#### Source Play Modes
+
+The `sourcePlayMode` property determines how the content is played:
+
+- **ON_DEMAND** - Standard video playback with full seeking capabilities
+- **LIVE** - Live stream mode with no seeking
+- **HYBRID** - Combines LIVE with seeking
+
+#### Using setSource with VideoController
+
+The `setSource` method allows you to dynamically change what's playing:
+
+```typescript
+// Change to a different video
+videoController.setSource('videos/newVideoId')
+
+// Change to an external video
+videoController.setSource({
+    type: SourceType.VOD_EXTERNAL,
+    url: 'https://example.com/video.mpd',
+    sourcePlayMode: SourcePlayMode.ON_DEMAND,
+    name: 'External Video'
+})
+
+// Change to a TV channel
+videoController.setSource('tvChannels/channelId')
+
+// Stop playback
+videoController.setSource(null)
+```
 
-### useUser hook
+The `setSource` method is particularly useful for:
+- Play next
+- Implementing playlists
+- Dynamic content loading
+
+**Event Handling:**
+- `addEventListener(event: string, callback: (value: T) => void)` - Add event listener
+- `removeEventListener(event: string, callback: (value: T) => void)` - Remove event listener
+
+**Utility:**
+- `destroy()` - Destroy player and clean up resources
+
+#### Playback Events
+
+The VideoController emits various events that you can listen to:
+
+```typescript
+// Video state changes
+videoController.addEventListener('statechange', (state) => {
+    console.log('Player state:', state) // 'playing', 'paused', 'idle'
+})
+
+// Time updates
+videoController.addEventListener('timeupdate', (currentTime) => {
+    console.log('Current time:', currentTime)
+})
+
+// Video ended
+videoController.addEventListener('video_unit_ended', () => {
+    console.log('Video playback ended')
+})
+
+// Duration changes
+videoController.addEventListener('durationchange', (duration) => {
+    console.log('Video duration:', duration)
+})
+
+// Volume changes
+videoController.addEventListener('volumechange', ({ muted, volume }: { muted: boolean, volume: number }) => {
+    console.log('Volume changed:', { muted, volume })
+})
+
+// Buffering state
+videoController.addEventListener('bufferingchange', (isBuffering) => {
+    console.log('Buffering:', isBuffering)
+})
+
+// Errors
+videoController.addEventListener('error', (error) => {
+    console.error('Playback error:', error)
+})
+```
+
+## WebPlayerProps
+
+The `WebPlayerProps` interface defines the properties that can be passed to the Tivio WebPlayer component. Here's a comprehensive overview of available properties:
+
+### Required Properties
+
+- **`id`** (string): Unique identifier for the player instance. This is required and must be unique across your application.
+
+### Source Properties
+
+- **`source`** (optional): The video or channel source to play. Can be:
+  - `VideoPath` (string): Path to a video (e.g., "videos/VIDEO_ID")
+  - `ChannelPath` (string): Path to a TV channel (e.g., "tvChannels/CHANNEL_ID")
+  - `SourceParams` (object): Complex source parameters
+  - `null`: No source (player will be idle)
+
+### Callback Properties
+
+- **`onEnded`** (optional): Callback function called when video playback ends
+- **`onProgress`** (optional): Callback function for video progress events
+
+### Layout Properties
+
+- **`className`** (optional): CSS class name for the player container
+- **`isSameSizeAsParent`** (optional): If `true`, the player will inherit the width and height of its parent element
+
+### Playback Control Properties
+
+- **`autoplay`** (optional, default: `false`): Whether to start playback automatically. Note that autoplay may be blocked by browsers before user interaction
+- **`canReplay`** (optional, default: `true`): Whether to show replay functionality
+- **`doNotSaveWatchPosition`** (optional): If `true`, the player won't save the watch position
+- **`disablePlayNext`** (optional): If `true`, the player won't automatically play the next video when current video ends
+
+### Visual Properties
+
+- **`showMarkers`** (optional, default: `false`): Whether to show video markers
+- **`markerColor`** (optional): Color for video markers (CSS color value)
+- **`showTvStreamType`** (optional): Whether to show TV stream type indicator
+- **`showCookiesSettings`** (optional): Whether to show cookies settings
+- **`showOsd`** (optional, default: `true`): Whether to show the On-Screen Display (OSD)
+- **`showBufferingSpinner`** (optional, default: `true`): Whether to show buffering spinner
+
+### Audio Properties
+
+- **`isMutedByDefault`** (optional): If `true`, the player starts muted but can be unmuted
+
+### Keyboard Shortcuts Properties
+
+- **`enableKeyboardShortcuts`** (optional, default: `true`): Whether to enable keyboard shortcuts
+- **`customShortcuts`** (optional): Custom keyboard shortcuts configuration:
+  ```typescript
+  {
+    toggleFullscreen: number[],    // Array of key codes
+    togglePause: number[],
+    toggleMute: number[],
+    jumpForward: number[],
+    jumpBack: number[],
+    volumeUp: number[],
+    volumeDown: number[]
+  }
+  ```
+
+### Ad Block Properties
+
+- **`checkAdBlock`** (optional, default: `false`): Whether to check for ad blockers and show warnings
+
+## Data hooks
 Gets information about current user.
 
 ```ts