@tivio/sdk-react 10.3.0 → 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[];
@@ -705,6 +743,16 @@ export declare interface BaseInteractiveWidget<TAnswer extends BaseQuestionAnswe
      * 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>;
@@ -1485,7 +1533,11 @@ export declare enum CustomerId {
     MORAVEC = "MORAVEC",
     JAN_TUNA = "JAN_TUNA",
     PODNIKATELSKY_MINDSET = "PODNIKATELSKY_MINDSET",
-    PETR_HOFMAN = "PETR_HOFMAN"
+    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 {