@tivio/sdk-react 10.0.0 → 10.1.0

package/CHANGELOG.md

@@ -1,4 +1,8 @@
 ## Changelog
+* 10.1.0
+  * minor: expose useInteractiveWidget, usePollWidget, useQuizWidget, useRemoteController
+  * minor: expose useRemoteController hook
+
 * 10.0.0
   * major: **BREAKING** new purchase flow — `PurchasableMonetization.frequency` is now a structured object (`{ unit, value, title }`) instead of a plain `MONETIZATION_FREQUENCY` enum value. Replace `frequency === MONETIZATION_FREQUENCY.X` checks with `frequency?.unit === MONETIZATION_FREQUENCY.X`. The new `value` and `title` fields make it easier to render recurring prices (e.g. "9.99 € / 3 months") without hand-rolling the period label.
   * major: **BREAKING** `TileProps` renamed to `TileComponentProps` to avoid a naming collision with the `TileProps` exported from row types

package/README.md

@@ -8,9 +8,9 @@ settings in the administration of Tivio Studio while having the freedom to build
 
 Install @tivio/sdk-react along with its peer dependencies
 ```sh
-npm i react@17 react-dom@17 @tivio/sdk-react
+npm i react@18 react-dom@18 @tivio/sdk-react
 # or
-yarn add react@17 react-dom@17 @tivio/sdk-react
+yarn add react@18 react-dom@18 @tivio/sdk-react
 ```
 
 ## Initialization

package/README.md.bak

@@ -8,9 +8,9 @@ settings in the administration of Tivio Studio while having the freedom to build
 
 Install @tivio/sdk-react along with its peer dependencies
 ```sh
-npm i react@17 react-dom@17 @tivio/sdk-react
+npm i react@18 react-dom@18 @tivio/sdk-react
 # or
-yarn add react@17 react-dom@17 @tivio/sdk-react
+yarn add react@18 react-dom@18 @tivio/sdk-react
 ```
 
 ## Initialization

package/dist/index.d.ts

@@ -649,6 +649,52 @@ export declare interface BannerProps {
  */
 export declare type BannerPropsPartial = Partial<BannerProps>;
 
+/**
+ * Fields and methods common to every interactive widget (quiz, poll, …).
+ * Parameterized over the concrete answer type, state type, and scene type so
+ * more specialized widget interfaces can narrow each axis independently.
+ */
+export declare interface BaseInteractiveWidget<TAnswer extends BaseQuestionAnswer = QuestionAnswer, TState extends InteractiveWidgetState = InteractiveWidgetState, TScene extends InteractiveWidgetScene = InteractiveWidgetScene> {
+    readonly id: string;
+    readonly name: string;
+    readonly path: string;
+    readonly type: InteractiveWidgetType;
+    readonly status: InteractiveWidgetStatus;
+    readonly questionsCount: number;
+    readonly currentAnswerId?: string;
+    readonly currentState: TState;
+    /**
+     * State delayed for end users, used to toggle scenes just like in OBS / host view.
+     */
+    readonly currentStateWithDelay: InteractiveWidgetCurrentStateWithDelay<TState>;
+    readonly currentQuestion: CurrentQuestion<TAnswer> | null;
+    readonly answers?: TAnswer[];
+    readonly questionIndex?: number;
+    readonly isSubmitted?: boolean;
+    readonly userRole: InteractiveWidgetRole;
+    readonly scenes: TScene[];
+    readonly activeScene: TScene | null;
+    readonly theme?: InteractiveWidgetTheme;
+    /**
+     * @remarks Always `false` for `PollWidget` — kept on the base to minimize
+     * disruption to existing consumers.
+     */
+    readonly isWaitingForStart: boolean;
+    answerQuestion(answerId: string): void;
+    submitAnswer(request: Pick<SubmitAnswerRequest, 'answerOptionId' | 'answerText'>): Promise<void>;
+    verifyJoinCode(joinCode: string, shouldJoinPlayer?: boolean): Promise<boolean>;
+    destroy(): void;
+}
+
+/**
+ * Fields shared by both quiz and poll answers.
+ */
+export declare interface BaseQuestionAnswer {
+    id: string;
+    answer: Translation;
+    status?: AnswerStatus;
+}
+
 /**
  * Base row interface with common fields
  * @public
@@ -1313,13 +1359,17 @@ export declare type CurrencyLowerCase = 'czk' | 'eur' | 'usd' | 'pln';
  */
 export declare const CurrencyToTitle: Record<Currency, string>;
 
-export declare interface CurrentQuestion {
+/**
+ * Generic "current question" shape, parameterized by answer type.
+ * Use `QuizQuestion` / `PollQuestion` for concrete forms.
+ */
+export declare interface CurrentQuestion<TAnswer extends BaseQuestionAnswer = QuestionAnswer> {
     id: string;
     question: Translation;
-    answers?: QuestionAnswer[];
+    answers?: TAnswer[];
     index?: number;
     endTimestampMs?: number;
-    status?: QuizGameStatus;
+    status?: InteractiveWidgetStatus;
 }
 
 export declare type CurrentQuestionScene = InteractiveWidgetSceneBase<InteractiveWidgetSceneTemplateType.CURRENT_QUESTION>;
@@ -2449,41 +2499,10 @@ export declare interface IndexedVideo extends IndexedObject {
 
 export declare type IntegrationType = 'discord' | 'patreon';
 
-export declare interface InteractiveWidget<T extends InteractiveWidgetScene = InteractiveWidgetScene> {
-    readonly id: string;
-    readonly name: string;
-    readonly path: string;
-    readonly currentQuestion: CurrentQuestion | null;
-    readonly status: QuizGameStatus;
-    readonly questionsCount: number;
-    readonly currentAnswerId?: string;
-    readonly currentState: InteractiveWidgetState;
-    /**
-     * State delayed for end users, which is used to toggle scenes just like in OBS and host view
-     */
-    readonly currentStateWithDelay: InteractiveWidgetCurrentStateWithDelay;
-    readonly answers?: QuestionAnswer[];
-    readonly questionIndex?: number;
-    readonly isSubmitted?: boolean;
-    readonly leaderboard: LeaderboardGroupItem | null;
-    readonly highlightedUsersIds: string[];
-    readonly userRole: QuizGameRole;
-    readonly secondsToAnswer: number;
-    readonly scenes: T[];
-    readonly activeScene: T | null;
-    readonly theme?: InteractiveWidgetTheme;
-    readonly showCountdown: boolean;
-    readonly lastQuestionTopScorers: LeaderboardPlayer[];
-    readonly questionRepository: QuestionRepository;
-    readonly isWaitingForStart: boolean;
-    answerQuestion(answerId: string): void;
-    submitAnswer(request: Pick<SubmitAnswerRequest, 'answerOptionId' | 'answerText'>): Promise<void>;
-    verifyJoinCode(joinCode: string, shouldJoinPlayer?: boolean): Promise<boolean>;
-    destroy(): void;
-}
+export declare type InteractiveWidget<TScene extends InteractiveWidgetScene = InteractiveWidgetScene> = QuizWidget<TScene> | PollWidget<TScene>;
 
-export declare interface InteractiveWidgetCurrentStateWithDelay {
-    state: InteractiveWidgetState;
+export declare interface InteractiveWidgetCurrentStateWithDelay<TState extends InteractiveWidgetState = InteractiveWidgetState> {
+    state: TState;
     enteredAt: Date;
 }
 
@@ -2497,6 +2516,27 @@ export declare enum InteractiveWidgetDisplayComponent {
     AD_VAST = "adVast"
 }
 
+export declare interface InteractiveWidgetGroupStats {
+    answerPercentages: Record<string, number>;
+    averageScore: number;
+    correctAnswersRatio: number;
+}
+
+export declare enum InteractiveWidgetGroupType {
+    HIGHLIGHTED_PLAYERS = "HIGHLIGHTED_PLAYERS",
+    /** Participants playing in Offline mode */
+    LOCAL_PLAYERS = "LOCAL_PLAYERS",
+    ALL = "ALL",
+    PARTY = "PARTY"
+}
+
+export declare enum InteractiveWidgetRole {
+    OBS = "OBS",
+    HOST = "HOST",
+    PLAYER = "PLAYER",
+    LOCAL_PLAYER = "LOCAL_PLAYER"
+}
+
 export declare type InteractiveWidgetScene = CurrentQuestionScene | LeaderboardScene | QRCodeScene | AdBannerScene | PlayersScene | NoGraphicsScene | CountdownScene;
 
 export declare interface InteractiveWidgetSceneBase<TType extends InteractiveWidgetSceneTemplateType> {
@@ -2554,6 +2594,16 @@ export declare enum InteractiveWidgetState {
     RESET_GAME = "ResetGame"
 }
 
+export declare enum InteractiveWidgetStatus {
+    /**
+     * Waiting to start the quiz / question
+     */
+    WAITING = "WAITING",
+    IN_PROGRESS = "IN_PROGRESS",
+    IN_BETWEEN_QUESTIONS = "IN_BETWEEN_QUESTIONS",
+    DONE = "DONE"
+}
+
 export declare interface InteractiveWidgetTheme {
     palette: Record<string, string>;
     components: {
@@ -2563,6 +2613,11 @@ export declare interface InteractiveWidgetTheme {
 
 declare type InteractiveWidgetThemeKey = InteractiveWidgetDisplayComponent | `${InteractiveWidgetDisplayComponent.CURRENT_QUESTION}${AnswerStatus}` | 'timeLeftBar';
 
+export declare enum InteractiveWidgetType {
+    POLL = "POLL",
+    QUIZ = "QUIZ"
+}
+
 /**
  * @public
  */
@@ -2589,6 +2644,15 @@ export declare type InternalConfig = SdkReactConfig & {
     forceCloudFnResolver?: boolean;
 };
 
+/**
+ * Subset of `BaseInteractiveWidget` methods that are intentionally **not**
+ * advertised on the SDK hook return types (`useInteractiveWidget`,
+ * `useQuizWidget`, `usePollWidget`). These methods still exist at runtime and
+ * are used by internal `core-react-dom` UI / server flows — they're just hidden
+ * from external SDK consumers, which should only call `submitAnswer`.
+ */
+export declare type InternalInteractiveWidgetMethods = 'answerQuestion' | 'verifyJoinCode' | 'changeState';
+
 /**
  * @public
  */
@@ -2743,7 +2807,7 @@ export declare interface LastMessage {
 export declare interface LeaderboardGroupItem {
     groupPath?: string;
     groupName?: string;
-    type: QuizGameGroupType;
+    type: InteractiveWidgetGroupType;
     /**
      * Consists of top 3 players of the group (global or private team)
      * the player's rank in the group
@@ -4370,6 +4434,22 @@ export declare enum PlayerWrapperEventType {
  */
 export declare type PlayerWrapperEventTypeType = `${PlayerWrapperEventType}`;
 
+export declare type PollQuestion = CurrentQuestion<PollQuestionAnswer>;
+
+export declare interface PollQuestionAnswer extends BaseQuestionAnswer {
+    votes?: number;
+}
+
+/**
+ * A poll-flavored interactive widget. No scoring / leaderboard / countdown — just
+ * "here's a question, here are the vote counts". Uses a narrower state machine.
+ */
+export declare interface PollWidget<TScene extends InteractiveWidgetScene = InteractiveWidgetScene> extends BaseInteractiveWidget<PollQuestionAnswer, PollWidgetState, TScene> {
+    readonly type: InteractiveWidgetType.POLL;
+}
+
+export declare type PollWidgetState = InteractiveWidgetState.IDLE | InteractiveWidgetState.CURRENT_QUESTION | InteractiveWidgetState.LEADERBOARD | InteractiveWidgetState.RESET_GAME | InteractiveWidgetState.NEXT_STATE;
+
 /**
  * @public
  */
@@ -5035,13 +5115,7 @@ export declare interface QerkoTransaction {
 
 export declare type QRCodeScene = InteractiveWidgetSceneBase<InteractiveWidgetSceneTemplateType.QR_CODE>;
 
-export declare interface QuestionAnswer {
-    id: string;
-    answer: Translation;
-    isCorrect?: boolean;
-    votes?: number;
-    status?: AnswerStatus;
-}
+export declare type QuestionAnswer = QuizQuestionAnswer | PollQuestionAnswer;
 
 export declare enum QuestionEvents {
     NEW_QUESTION = "new_question",
@@ -5059,7 +5133,7 @@ export declare interface QuestionRepository {
     readonly selectedAnswerId: string | undefined;
     isSubmitted: boolean;
     isSubmitting: boolean;
-    setCurrentQuestion: (question: CurrentQuestion | null, role: QuizGameRole, secondsToAnswer: number, shouldEnterAtTimestampMs?: number, shouldAdjustEndTimestampMs?: boolean) => void;
+    setCurrentQuestion: (question: CurrentQuestion | null, role: InteractiveWidgetRole, secondsToAnswer: number, shouldEnterAtTimestampMs?: number, shouldAdjustEndTimestampMs?: boolean) => void;
     selectAnswer: (answerId: string | undefined) => void;
     setShowCountdown: (showCountdown: boolean) => void;
     reset: () => void;
@@ -5073,41 +5147,28 @@ export declare type QuestionRepositoryEventMap = {
     [QuestionEvents.QUESTION_TIMEOUT]: (question: CurrentQuestion | null) => void;
 };
 
-export declare interface QuizGameGroupStats {
-    answerPercentages: Record<string, number>;
-    averageScore: number;
-    correctAnswersRatio: number;
-}
-
-export declare enum QuizGameGroupType {
-    HIGHLIGHTED_PLAYERS = "HIGHLIGHTED_PLAYERS",
-    /** Participants playing in Offline mode */
-    LOCAL_PLAYERS = "LOCAL_PLAYERS",
-    ALL = "ALL",
-    PARTY = "PARTY"
-}
+export declare type QuizQuestion = CurrentQuestion<QuizQuestionAnswer>;
 
-export declare enum QuizGameRole {
-    OBS = "OBS",
-    HOST = "HOST",
-    PLAYER = "PLAYER",
-    LOCAL_PLAYER = "LOCAL_PLAYER"
+export declare interface QuizQuestionAnswer extends BaseQuestionAnswer {
+    isCorrect?: boolean;
+    votes?: number;
 }
 
-export declare enum QuizGameStatus {
-    /**
-     * Waiting to start the quiz / question
-     */
-    WAITING = "WAITING",
-    IN_PROGRESS = "IN_PROGRESS",
-    IN_BETWEEN_QUESTIONS = "IN_BETWEEN_QUESTIONS",
-    DONE = "DONE"
+/**
+ * A quiz-flavored interactive widget. Adds scoring, leaderboard, and countdown
+ * concepts on top of the base, and narrows answers to `QuizQuestionAnswer`.
+ */
+export declare interface QuizWidget<TScene extends InteractiveWidgetScene = InteractiveWidgetScene> extends BaseInteractiveWidget<QuizQuestionAnswer, QuizWidgetState, TScene> {
+    readonly type: InteractiveWidgetType.QUIZ;
+    readonly leaderboard: LeaderboardGroupItem | null;
+    readonly lastQuestionTopScorers: LeaderboardPlayer[];
+    readonly highlightedUsersIds: string[];
+    readonly secondsToAnswer: number;
+    readonly showCountdown: boolean;
+    readonly questionRepository: QuestionRepository;
 }
 
-export declare enum QuizGameType {
-    POLL = "POLL",
-    QUIZ = "QUIZ"
-}
+export declare type QuizWidgetState = InteractiveWidgetState;
 
 /**
  * @public
@@ -5224,6 +5285,11 @@ export declare interface RemoteControlPairPayload {
     profileId: string;
 }
 
+export declare interface RemoteControlPairResponse {
+    sessionId: string;
+    videoId: string;
+}
+
 export declare interface RemoteControlPlaybackControlPayload {
     sessionId: string;
     videoId: string;
@@ -5605,7 +5671,7 @@ declare type SceneMetadata<TType extends InteractiveWidgetSceneTemplateType> = T
 } : TType extends InteractiveWidgetSceneTemplateType.LEADERBOARD ? {
     highlightedPlayers: LeaderboardPlayer[];
     topPlayers: LeaderboardPlayer[];
-    stats?: QuizGameGroupStats;
+    stats?: InteractiveWidgetGroupStats;
 } : TType extends InteractiveWidgetSceneTemplateType.QR_CODE ? Record<Extract<SceneMetadataKeys[TType], string>, string> : TType extends InteractiveWidgetSceneTemplateType.AD_BANNER ? Record<Extract<SceneMetadataKeys[TType], string>, string> : TType extends InteractiveWidgetSceneTemplateType.PLAYERS ? Record<Extract<SceneMetadataKeys[TType], string>, string> : object;
 
 export declare interface SceneMetadataKeys {
@@ -5758,6 +5824,13 @@ export declare type SdkReactConfig = Omit<TivioConfig, 'language'> & {
     language?: LangCode;
 };
 
+/**
+ * Narrows away `InternalInteractiveWidgetMethods` from any concrete widget
+ * type. Distributes over discriminated unions so `SDKWidget<InteractiveWidget>`
+ * stays a union of `SDKWidget<QuizWidget> | SDKWidget<PollWidget>`.
+ */
+export declare type SDKWidget<T> = T extends unknown ? Omit<T, InternalInteractiveWidgetMethods> : never;
+
 /**
  * @public
  * @deprecated sections are no longer used.
@@ -7050,6 +7123,22 @@ export declare type TivioHooks = {
     };
     useChannelSource: UseChannelSource;
     useTvChannel: UseTvChannel;
+    useInteractiveWidget: (widgetPath: string | undefined, isObs?: boolean) => {
+        widget: SDKWidget<InteractiveWidget> | null;
+        isLoading: boolean;
+        error: Error | null;
+    };
+    useQuizWidget: (widgetPath: string | undefined, isObs?: boolean) => {
+        widget: SDKWidget<QuizWidget> | null;
+        isLoading: boolean;
+        error: Error | null;
+    };
+    usePollWidget: (widgetPath: string | undefined, isObs?: boolean) => {
+        widget: SDKWidget<PollWidget> | null;
+        isLoading: boolean;
+        error: Error | null;
+    };
+    useRemoteController: UseRemoteController;
 };
 
 /**
@@ -7690,6 +7779,18 @@ export declare type UseEpisodesResult = {
     hasMoreEpisodes: boolean;
 };
 
+/**
+ * Load the interactive widget at `widgetPath` via the remote Tivio bundle.
+ * Returns the union widget (`QuizWidget | PollWidget`); narrow
+ * on `widget.type` to access type-specific fields. Prefer `useQuizWidget` /
+ * `usePollWidget` when you know the type up-front.
+ */
+export declare const useInteractiveWidget: (widgetPath: string | undefined, isObs?: boolean) => {
+    widget: SDKWidget<InteractiveWidget> | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+
 /**
  * @public
  */
@@ -7782,6 +7883,12 @@ export declare const useOrganizationSubscriptions: (onlyPurchasableSubscriptions
     subscriptions: PurchasableMonetization[];
 };
 
+export declare const usePollWidget: (widgetPath: string | undefined, isObs?: boolean) => {
+    widget: Omit<PollWidget<InteractiveWidgetScene>, InternalInteractiveWidgetMethods> | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+
 /**
  * Is used to mark purchase in recovery state as PAID.
  *
@@ -7803,6 +7910,12 @@ export declare function usePurchaseRecovery(): {
  */
 export declare const usePurchaseSubscription: (monetizationId: string, voucher?: NewVoucher) => QerkoTransaction;
 
+export declare const useQuizWidget: (widgetPath: string | undefined, isObs?: boolean) => {
+    widget: Omit<QuizWidget<InteractiveWidgetScene>, InternalInteractiveWidgetMethods> | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+
 /**
  * @public
  */
@@ -7944,6 +8057,58 @@ export declare interface UseReactionsOptions {
     onError?: (error: Error) => void;
 }
 
+/**
+ * @public
+ */
+export declare type UseRemoteController = (options?: UseRemoteControllerOptions) => UseRemoteControllerResult;
+
+export declare const useRemoteController: UseRemoteController;
+
+/**
+ * @public
+ */
+export declare interface UseRemoteControllerOptions {
+    sessionId?: string;
+    videoId?: string;
+}
+
+/**
+ * @public
+ */
+export declare type UseRemoteControllerPlaybackControlPayload = Pick<RemoteControlPlaybackControlPayload, 'playback' | 'activeVideoId'> & Partial<Pick<RemoteControlPlaybackControlPayload, 'sessionId' | 'videoId'>>;
+
+/**
+ * @public
+ */
+export declare type UseRemoteControllerPlayHighlightPayload = Pick<RemoteControlPlayHighlightPayload, 'activeVideoId' | 'replay'> & Partial<Pick<RemoteControlPlayHighlightPayload, 'sessionId' | 'videoId'>>;
+
+/**
+ * @public
+ */
+export declare interface UseRemoteControllerResult {
+    session: UserStreamingSessionFieldInterface | null;
+    sessionId: string | null;
+    videoId: string | null;
+    activeContentId: string | null;
+    isInitialized: boolean;
+    isSignedIn: boolean;
+    isLoading: boolean;
+    error: Error | null;
+    resetError: () => void;
+    pairDevice: (payload: RemoteControlPairPayload) => Promise<RemoteControlPairResponse>;
+    unpairDevice: (payload?: Partial<RemoteControlUnpairPayload>) => Promise<boolean | string>;
+    selectCamera: (payload: UseRemoteControllerSelectCameraPayload) => Promise<boolean | string>;
+    playHighlight: (payload: UseRemoteControllerPlayHighlightPayload) => Promise<boolean | string>;
+    playbackControl: (payload: UseRemoteControllerPlaybackControlPayload) => Promise<boolean | string>;
+    getSourceUrl: (payload: RemoteControlGetSourceUrlPayload) => Promise<RemoteControlGenerateSourceResponse>;
+    remoteControl: <TResponse = RemoteControlGenerateSourceResponse | boolean | string>(payload: RemoteControlRequest) => Promise<TResponse>;
+}
+
+/**
+ * @public
+ */
+export declare type UseRemoteControllerSelectCameraPayload = Pick<RemoteControlSelectCameraPayload, 'activeVideoId'> & Partial<Pick<RemoteControlSelectCameraPayload, 'sessionId' | 'videoId'>>;
+
 export declare enum UserGroup {
     ALL = "all",
     FREE = "free",