@tivio/sdk-react 9.2.0 → 9.3.1

package/README.md

@@ -52,6 +52,301 @@ await setUser('userId', { token: 'xxx'})
 await setUser(null)
 ```
 
+### Create user with email and password
+
+Returns user's firebase uid or null if error occurs
+
+```typescript
+tivio.createUserWithEmailAndPassword(email: string, password: string, username: string, phoneNumber?: string | undefined): Promise<string | null>
+```
+**Example**
+```typescript
+await tivio.createUserWithEmailAndPassword('test@example.com', 'password', 'Fist & Last Name', '+420777123456')
+```
+
+### Sign in with email and password
+
+Returns user's firebase uid or null if error occurs
+
+```typescript
+tivio.signInWithEmailAndPassword(email: string, password: string): Promise<string | null>
+```
+**Example**
+```typescript
+await tivio.signInWithEmailAndPassword('test@example.com', 'password')
+```
+
+### Sign out
+
+```typescript
+tivio.signOut(): Promise<void>
+```
+
+### Reset password
+
+Send email with password reset link to the user with given email address
+
+```typescript
+tivio.resetPassword(email: string): Promise<void>
+```
+
+## User entity
+
+### Get user
+
+Returns user object or null if user is not authenticated
+
+```typescript
+tivio.getUser(): Promise<User | null>
+```
+
+### Essential Properties
+
+#### Basic Information
+- `id: string` - Unique Tivio user ID
+- `email?: string` - Email address
+- `name?: string` - Display name - could be nickname, first name and last name, etc.
+
+#### Authentication Status
+- `isSignedIn: boolean` - Whether the user is currently signed in
+- `isReady: boolean` - Whether user data is fully loaded
+- `isAnonymous: boolean` - Whether this is an anonymous user
+
+#### Content & Preferences
+- `purchases: Purchase[]` - Active purchases (excluding vouchers)
+
+#### User Profiles
+- `profiles: UserProfile[]` - Available user profiles (e.g. multiple people can use the same user account with different preferences)
+- `activeUserProfileId: string | null` - Currently active profile
+
+### Essential Methods
+
+#### Authentication
+```typescript
+changePassword(oldPassword: string, newPassword: string): Promise<void>
+```
+
+#### Profile Management
+
+#### Create user profile
+
+```typescript
+interface CreateUserProfileRequest {
+    /**
+     * Profile name - typically first name and last name, but users can fill in whatever they want.
+     */
+    name: string
+    /**
+     * Filled in values for user profile survey. See {@link OrganizationDocument} its configuration.
+     */
+    survey?: ProfileSurvey
+}
+interface ProfileSurvey {
+    gender?: Translation
+    age?: AgeRange
+}
+interface AgeRange {
+    from: number
+    /**
+     * If not set, we assume the range is not closed and {@property to} is set to infinity
+     * (there are no values to represent {@link Infinity} in firestore, so we use undefined instead).
+     */
+    to?: number
+    /**
+     * If set, we assume that this is a profile for kids only (e.g. 0-12).
+     * This value can only be `true` or not specified (undefined).
+     */
+    kidsOnly?: true
+}
+createUserProfile(request: CreateUserProfileRequest): Promise<void>
+```
+**Example**
+```typescript
+await user.createUserProfile({
+    name: 'John Doe',
+    survey: {
+        gender: {
+            cs: "Žena",
+            en: "Female",
+            sk: "Žena"
+        },
+        age: {
+            from: 18,
+            to: 24
+        }
+    }
+})
+```
+
+#### Set active user profile
+
+```typescript
+user.setActiveUserProfileId(profileId: string): void
+```
+
+#### Delete user profile
+
+```typescript
+user.deleteUserProfile(profileId: string): Promise<void>
+```
+
+## Content
+
+### Assets
+
+In order to obtain assets (images) from a Video or Tag, you can use these methods:
+
+#### Video or Tag
+- `video.cover` - cover image (landscape)
+- `video.banner` - banner image
+- `video.circled` - circled image
+- `video.detailBanner` - detail banner image (landscape)
+- `video.portrait` - portrait image (portrait)
+
+#### Tag only
+- `tag.bannerMobile` - banner image mobile
+
+__All of the assets fallback to type cover or empty string if cover is not available__
+
+### Get content based on user profile
+
+```typescript
+interface GetUserProfileDataOptions {
+    /**
+     * If true, the data will be returned for all user profiles.
+     * If false, the data will be returned only for the active user profile.
+     */
+    ignoreActiveUserProfile?: boolean
+}
+
+getFavorites(options?: GetUserProfileDataOptions): Promise<FavoriteWithData[]>
+getWatchPositions(options?: GetUserProfileDataOptions): Promise<WatchPositionWithData[]>
+getWatchHistory(options?: GetUserProfileDataOptions): Promise<WatchPositionWithData[]>
+```
+
+### Get user favorites
+
+```typescript
+interface FavoriteWithData {
+    content: Video | Tag
+    type: 'video' | 'tag' // Filtering by this type will set the content type to be Video or Tag
+    profileId?: string
+}
+
+getFavorites(options?: GetUserProfileDataOptions): Promise<FavoriteWithData[]>
+```
+**Example**
+```typescript
+const favorites = await user.getFavorites()
+favorites.forEach(favorite => {
+    console.log({
+        name: favorite.name,
+        cover: favorite.cover, // cover image (landscape)
+        portrait: favorite.portrait, // portrait image (portrait)
+    })
+})
+```
+
+### Get user watch positions
+
+```typescript
+interface WatchPositionWithData {
+    position: number
+    video: Video
+    tag?: Tag
+    episodeNumber?: number
+    seasonNumber?: number
+    videoDuration?: number
+}
+
+getWatchPositions(options?: GetUserProfileDataOptions): Promise<WatchPositionWithData[]>
+```
+**Example**
+```typescript
+const watchPositions = await user.getWatchPositions()
+watchPositions.forEach(watchPosition => {
+    console.log({
+        position: watchPosition.position, // watch position in milliseconds
+        videoName: watchPosition.video.name,
+        videoCover: watchPosition.video.cover,
+        tagName: watchPosition.tag?.name, // optional tag for series
+        episodeNumber: watchPosition.episodeNumber, // optional episode number
+        seasonNumber: watchPosition.seasonNumber, // optional season number
+        videoDuration: watchPosition.videoDuration, // optional video duration
+    })
+})
+```
+
+### Get user watch history
+
+```typescript
+getWatchHistory(options?: GetUserProfileDataOptions): Promise<WatchPositionWithData[]>
+```
+**Example**
+```typescript
+const watchHistory = await user.getWatchHistory()
+watchHistory.forEach(watchPosition => {
+    console.log({
+        position: watchPosition.position, // watch position in milliseconds
+        videoName: watchPosition.video.name,
+        videoCover: watchPosition.video.cover,
+        tagName: watchPosition.tag?.name, // optional tag for series
+        episodeNumber: watchPosition.episodeNumber, // optional episode number
+        seasonNumber: watchPosition.seasonNumber, // optional season number
+        videoDuration: watchPosition.videoDuration, // optional video duration
+    })
+})
+```
+
+### Add to/remove from favorites
+
+Simply call addToFavorites or removeFromFavorites on the Video or Tag.
+```typescript
+const video = await tivio.getVideoById('videoId')   
+await video.addToFavorites()
+await video.removeFromFavorites()
+
+const tag = await tivio.getTagById('tagId')
+await tag.addToFavorites()
+await tag.removeFromFavorites()
+
+// Remove a favorite from favorites
+const favorites = await tivio.getUser()?.favorites
+favorites[0]?.removeFromFavorites()
+```
+
+> Note: When user saves favorite without profileId, it will only be shown if the app doesn't have any active user profile.
+
+### Get screen by ID
+
+```typescript
+getScreenById(screenId: string): Promise<Screen | null>
+```
+
+### Get row by ID
+
+```typescript
+getRowById(rowId: string): Promise<Row | null>
+```
+
+### Get video by ID
+
+```typescript
+getVideoById(videoId: string): Promise<Video | null>
+```
+
+### Get tag by ID
+
+```typescript
+getTagById(tagId: string): Promise<Tag | null>
+```
+
+### Get TV Channel by ID
+
+```typescript
+getTvChannelById(tvChannelId: string): Promise<TvChannel | null>
+```
+
 ## Player
 
 You can choose whether you will use complete player component provided by Tivio or you will wrap your existing player

package/README.md.bak

@@ -52,6 +52,301 @@ await setUser('userId', { token: 'xxx'})
 await setUser(null)
 ```
 
+### Create user with email and password
+
+Returns user's firebase uid or null if error occurs
+
+```typescript
+tivio.createUserWithEmailAndPassword(email: string, password: string, username: string, phoneNumber?: string | undefined): Promise<string | null>
+```
+**Example**
+```typescript
+await tivio.createUserWithEmailAndPassword('test@example.com', 'password', 'Fist & Last Name', '+420777123456')
+```
+
+### Sign in with email and password
+
+Returns user's firebase uid or null if error occurs
+
+```typescript
+tivio.signInWithEmailAndPassword(email: string, password: string): Promise<string | null>
+```
+**Example**
+```typescript
+await tivio.signInWithEmailAndPassword('test@example.com', 'password')
+```
+
+### Sign out
+
+```typescript
+tivio.signOut(): Promise<void>
+```
+
+### Reset password
+
+Send email with password reset link to the user with given email address
+
+```typescript
+tivio.resetPassword(email: string): Promise<void>
+```
+
+## User entity
+
+### Get user
+
+Returns user object or null if user is not authenticated
+
+```typescript
+tivio.getUser(): Promise<User | null>
+```
+
+### Essential Properties
+
+#### Basic Information
+- `id: string` - Unique Tivio user ID
+- `email?: string` - Email address
+- `name?: string` - Display name - could be nickname, first name and last name, etc.
+
+#### Authentication Status
+- `isSignedIn: boolean` - Whether the user is currently signed in
+- `isReady: boolean` - Whether user data is fully loaded
+- `isAnonymous: boolean` - Whether this is an anonymous user
+
+#### Content & Preferences
+- `purchases: Purchase[]` - Active purchases (excluding vouchers)
+
+#### User Profiles
+- `profiles: UserProfile[]` - Available user profiles (e.g. multiple people can use the same user account with different preferences)
+- `activeUserProfileId: string | null` - Currently active profile
+
+### Essential Methods
+
+#### Authentication
+```typescript
+changePassword(oldPassword: string, newPassword: string): Promise<void>
+```
+
+#### Profile Management
+
+#### Create user profile
+
+```typescript
+interface CreateUserProfileRequest {
+    /**
+     * Profile name - typically first name and last name, but users can fill in whatever they want.
+     */
+    name: string
+    /**
+     * Filled in values for user profile survey. See {@link OrganizationDocument} its configuration.
+     */
+    survey?: ProfileSurvey
+}
+interface ProfileSurvey {
+    gender?: Translation
+    age?: AgeRange
+}
+interface AgeRange {
+    from: number
+    /**
+     * If not set, we assume the range is not closed and {@property to} is set to infinity
+     * (there are no values to represent {@link Infinity} in firestore, so we use undefined instead).
+     */
+    to?: number
+    /**
+     * If set, we assume that this is a profile for kids only (e.g. 0-12).
+     * This value can only be `true` or not specified (undefined).
+     */
+    kidsOnly?: true
+}
+createUserProfile(request: CreateUserProfileRequest): Promise<void>
+```
+**Example**
+```typescript
+await user.createUserProfile({
+    name: 'John Doe',
+    survey: {
+        gender: {
+            cs: "Žena",
+            en: "Female",
+            sk: "Žena"
+        },
+        age: {
+            from: 18,
+            to: 24
+        }
+    }
+})
+```
+
+#### Set active user profile
+
+```typescript
+user.setActiveUserProfileId(profileId: string): void
+```
+
+#### Delete user profile
+
+```typescript
+user.deleteUserProfile(profileId: string): Promise<void>
+```
+
+## Content
+
+### Assets
+
+In order to obtain assets (images) from a Video or Tag, you can use these methods:
+
+#### Video or Tag
+- `video.cover` - cover image (landscape)
+- `video.banner` - banner image
+- `video.circled` - circled image
+- `video.detailBanner` - detail banner image (landscape)
+- `video.portrait` - portrait image (portrait)
+
+#### Tag only
+- `tag.bannerMobile` - banner image mobile
+
+__All of the assets fallback to type cover or empty string if cover is not available__
+
+### Get content based on user profile
+
+```typescript
+interface GetUserProfileDataOptions {
+    /**
+     * If true, the data will be returned for all user profiles.
+     * If false, the data will be returned only for the active user profile.
+     */
+    ignoreActiveUserProfile?: boolean
+}
+
+getFavorites(options?: GetUserProfileDataOptions): Promise<FavoriteWithData[]>
+getWatchPositions(options?: GetUserProfileDataOptions): Promise<WatchPositionWithData[]>
+getWatchHistory(options?: GetUserProfileDataOptions): Promise<WatchPositionWithData[]>
+```
+
+### Get user favorites
+
+```typescript
+interface FavoriteWithData {
+    content: Video | Tag
+    type: 'video' | 'tag' // Filtering by this type will set the content type to be Video or Tag
+    profileId?: string
+}
+
+getFavorites(options?: GetUserProfileDataOptions): Promise<FavoriteWithData[]>
+```
+**Example**
+```typescript
+const favorites = await user.getFavorites()
+favorites.forEach(favorite => {
+    console.log({
+        name: favorite.name,
+        cover: favorite.cover, // cover image (landscape)
+        portrait: favorite.portrait, // portrait image (portrait)
+    })
+})
+```
+
+### Get user watch positions
+
+```typescript
+interface WatchPositionWithData {
+    position: number
+    video: Video
+    tag?: Tag
+    episodeNumber?: number
+    seasonNumber?: number
+    videoDuration?: number
+}
+
+getWatchPositions(options?: GetUserProfileDataOptions): Promise<WatchPositionWithData[]>
+```
+**Example**
+```typescript
+const watchPositions = await user.getWatchPositions()
+watchPositions.forEach(watchPosition => {
+    console.log({
+        position: watchPosition.position, // watch position in milliseconds
+        videoName: watchPosition.video.name,
+        videoCover: watchPosition.video.cover,
+        tagName: watchPosition.tag?.name, // optional tag for series
+        episodeNumber: watchPosition.episodeNumber, // optional episode number
+        seasonNumber: watchPosition.seasonNumber, // optional season number
+        videoDuration: watchPosition.videoDuration, // optional video duration
+    })
+})
+```
+
+### Get user watch history
+
+```typescript
+getWatchHistory(options?: GetUserProfileDataOptions): Promise<WatchPositionWithData[]>
+```
+**Example**
+```typescript
+const watchHistory = await user.getWatchHistory()
+watchHistory.forEach(watchPosition => {
+    console.log({
+        position: watchPosition.position, // watch position in milliseconds
+        videoName: watchPosition.video.name,
+        videoCover: watchPosition.video.cover,
+        tagName: watchPosition.tag?.name, // optional tag for series
+        episodeNumber: watchPosition.episodeNumber, // optional episode number
+        seasonNumber: watchPosition.seasonNumber, // optional season number
+        videoDuration: watchPosition.videoDuration, // optional video duration
+    })
+})
+```
+
+### Add to/remove from favorites
+
+Simply call addToFavorites or removeFromFavorites on the Video or Tag.
+```typescript
+const video = await tivio.getVideoById('videoId')   
+await video.addToFavorites()
+await video.removeFromFavorites()
+
+const tag = await tivio.getTagById('tagId')
+await tag.addToFavorites()
+await tag.removeFromFavorites()
+
+// Remove a favorite from favorites
+const favorites = await tivio.getUser()?.favorites
+favorites[0]?.removeFromFavorites()
+```
+
+> Note: When user saves favorite without profileId, it will only be shown if the app doesn't have any active user profile.
+
+### Get screen by ID
+
+```typescript
+getScreenById(screenId: string): Promise<Screen | null>
+```
+
+### Get row by ID
+
+```typescript
+getRowById(rowId: string): Promise<Row | null>
+```
+
+### Get video by ID
+
+```typescript
+getVideoById(videoId: string): Promise<Video | null>
+```
+
+### Get tag by ID
+
+```typescript
+getTagById(tagId: string): Promise<Tag | null>
+```
+
+### Get TV Channel by ID
+
+```typescript
+getTvChannelById(tvChannelId: string): Promise<TvChannel | null>
+```
+
 ## Player
 
 You can choose whether you will use complete player component provided by Tivio or you will wrap your existing player