@monterosa/sdk-interact-kit 2.0.0-rc.1 → 2.0.0-rc.3

package/dist/core/connection_health/index.d.ts

@@ -11,11 +11,17 @@ import { Unsubscribe } from '@monterosa/sdk-util';
 import { ConnectionHealth, ConnectionHealthState } from './public-types';
 /**
  * Returns {@link ConnectionHealth | connection health} instance
+ *
+ * @param sdk - The SDK instance to monitor
+ * @returns The connection health instance.
  */
 declare function getConnectionHealth(sdk?: MonterosaSdk): Promise<ConnectionHealth>;
 /**
  * Adds an observer for when
- * {@link ConnectionHealth.state | connection health state} changed
+ * {@link ConnectionHealth | connection health state} changed
+ *
+ * @param connectionHealth - The instance to observe
+ * @param callback - Called with the new state
  */
 declare function onConnectionHealthState(connectionHealth: ConnectionHealth, callback: (state: ConnectionHealthState) => void): Unsubscribe;
 export { ConnectionHealthState, ConnectionHealth } from './public-types';

package/dist/core/connection_health/public-types.d.ts

@@ -26,7 +26,7 @@ export declare enum ConnectionHealthState {
     Ok = "ok",
     /**
      * The client is either trying to establish a connection but failing, or
-     * the client has been explicetily {@link @monterosa/sdk-connect-kit#disconnect() | disconnected}
+     * the client has been explicitly {@link @monterosa/sdk-connect-kit#disconnect() | disconnected}
      */
     Error = "error"
 }

package/dist/core/element/api.d.ts

@@ -15,7 +15,10 @@ import { Answer, AnswerValue } from './answer';
  */
 declare const getElementMemoized: (...args: any[]) => Promise<InteractElement | null>;
 /**
- * Returns an element of a specific event by its id
+ * Returns an Element of a specific Event by its id.
+ *
+ * @param event - The Event that owns the Element
+ * @param id - The Element identifier
  */
 declare function getElement(event: InteractEvent, id: string): Promise<InteractElement | null>;
 /**
@@ -23,11 +26,14 @@ declare function getElement(event: InteractEvent, id: string): Promise<InteractE
  */
 declare const getElementsMemoized: (...args: any[]) => Promise<InteractElement[]>;
 /**
- * Returns the list of elements published in a specific event
+ * Returns the list of Elements published in a specific Event
+ *
+ * @param event - The Event to fetch Elements for
+ * @returns The published Elements, sorted oldest first.
  */
 declare function getElements(event: InteractEvent): Promise<InteractElement[]>;
 /**
- * Submits an element answer as a spread of options indices
+ * Submits an Element answer as a spread of options indices
  *
  * @example
  * ```javascript
@@ -35,12 +41,12 @@ declare function getElements(event: InteractEvent): Promise<InteractElement[]>;
  * answer(element, 0, 2);
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param indices - Spread of options indices (starting with 0) to vote for
  */
 declare function answer(element: InteractElement, ...indices: number[]): void;
 /**
- * Submits an element answer as an array of options indices
+ * Submits an Element answer as an array of options indices
  *
  * @example
  * ```javascript
@@ -48,12 +54,12 @@ declare function answer(element: InteractElement, ...indices: number[]): void;
  * answer(element, [0, 2]);
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param arrayOfIndices - Array of options indices (starting with 0) to vote for
  */
 declare function answer(element: InteractElement, arrayOfIndices: number[]): void;
 /**
- * Submits an element answer as a spread of answer values
+ * Submits an Element answer as a spread of answer values
  *
  * @example
  * ```javascript
@@ -64,12 +70,12 @@ declare function answer(element: InteractElement, arrayOfIndices: number[]): voi
  * );
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param answerValues - Spread of answer values to vote for
  */
 declare function answer(element: InteractElement, ...answerValues: AnswerValue[]): void;
 /**
- * Submits an element answer as an array of answer values
+ * Submits an Element answer as an array of answer values
  *
  * @example
  * ```javascript
@@ -80,12 +86,12 @@ declare function answer(element: InteractElement, ...answerValues: AnswerValue[]
  * ]);
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param arrayOfAnswerValues - Array of answer values to vote for
  */
 declare function answer(element: InteractElement, arrayOfAnswerValues: AnswerValue[]): void;
 /**
- * Submits an element answer as an Answer instance
+ * Submits an Element answer as an Answer instance
  *
  * @example
  * ```javascript
@@ -97,7 +103,7 @@ declare function answer(element: InteractElement, arrayOfAnswerValues: AnswerVal
  * answer(element, value);
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param answerObject - Array of answer values to vote for
  */
 declare function answer(element: InteractElement, answerObject: Answer): void;
@@ -105,7 +111,7 @@ declare function answer(element: InteractElement, answerObject: Answer): void;
  * Validates user's answer as a spread of options indices and
  * throws {@link @monterosa/sdk-util#MonterosaError%20class | error} with one of the
  * {@link AnswerError | error code} if the answer doesn't match
- * elements constraints
+ * Element's constraints
  *
  *
  * @example
@@ -117,7 +123,7 @@ declare function answer(element: InteractElement, answerObject: Answer): void;
  * }
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param indices - Spread of options indices (starting with 0) to vote for
  */
 declare function validateAnswer(element: InteractElement, ...indices: number[]): void;
@@ -125,7 +131,7 @@ declare function validateAnswer(element: InteractElement, ...indices: number[]):
  * Validates user's answer as an array of options indices and
  * throws {@link @monterosa/sdk-util#MonterosaError%20class | error} with one of the
  * {@link AnswerError | error code} if the answer doesn't match
- * elements constraints
+ * Element's constraints
  *
  * @example
  * ```javascript
@@ -136,7 +142,7 @@ declare function validateAnswer(element: InteractElement, ...indices: number[]):
  * }
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param arrayOfIndices - Array of options indices (starting with 0) to vote for
  */
 declare function validateAnswer(element: InteractElement, arrayOfIndices: number[]): void;
@@ -144,7 +150,7 @@ declare function validateAnswer(element: InteractElement, arrayOfIndices: number
  * Validates user's answer as a spread of answer values and
  * throws {@link @monterosa/sdk-util#MonterosaError%20class | error} with one of the
  * {@link AnswerError | error code} if the answer doesn't match
- * elements constraints
+ * Element's constraints
  *
  * @example
  * ```javascript
@@ -158,7 +164,7 @@ declare function validateAnswer(element: InteractElement, arrayOfIndices: number
  * }
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param answerValues - Spread of answer values to vote for
  */
 declare function validateAnswer(element: InteractElement, ...answerValues: AnswerValue[]): void;
@@ -166,7 +172,7 @@ declare function validateAnswer(element: InteractElement, ...answerValues: Answe
  * Validates user's answer  as an array of answer values and
  * throws {@link @monterosa/sdk-util#MonterosaError%20class | error} with one of the
  * {@link AnswerError | error code} if the answer doesn't match
- * elements constraints
+ * Element's constraints
  *
  * @example
  * ```javascript
@@ -180,7 +186,7 @@ declare function validateAnswer(element: InteractElement, ...answerValues: Answe
  * }
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param arrayOfAnswerValues - Array of answer values to vote for
  */
 declare function validateAnswer(element: InteractElement, arrayOfAnswerValues: AnswerValue[]): void;
@@ -188,7 +194,7 @@ declare function validateAnswer(element: InteractElement, arrayOfAnswerValues: A
  * Validates user's answer as an Answer instance and
  * throws {@link @monterosa/sdk-util#MonterosaError%20class | error} with one of the
  * {@link AnswerError | error code} if the answer doesn't match
- * elements constraints
+ * Element's constraints
  *
  * @example
  * ```javascript
@@ -203,31 +209,46 @@ declare function validateAnswer(element: InteractElement, arrayOfAnswerValues: A
  * }
  * ```
  *
- * @param element - An element instance
+ * @param element - An Element instance
  * @param answerObject - Array of answer values to vote for
  */
 declare function validateAnswer(element: InteractElement, answerObject: Answer): void;
 /**
- * Adds an observer for when {@link InteractElement.results | element results}
- * are updated
+ * Adds an observer for when
+ * {@link InteractElement | Element results} are updated
+ *
+ * @param element - The Element to observe
+ * @param callback - Called when results are updated
  */
 declare function onElementResults(element: InteractElement, callback: () => void): Unsubscribe;
 /**
- * Adds an observer for when {@link InteractElement.state | element state}
- * changed
+ * Adds an observer for when
+ * {@link InteractElement | Element state} changed
+ *
+ * @param element - The Element to observe
+ * @param callback - Called when the state changes
  */
 declare function onElementStateChanged(element: InteractElement, callback: () => void): Unsubscribe;
 /**
- * Adds an observer for when {@link InteractElement.fields | element's data}
- * is updated
+ * Adds an observer for when
+ * {@link InteractElement | Element fields} are updated
+ *
+ * @param event - The Event containing the Elements
+ * @param callback - Called with the updated Element
  */
 declare function onElementUpdated(event: InteractEvent, callback: (element: InteractElement) => void): Unsubscribe;
 /**
- * Adds an observer for when a new element is published
+ * Adds an observer for when a new Element is published
+ *
+ * @param event - The Event to observe
+ * @param callback - Called with the published Element
  */
 declare function onElementPublished(event: InteractEvent, callback: (element: InteractElement) => void): Unsubscribe;
 /**
- * Adds an observer for when an element is revoked
+ * Adds an observer for when an Element is revoked
+ *
+ * @param event - The Event to observe
+ * @param callback - Called with the revoked Element
  */
 declare function onElementRevoked(event: InteractEvent, callback: (element: InteractElement) => void): Unsubscribe;
 export { getElement, getElementMemoized, getElements, getElementsMemoized, answer, validateAnswer, onElementResults, onElementStateChanged, onElementUpdated, onElementPublished, onElementRevoked, };

package/dist/core/element/public-types.d.ts

@@ -15,13 +15,21 @@ import { Answer } from './answer';
  * vote() or validateAnswer() functions.
  */
 export declare enum AnswerError {
+    /** Selected option index is out of range. */
     OptionIndexOutOfRange = "out_of_range",
+    /** Fewer options selected than the minimum required. */
     BelowMinVoteOptions = "below_min_vote_options",
+    /** More options selected than the maximum allowed. */
     AboveMaxVoteOptions = "above_max_vote_options",
+    /** User has exceeded the maximum votes allowed. */
     AboveMaxVotesPerUser = "above_max_per_user",
+    /** A single option received more votes than allowed. */
     AboveMaxVotesPerOption = "above_max_per_option",
+    /** Attempted to vote on a non-interactive element. */
     VotedOnNonInteractiveElement = "non_interactive_element",
+    /** Attempted to vote on a closed element. */
     VotedOnClosedElement = "closed_element",
+    /** No vote value was provided. */
     EmptyVote = "empty_vote"
 }
 export declare const AnswerErrorMessages: {
@@ -35,35 +43,38 @@ export declare const AnswerErrorMessages: {
     empty_vote: (indices: string) => string;
 };
 /**
- * The ElementState represents the potential states an element is in.
+ * The ElementState represents the potential states an Element is in.
  */
 export declare enum ElementState {
     /**
      * Element is opened and active. The user can vote if
-     * element is `interactive`
+     * the Element is `interactive`
      */
     Opened = "opened",
     /**
      * Element is closed and the user can no longer vote for
-     * `interactive` elements
+     * `interactive` Elements
      */
     Closed = "closed"
 }
 /**
- * An instance of
- * {@link https://products.monterosa.co/mic/core-concepts/elements | Monterosa / Interaction Cloud Element}
- * that holds all of its information.
+ * Represents an interactive Element such as a poll,
+ * prediction, or trivia question. Obtain via
+ * {@link getElements} or {@link getElement}.
  *
- * Elements are interactive components such as Polls, Predictions or Trivia
- * questions which have a range of configuration fields such as duration,
- * publish time, question, answers, etc. Also developer can add a custom set of
- * fields of various types. Elements are triggered to appear at a certain
- * time and process both the appearance of the content, the way it behaves,
- * and the data which is sent back from the audience.
+ * @remarks
+ * Elements are interactive components with configuration
+ * fields such as duration, publish time, question, answers,
+ * etc. Developers can add custom fields of various
+ * types via the
+ * {@link https://products.monterosa.co/mic/developer-guides/app-spec/elements-spec | app's Element spec}.
  *
- * Elements configured through the
- * {@link https://products.monterosa.co/mic/developer-guides/app-spec/elements-spec | app's element spec}
- * where developer can configure the list of elements and its custom fields.
+ * Elements are triggered to appear at a certain time and
+ * process both the appearance of the content, the way it
+ * behaves, and the data sent back from the audience.
+ *
+ * See {@link https://products.monterosa.co/mic/core-concepts/elements | Elements} in
+ * the platform documentation for more details.
  */
 export interface InteractElement extends Emitter {
     /**
@@ -75,32 +86,32 @@ export interface InteractElement extends Emitter {
      */
     state: ElementState;
     /**
-     * Basic type of the element
+     * Basic type of the Element
      */
     type: ElementType;
     /**
      * Returns `content type` of a custom Element if any is set in
-     * the elements spec. Otherwise returns the basic `type`.
+     * the Element spec. Otherwise returns the basic `type`.
      */
     contentType: ElementType | string;
     /**
-     * Returns the element publish time as UNIX time in seconds.
+     * Returns the Element publish time as UNIX time in seconds.
      */
     publishedAt: number;
     /**
-     * Returns the element publish time as ISO string.
+     * Returns the Element publish time as ISO string.
      */
     publishedAtIso: string;
     /**
-     * Returns the element update as UNIX time in seconds.
+     * Returns the Element update as UNIX time in seconds.
      */
     updatedAt: number;
     /**
-     * Returns the element update time as ISO string.
+     * Returns the Element update time as ISO string.
      */
     updatedAtIso: string;
     /**
-     * Returns the total duration in seconds of the element.
+     * Returns the total duration in seconds of the Element.
      */
     duration: number;
     /**
@@ -121,7 +132,7 @@ export interface InteractElement extends Emitter {
      */
     fields: Record<string, unknown>;
     /**
-     * Returns `true` if the user can vote for the element
+     * Returns `true` if the user can vote for the Element
      */
     interactive: boolean;
     /**
@@ -169,7 +180,7 @@ export interface InteractElement extends Emitter {
      */
     maxVotesPerUser: number | null;
     /**
-     * Returns element results if they exist. Otherwise, returns `null`.
+     * Returns Element results if they exist. Otherwise, returns `null`.
      *
      * @example
      * ```javascript
@@ -202,13 +213,13 @@ export interface InteractElement extends Emitter {
     /** @internal */
     showResultsMode: ShowResultsMode | null;
     /**
-     * Returns `true` if results present and the state of the element satisfies
+     * Returns `true` if results present and the state of the Element satisfies
      * reveal mode. Otherwise, returns `false`.
      */
     canShowResults: boolean;
     /**
      * Returns `true` if the user voted and `false` if not. The user answer
-     * could be retrieved by calling {@link InteractElement.userAnswer} getter.
+     * could be retrieved by calling {@link InteractElement | userAnswer} getter.
      */
     hasBeenAnswered: boolean;
     /**

package/dist/core/element/types.d.ts

@@ -8,39 +8,39 @@
  */
 import { Localised } from '../../types';
 /**
- * Describes element types
+ * Describes Element types
  */
 export declare enum ElementType {
     /**
-     * Data element
+     * Data Element
      */
     Data = "data",
     /**
-     * Poll element
+     * Poll Element
      */
     Poll = "poll",
     /**
-     * Regular poll element
+     * Regular poll Element
      */
     RegularPoll = "rpoll",
     /**
-     * Diametric poll element
+     * Diametric poll Element
      */
     DiametricPoll = "dpoll",
     /**
-     * Emoting poll
+     * Emoting poll Element
      */
     EmotingPoll = "emo",
     /**
-     * Powerbar element
+     * Powerbar Element
      */
     Powerbar = "powerbar",
     /**
-     * Prediction element
+     * Prediction Element
      */
     Prediction = "prediction",
     /**
-     * Trivia element
+     * Trivia Element
      */
     Trivia = "trivia"
 }
@@ -53,11 +53,11 @@ export declare enum ShowResultsMode {
     Always = "always"
 }
 /**
- * A dataset that describes result for a single option
+ * A dataset that describes the result for a single option
  */
 export interface ElementResult {
     /**
-     * Total number of votes placed against the element's option
+     * Total number of votes placed against the Element's option
      */
     votes: number;
     /**

package/dist/core/event/api.d.ts

@@ -6,12 +6,13 @@ import { InteractProject } from '../project/public-types';
  */
 declare const getEventsMemoized: (...args: any[]) => Promise<InteractEvent[]>;
 /**
- * Returns all events in a project, including all active events and
- * past/upcoming events, according to Listings settings in Project Setup
+ * Returns all Events in a Project, including all active Events and
+ * past/upcoming Events, according to Listings settings in Project Setup
  * in Studio.
  *
- * @param project - A project instance. If not provided,
- *   the one from the default sdk will be fetched.
+ * @param project - A Project instance. If not provided,
+ *   the one from the default SDK will be fetched.
+ * @returns A promise that resolves to an array of Events.
  */
 declare function getEvents(project?: InteractProject): Promise<InteractEvent[]>;
 /**
@@ -19,66 +20,73 @@ declare function getEvents(project?: InteractProject): Promise<InteractEvent[]>;
  */
 declare const getEventMemoized: (...args: any[]) => Promise<InteractEvent | null>;
 /**
- * Returns an event by its id
+ * Returns an Event by its id
  *
- * @param id - Id of the event
- * @param project - A project instance. If not provided,
- *   the one from the default sdk will be fetched.
+ * @param id - Id of the Event
+ * @param project - A Project instance. If not provided,
+ *   the one from the default SDK will be fetched.
  *
- * @returns A an event associated with the provided id and project or null if no such
- *   event exists in the project.
+ * @returns The Event associated with the provided id,
+ *   or null if no such Event exists in the Project.
  */
 declare function getEvent(id: string, project?: InteractProject): Promise<InteractEvent | null>;
 /**
- * Adds an observer for when {@link InteractEvent.state | event state} changed
+ * Adds an observer for when
+ * {@link InteractEvent | Event state} changed
+ *
+ * @param event - The Event to observe
+ * @param callback - Called with the new state
  */
 declare function onEventState(event: InteractEvent, callback: (state: EventState) => void): Unsubscribe;
 /**
- * Adds an observer for when event's data changed
+ * Adds an observer for when Event's data changed
+ *
+ * @param event - The Event to observe
+ * @param callback - Called when the Event data changes
  */
 declare function onEventUpdated(event: InteractEvent, callback: () => void): Unsubscribe;
 /**
- * Adds an observer that is called when an event is added to listings.
+ * Adds an observer that is called when an Event is added to listings.
  *
  * @remarks
- * The following actions will result in adding an event to listings:
+ * The following actions will result in adding an Event to listings:
  *
- * - The start of the event in Studio
+ * - The start of the Event in Studio
  *
- * - The scheduling of a future event in Studio, when listings are configured
- *   to include future events in Project Settings.
+ * - The scheduling of a future Event in Studio, when listings are configured
+ *   to include future Events in Project Settings.
  *
- * - When a future event starts, a new future event may be added to the list,
- *   depending on the project configuration, to ensure a minimum number of
- *   upcoming events are always available.
- */
-declare function onEventAdded(project: InteractProject, callback: (event: InteractEvent) => void): Unsubscribe;
-/**
- * {@link onEventAdded} alias.
+ * - When a future Event starts, a new future Event may be added to the list,
+ *   depending on the Project configuration, to ensure a minimum number of
+ *   upcoming Events are always available.
  *
- * @deprecated Use the new {@link onEventAdded} function instead.
+ * @param project - The Project to observe
+ * @param callback - Called with the added Event
  */
-declare function onEventPublished(project: InteractProject, callback: (event: InteractEvent) => void): Unsubscribe;
+declare function onEventAdded(project: InteractProject, callback: (event: InteractEvent) => void): Unsubscribe;
 /**
- * Adds an observer that is called when an event is removed from listings.
+ * Adds an observer that is called when an Event is removed from listings.
  *
  * @remarks
- * The following actions will result in removing an event from listings:
+ * The following actions will result in removing an Event from listings:
  *
- * - The deletion of the event from Studio
+ * - The deletion of the Event from Studio
  *
- * - The change of listings confuguration in Project Settings to exclude future
- *   or past events.
+ * - The change of listings configuration in Project Settings to exclude future
+ *   or past Events.
  *
- * - The event is removed after a period of time since its completion. This period
+ * - The Event is removed after a period of time since its completion. This period
  *   is calculated as 45 seconds plus the Maximum allowed delay (configured in
  *   Project Settings in Studio).
+ *
+ * @param project - The Project to observe
+ * @param callback - Called with the removed Event
  */
 declare function onEventRemoved(project: InteractProject, callback: (event: InteractEvent) => void): Unsubscribe;
 /**
- * Returns the list of upcoming events
+ * Returns the list of upcoming Events
  */
 /**
- * Returns the list of active events
+ * Returns the list of active Events
  */
-export { getEvents, getEventsMemoized, getEvent, getEventMemoized, onEventState, onEventUpdated, onEventAdded, onEventPublished, onEventRemoved, };
+export { getEvents, getEventsMemoized, getEvent, getEventMemoized, onEventState, onEventUpdated, onEventAdded, onEventRemoved, };