@tivio/sdk-react 10.2.1 → 11.0.0

package/dist/index.d.ts

@@ -675,15 +675,53 @@ export declare interface BaseInteractiveWidget<TAnswer extends BaseQuestionAnswe
     readonly type: InteractiveWidgetType;
     readonly status: InteractiveWidgetStatus;
     readonly questionsCount: number;
+    /**
+     * Id of the answer option the current user picked for {@link currentQuestion}.
+     *
+     * @remarks
+     * This is **optimistic local state**, not a server-confirmed value. It is set
+     * immediately when `submitAnswer` is called (before the backend responds) so the
+     * UI can reflect the choice without delay. For quizzes it is reverted to its
+     * previous value if the submission fails; for **polls** it is intentionally kept
+     * on failure (polls favor a smooth voting experience over per-vote precision), so
+     * the user keeps seeing their pick for this session. It is scoped to this
+     * device/session and resets when the question changes — it does not reflect a vote
+     * made by the same user elsewhere.
+     */
     readonly currentAnswerId?: string;
+    /**
+     * The state to render **right now** for the audience. Render your scene off this.
+     *
+     * @remarks
+     * It is kept in sync with the viewer's delayed video stream: it switches to the
+     * next state exactly when that state becomes active, not before. To show a preview
+     * of what's coming (e.g. a "voting opens in N s" screen), read
+     * {@link currentStateWithDelay}'s `state` together with {@link secondsUntilStateChange}.
+     */
     readonly currentState: TState;
     /**
-     * State delayed for end users, used to toggle scenes just like in OBS / host view.
+     * The **upcoming** state and the absolute time it becomes active (`enteredAt`).
+     *
+     * @remarks
+     * While a transition is pending, `state` is already the next state whereas
+     * {@link currentState} still reports what's on screen. Use this together with
+     * {@link secondsUntilStateChange} to render a countdown / preview of the next state.
      */
     readonly currentStateWithDelay: InteractiveWidgetCurrentStateWithDelay<TState>;
     readonly currentQuestion: CurrentQuestion<TAnswer> | null;
     readonly answers?: TAnswer[];
     readonly questionIndex?: number;
+    /**
+     * Whether the current user has submitted an answer for {@link currentQuestion}.
+     *
+     * @remarks
+     * This is **optimistic local state**, not a server-confirmed value. It flips to
+     * `true` the moment `submitAnswer` is called (before the backend responds). For
+     * quizzes it is reverted to `false` if the submission fails; for **polls** it is
+     * intentionally kept `true` on failure, so the user keeps seeing their vote as
+     * submitted for this session. It is scoped to this device/session and resets when
+     * the question changes.
+     */
     readonly isSubmitted?: boolean;
     readonly userRole: InteractiveWidgetRole;
     readonly scenes: TScene[];
@@ -694,6 +732,27 @@ export declare interface BaseInteractiveWidget<TAnswer extends BaseQuestionAnswe
      * disruption to existing consumers.
      */
     readonly isWaitingForStart: boolean;
+    /**
+     * Delay (in seconds) applied to the audience-facing
+     * state relative to the live state, so end users see widget transitions in sync
+     * with their delayed video stream.
+     */
+    readonly audienceDelayInSeconds: number;
+    /**
+     * Number of users currently active on the video this widget belongs to.
+     * Sourced live from the video document (`activeUsers.value`).
+     */
+    readonly activeUsers?: number;
+    /**
+     * Whole seconds until the {@link currentStateWithDelay} state becomes active for
+     * the audience; `0` when no transition is pending.
+     *
+     * @remarks
+     * Use this for countdown UIs instead of computing time yourself — it is already
+     * synced to server time. Reading it in render is safe (it updates at most once per
+     * second). Derive "is a transition pending?" as `secondsUntilStateChange > 0`.
+     */
+    readonly secondsUntilStateChange: number;
     answerQuestion(answerId: string): void;
     submitAnswer(request: Pick<SubmitAnswerRequest, 'answerOptionId' | 'answerText'>): Promise<void>;
     verifyJoinCode(joinCode: string, shouldJoinPlayer?: boolean): Promise<boolean>;
@@ -1473,7 +1532,12 @@ export declare enum CustomerId {
     MYSTICO = "MYSTICO",
     MORAVEC = "MORAVEC",
     JAN_TUNA = "JAN_TUNA",
-    PODNIKATELSKY_MINDSET = "PODNIKATELSKY_MINDSET"
+    PODNIKATELSKY_MINDSET = "PODNIKATELSKY_MINDSET",
+    PETR_HOFMAN = "PETR_HOFMAN",
+    NCSLM = "NCSLM",
+    DOUCKO_S_ROBINEM = "DOUCKO_S_ROBINEM",
+    KVIZ_PLEASE = "KVIZ_PLEASE",
+    TALKSHOW_KOTAK_LIVE = "TALKSHOW_KOTAK_LIVE"
 }
 
 export declare interface CustomScript {
@@ -4475,7 +4539,7 @@ export declare interface PollWidget<TScene extends InteractiveWidgetScene = Inte
     readonly type: InteractiveWidgetType.POLL;
 }
 
-export declare type PollWidgetState = InteractiveWidgetState.IDLE | InteractiveWidgetState.CURRENT_QUESTION | InteractiveWidgetState.LEADERBOARD | InteractiveWidgetState.RESET_GAME | InteractiveWidgetState.NEXT_STATE;
+export declare type PollWidgetState = InteractiveWidgetState.IDLE | InteractiveWidgetState.CURRENT_QUESTION | InteractiveWidgetState.RESOLVED_QUESTION | InteractiveWidgetState.RESET_GAME | InteractiveWidgetState.NEXT_STATE;
 
 /**
  * @public
@@ -5165,7 +5229,9 @@ export declare interface QuestionRepository {
     readonly selectedAnswerId: string | undefined;
     isSubmitted: boolean;
     isSubmitting: boolean;
-    setCurrentQuestion: (question: CurrentQuestion | null, role: InteractiveWidgetRole, secondsToAnswer: number, shouldEnterAtTimestampMs?: number, shouldAdjustEndTimestampMs?: boolean) => void;
+    setCurrentQuestion: (question: CurrentQuestion | null, role: InteractiveWidgetRole, 
+    /** Time limit for the question. Omit/undefined means no timer (e.g. polls). */
+    secondsToAnswer: number | undefined, shouldEnterAtTimestampMs?: number, shouldAdjustEndTimestampMs?: boolean) => void;
     selectAnswer: (answerId: string | undefined) => void;
     setShowCountdown: (showCountdown: boolean) => void;
     reset: () => void;