@tivio/sdk-react 5.0.0 → 5.0.1

package/README.md.bak

@@ -0,0 +1,497 @@
+# @tivio/sdk-react
+
+@tivio/sdk-react provides everything which is necessary (components, data hooks etc.) to build a custom React application
+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
+
+* 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
+```sh
+npm i react@17 react-dom@17 @tivio/sdk-react
+# or
+yarn add react@17 react-dom@17 @tivio/sdk-react
+```
+
+## Initialization
+
+Put Tivio Provider at the top level of your application:
+
+``` javascript
+import { TivioProvider } from '@tivio/sdk-react'
+
+const config = {
+    secret: 'XXXXXXXXXX',
+}
+
+function App({children}) {
+    return (
+        <TivioProvider conf={config}>
+           {children}
+        </TivioProvider>
+    )
+}
+```
+
+## Authentication
+
+A logged-in user can access more features, such as making purchases. In order to authenticate a user with Tivio, use the `setUser()` method.
+
+Verification of the user against 3rd party auth servers is implemented per customer.
+
+```typescript
+import { setUser } from '@tivio/sdk-react'
+
+// Log in
+
+// Payload is specific per customer
+// A common use-case is sending an auth token inside the payload, which Tivio can use to verify the user
+await setUser('userId', { token: 'xxx'})
+
+// Log out
+await setUser(null)
+```
+
+## Player
+
+You can choose whether you will use complete player component provided by Tivio or you will wrap your existing player
+with the Tivio Player Wrapper.
+
+### Tivio Player component
+
+```javascript
+import { useTivioData } from '@tivio/sdk-react'
+
+const PlayerExample = () => {
+    const bundle = useTivioData()
+
+    if (!bundle?.components?.WebPlayer) {
+        return <p>Loading...</p>
+    }
+
+    return (
+        <>
+            <div
+                style={{
+                    height: 720,
+                    width: 1280,
+                }}
+            >
+                <bundle.components.WebPlayer
+                    id="player1"
+                    className="web-player"
+                    source="/videos/xxxxxxxxxxxxxxxxxxxx" // dynamically change this based on video you want to play
+                />
+            </div>
+        </>
+    )
+}
+```
+
+### Player wrapper
+
+Player wrapper is the way how you can enhance your video player with Tivio features, such Tivio Ads. In order to start
+using Tivio player wrapper, wrap your player methods with PlayerWrapper, start using PlayerWrapper's methods
+instead of them to control your playback and start sending player events to Tivio PlayerWrapper.
+
+#### Wrap your player methods with Tivio player wrapper
+
+```javascript
+import { useTivioReadyData } from '@tivio/sdk-react'
+
+function CustomPlayer() {
+    const tivioData = useTivioReadyData()
+
+    useEffect(() => {
+        if (tivioData) {
+            // If your app uses multiple player instances, use different Tivio player wrapper for each
+            // distinguished by playerWrapperId
+            const playerWrapper = tivio.getPlayerWrapper({ playerWrapperId: 'PLAYER_1' })
+
+            // Pass your player methods to Tivio player wrapper
+            playerWrapper.register({
+                play: () => {
+                    // Un-pause your player
+                },
+                pause: () => {
+                    // Pause your player
+                },
+                seekTo: (ms: number) => {
+                    // Seek to position in milliseconds using your player
+                },
+                setSource: (videoSource: InputSource) => {
+                    // Send this video source to your player to load it
+                },
+            })
+        }
+    }, [tivioData])
+}
+```
+
+#### Start using Tivio player wrapper methods to control playback
+
+```javascript
+    // Channel source metadata, such as channel name, epg start and epg end are necessary
+    // for TV ad segment detection and application of ad strategies
+    const source = new ChannelSource(
+        'https://channel_prima_hd.m3u8',
+        {
+            // here put any additional metadata, for your use.
+            // This object will not be touched by Tivio
+        },
+        // channel name
+        // can also be prima hd, prima_hd, prima, Prima, PRIMA, etc.
+        // we will normalize it to snake case and add '_hd' if necessary
+        'Prima HD',
+        // program name
+        'Dr. House',
+        // description (optional)
+        'Episode about Dr. House being awesome',
+        // EPG start
+        new Date('2021-12-10T12:00:00'),
+        // EPG end
+        new Date('2021-12-10T13:40:00'),
+    )
+
+    // Send source to player
+    playerWrapper.onSourceChanged(source)
+
+    // Un-pause player
+    playerWrapper.play()
+
+    // Pause player
+    playerWrapper.pause()
+}
+```
+
+#### Start reporting player events to Tivio
+
+```javascript
+    // Report that source is playing
+    playerWrapper.onStateChanged('playing')
+
+    // Report that source is paused
+    playerWrapper.onStateChanged('paused')
+
+    // Report that source stopped playing
+    playerWrapper.onPlaybackEnded()
+    playerWrapper.onStateChanged('idle')
+
+    // Report video progress
+    playerWrapper.onTimeChanged(ms)
+}
+```
+
+#### Start reporting playback-related errors to Tivio
+
+```javascript
+    // Report that video failed to load (e.g. due to a wrong URI)
+    playerWrapper.onLoadError(new Error('video failed to load'))
+
+    // Report that video failed during playback (e.g. due to bad connection, corrupted chunks of stream video etc.)
+    // This type of error may be auto-recoverable
+    playerWrapper.onError(new Error('playback error'))
+}
+```
+
+## Data hooks
+
+### useUser hook
+Gets information about current user.
+
+```ts
+useUser: () => {
+    user: User | null
+    error: string | null
+    isInitialized: boolean
+}
+```
+
+### useRowsInScreen hook
+Gets array of Rows objects of specific screen and subscribes to its changes.
+
+```ts
+/**
+ * Use rows in screen
+ * @param screenId - screen id (from studio.tiv.io)
+ * @param options - subscription options
+ */
+useRowsInScreen: (screenId: string, options?: PaginationOptions) => {
+    pagination: PaginationInterface<Row> | null
+    error: Error | null
+}
+```
+
+### useItemsInRow hook
+Gets array of row items objects of specific row and subscribes to its changes.
+
+```ts
+/**
+ * Use row items
+ * @param rowId - row ID
+ * @param options - subscription options
+ */
+useItemsInRow: (rowId: string, options?: SubscribeToItemsInRowOptions) => {
+    pagination: PaginationInterface<ItemsInRow> | null
+    error: Error | null
+}
+```
+
+### useVideo hook
+
+Gets Video object and subscribes to its changes.
+
+```ts
+/**
+ * Use video
+ * @param videoId - video id
+ */
+useVideo: (videoId: string) => {
+    error: string | null;
+    data: Video | null;
+}
+```
+
+### useTaggedVideos hook
+Gets videos with given tag IDs.
+
+```ts
+/**
+ * Use tagged videos
+ * @param tagIds - tag ids
+ * @param options - subscription options
+ * @public
+ */
+useTaggedVideos: (tagIds: string[], options?: SubscribeToItemsInRowOptions) => {
+    pagination: PaginationInterface<Video> | null
+    error: Error | null
+}
+```

package/dist/index.d.ts

@@ -2450,7 +2450,6 @@ export declare type TivioHooks = {
         applyInviteCode: (code: string) => void;
         inviteCodeReset: () => void;
     };
-    useChannelSource: UseChannelSource;
 };
 
 /**
@@ -2510,6 +2509,7 @@ export declare type TivioInternalHooks = {
         loading: boolean;
     });
     useTvChannel: UseTvChannel;
+    useChannelSource: UseChannelSource;
     useUser: () => {
         user: User | null;
         error: string | null;