@tivio/sdk-react 10.0.0 → 10.1.0

package/dist/sdk-react.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
@@ -1355,13 +1401,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>;
@@ -2843,41 +2893,10 @@ export declare interface InputOptions {
 
 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;
 }
 
@@ -2891,6 +2910,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> {
@@ -2948,6 +2988,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: {
@@ -2957,6 +3007,11 @@ export declare interface InteractiveWidgetTheme {
 
 declare type InteractiveWidgetThemeKey = InteractiveWidgetDisplayComponent | `${InteractiveWidgetDisplayComponent.CURRENT_QUESTION}${AnswerStatus}` | 'timeLeftBar';
 
+export declare enum InteractiveWidgetType {
+    POLL = "POLL",
+    QUIZ = "QUIZ"
+}
+
 /**
  * @public
  */
@@ -2983,6 +3038,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
  */
@@ -3137,7 +3201,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
@@ -4774,6 +4838,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
  */
@@ -5439,13 +5519,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",
@@ -5463,7 +5537,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;
@@ -5477,41 +5551,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
@@ -5628,6 +5689,11 @@ export declare interface RemoteControlPairPayload {
     profileId: string;
 }
 
+export declare interface RemoteControlPairResponse {
+    sessionId: string;
+    videoId: string;
+}
+
 export declare interface RemoteControlPlaybackControlPayload {
     sessionId: string;
     videoId: string;
@@ -6018,7 +6084,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 {
@@ -6171,6 +6237,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.
@@ -7549,6 +7622,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;
 };
 
 /**
@@ -8197,6 +8286,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
  */
@@ -8289,6 +8390,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.
  *
@@ -8310,6 +8417,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
  */
@@ -8451,6 +8564,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",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tivio/sdk-react",
-    "version": "10.0.0",
+    "version": "10.1.0",
     "main": "dist/index.js",
     "typings": "dist/index.d.ts",
     "source": "src/index.ts",
@@ -39,7 +39,7 @@
         "@material-ui/core": "^4.11.2",
         "@material-ui/icons": "^4.11.2",
         "@sentry/browser": "^6.1.0",
-        "@tivio/common": "1.1.132",
+        "@tivio/common": "1.1.135",
         "dayjs": "^1.11.0",
         "es7-object-polyfill": "^1.0.1",
         "firebase": "8.10.1",