@inappstory/js-sdk 3.6.4 → 3.6.5

package/dist/types/in-app-messaging/inAppMessaging.d.ts

@@ -1,48 +1,214 @@
+import {
+    IamNotFoundByEventError,
+    IamMessageOpenError,
+    IamOtherReaderIsOpenError,
+    IamShowOnlyIfLoadedError,
+    IamMessageLimitExceededError,
+    IamNotFoundByIdError,
+    IamFrequencyLimitError,
+    IamCheckDisplayTimeRangeError
+} from "./iamErrors";
+
+/**
+ * Enum representing different types of in-app messages
+ */
 export declare enum IamMessageType {
+    /**
+     * Message appears as a bottom sheet (slides up from bottom of screen)
+     */
     BottomSheet = 1,
+
+    /**
+     * Message appears as a modal dialog (centered on screen)
+     */
     Modal = 2,
+
+    /**
+     * Message takes up the full screen
+     */
     Fullscreen = 3
 }
 
+/**
+ * Interface representing an in-app message
+ */
 export interface IamMessage {
+    /**
+     * Unique identifier for the message
+     */
     id: number;
+
+    /**
+     * Name of the campaign this message belongs to
+     */
     campaignName: string;
+
+    /**
+     * Visual presentation type of the message
+     */
     type: IamMessageType;
 }
 
+/**
+ * Type mapping of all possible IAM events and their payload structures
+ */
 export type IamEvents = {
+    /**
+     * Triggered when a message is closed
+     */
     close: {
+        /**
+         * The message that was closed
+         */
         message: IamMessage;
     };
+
+    /**
+     * Triggered when a widget within a message fires an event
+     */
     widgetEvent: {
+        /**
+         * The message containing the widget
+         */
         message: IamMessage;
+
+        /**
+         * Name/type of the widget event
+         */
         name: string;
+
+        /**
+         * Additional data associated with the event
+         */
         data: Record<string, any>;
     };
+
+    /**
+     * Triggered when a button is clicked within a message
+     */
     clickOnButton: {
+        /**
+         * Unique identifier of the clicked button
+         */
         id: number;
+
+        /**
+         * Index position of the button
+         */
         index: number;
+
+        /**
+         * URL associated with the button (if any)
+         */
         url: string;
+
+        /**
+         * ID of the HTML element that was clicked
+         */
         elementId: string;
     };
 };
 
+/**
+ * Type definition for IAM event handlers
+ * @template Event - The event name (keyof IamEvents)
+ */
 export type IamEventHandler<Event extends keyof IamEvents> = (event: IamEvents[Event]) => void;
 
+/**
+ * Interface for the In-App Messaging service
+ */
 export interface InAppMessaging {
+    /**
+     * Gets the currently active/open message
+     */
     get activeMessage(): IamMessage | null;
+
+    /**
+     * Indicates whether messages have been loaded
+     */
     get isLoaded(): boolean;
+
+    /**
+     * Indicates whether messages are currently loading
+     */
     get isLoading(): boolean;
+
+    /**
+     * Indicates whether a message is currently open/visible
+     */
     get isOpened(): boolean;
 
+    /**
+     * Preloads messages for faster display later
+     * @param options - Optional configuration
+     * @param options.tags - Filter messages by tags
+     * @returns Promise resolving to array of loaded messages
+     */
     preload(options?: { tags?: string[] }): Promise<IamMessage[]>;
+
+    /**
+     * Displays a message by its ID
+     * @param messageId - The ID of the message to show
+     * @param options - Optional display configuration
+     * @param options.showOnlyIfLoaded - If true, only shows messages that were preloaded
+     * @returns Promise resolving to the displayed message
+     * @throws {IamNotFoundByIdError} If no message exists with this ID
+     * @throws {IamMessageOpenError} If this message is already open
+     * @throws {IamOtherReaderIsOpenError} If another reader is active
+     * @throws {IamShowOnlyIfLoadedError} If showOnlyIfLoaded=true but message wasn't preloaded
+     * @throws {IamMessageLimitExceededError} If message display limit was reached
+     */
     showMessageById(messageId: number | string, options?: { showOnlyIfLoaded?: boolean }): Promise<IamMessage>;
+
+    /**
+     * Displays a message associated with an event name
+     * @param eventName - The event name triggering the message
+     * @param options - Optional display configuration
+     * @param options.showOnlyIfLoaded - If true, only shows messages that were preloaded
+     * @param options.tags - Filter messages by tags
+     * @returns Promise resolving to the displayed message
+     * @throws {IamNotFoundByEventError} If no message exists for this event
+     * @throws {IamFrequencyLimitError} If message frequency limit was exceeded
+     * @throws {IamCheckDisplayTimeRangeError} If current time is outside allowed display period
+     * @throws {IamOtherReaderIsOpenError} If another reader is active
+     * @throws {IamShowOnlyIfLoadedError} If showOnlyIfLoaded=true but message wasn't preloaded
+     */
     showMessageByEvent(
         eventName: string,
         options?: { showOnlyIfLoaded?: boolean; tags?: string[] }
     ): Promise<IamMessage>;
+
+    /**
+     * Closes the currently open message
+     * @returns Promise that resolves when the message is closed
+     */
     close(): Promise<void>;
+
+    /**
+     * Registers an event listener
+     * @template Event - The event name to listen for
+     * @param eventName - Name of the event to listen for
+     * @param listener - Callback function to handle the event
+     * @returns The InAppMessaging instance for chaining
+     */
     on<Event extends keyof IamEvents>(eventName: Event, listener: IamEventHandler<Event>): this;
+
+    /**
+     * Registers a one-time event listener
+     * @template Event - The event name to listen for
+     * @param eventName - Name of the event to listen for
+     * @param listener - Callback function to handle the event
+     * @returns The InAppMessaging instance for chaining
+     */
     once<Event extends keyof IamEvents>(eventName: Event, listener: IamEventHandler<Event>): this;
+
+    /**
+     * Removes an event listener
+     * @template Event - The event name to remove listener for
+     * @param eventName - Name of the event
+     * @param listener - Callback function to remove
+     * @returns The InAppMessaging instance for chaining
+     */
     off<Event extends keyof IamEvents>(eventName: Event, listener: IamEventHandler<Event>): this;
 }

package/dist/types/inAppStoryManager.d.ts

@@ -3,89 +3,284 @@ import { AppearanceManager } from "./appearance-manager/appearanceManager";
 import { StoriesList, UGCStoriesList } from "./story-list";
 import { PublicEventHandler, PublicEvents } from "./publicEvents";
 import { InAppMessaging } from "./in-app-messaging";
+import { StoryManagerEvents } from "./events";
 
+/**
+ * Source of a link click within stories.
+ */
 export declare enum StoryLinkSource {
     StoryList = "storyList",
     StoryReader = "storyReader",
     GameReader = "gameReader"
 }
 
+/**
+ * Configuration options for initializing the InAppStoryManager.
+ */
 export type InAppStoryManagerConfig = {
+    /** API key for initializing the SDK */
     apiKey: string;
+    /** Unique user identifier (optional)
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/user-settings.html
+     */
     userId?: string | number;
+    /** Signature for the userId for validation (optional)
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/user-settings.html
+     */
     userIdSign?: string;
+    /** Tags for filtering stories (optional)
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/tags.html
+     */
     tags?: Array<string>;
+    /** Text placeholders to replace in stories (optional)
+     * @example
+     * placeholders: {
+     *   "userName": "John"
+     * }
+     * @see https://docs.inappstory.com/sdk-guides/js-sdk/placeholders.html
+     */
     placeholders?: Record<string, string>;
+    /** Image placeholders to replace in stories (optional)
+     * @example
+     * imagePlaceholders: {
+     *   "avatar": "https://example.com/avatar.png"
+     * }
+     * @see https://docs.inappstory.com/sdk-guides/js-sdk/placeholders.html
+     */
     imagePlaceholders?: Record<string, string>;
+    /** Language code for content display (e.g., "en-US") */
     lang?: string;
-    dir?: "ltr" | "rtl"
+    /** Text direction: 'ltr' or 'rtl' */
+    dir?: "ltr" | "rtl";
+    /** Disables automatic deviceId generation
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/user-settings.html#overview
+     */
     disableDeviceId?: boolean;
 };
 
+/**
+ * Configuration for the User Generated Content (UGC) editor.
+ */
 export type UgcEditorConfig = {
+    /** Unique session identifier */
     sessionId: string;
+    /** SDK API key */
     apiKey: string;
+    /** Editor configuration */
     editor: Record<any, any>;
+    /** SDK version */
     sdkVersion: string;
+    /** Application package identifier (optional) */
     appPackageId?: string;
+    /** Unique device identifier */
     deviceId: string;
+    /** User identifier (optional) */
     userId?: string;
+    /** Editor language code */
     lang: string;
 };
 
+/**
+ * Handler for story link click events.
+ */
 export type StoryLinkClickHandler = (payload: {
     data: { id: number; index: number; isDeeplink: boolean; url: string };
     src: StoryLinkSource;
 }) => void;
 
+/**
+ * Interface for external plugin integration.
+ */
 export interface Plugin {
+    /** Unique plugin name */
     name: string;
+    /** Called when the plugin is installed */
     install(inAppStoryManager: InAppStoryManager, options?: any): void;
+    /** Called when the plugin is uninstalled */
     uninstall(inAppStoryManager: InAppStoryManager, options?: any): void;
 }
 
+/**
+ * Main class for managing stories, games, and content.
+ */
 export declare class InAppStoryManager {
+    /** SDK version name (e.g., '1.7.0') */
     get sdkVersionName(): string;
+
+    /** Numeric SDK version code (e.g., 10700) */
     get sdkVersionCode(): number;
+
+    /** Module for displaying in-app messages */
     inAppMessaging: InAppMessaging;
+
+    /** Sets the handler for story link clicks
+     * @example
+     * manager.storyLinkClickHandler = ({ data, src }) => {
+     *   console.log(`Link clicked: ${data.url} from ${src}`);
+     * };
+     */
     set storyLinkClickHandler(value: StoryLinkClickHandler);
 
+    /**
+     * Creates an instance of InAppStoryManager.
+     * @param config SDK configuration
+     */
     constructor(config: InAppStoryManagerConfig);
+
+    /**
+     * Gets the current instance of the manager.
+     */
     static getInstance(): InAppStoryManager;
+
+    /**
+     * Installs a plugin at the class level.
+     * @param plugin The plugin instance
+     * @param options Optional plugin options
+     */
     static use(plugin: Plugin, options?: any): void;
 
+    /**
+     * Destroys the manager instance.
+     */
     destroy(): void;
+
+    /**
+     * Displays onboarding stories.
+     * @param appearanceManager Appearance manager instance
+     * @param options Optional filtering options
+     */
     showOnboardingStories(
         appearanceManager: AppearanceManager,
         options?: { feed?: string; customTags?: Array<string>; limit?: number }
     ): Promise<void>;
+
+    /**
+     * Displays the share page for a specific story.
+     * @param storyId The story ID
+     */
     showSharePage(storyId: number | string, appearanceManager: AppearanceManager): Promise<void>;
+
+    /**
+     * Opens a specific story.
+     * @param id The story ID
+     */
     showStory(id: number | string, appearanceManager: AppearanceManager): Promise<void>;
+
+    /**
+     * Opens a specific story only once.
+     * @param id The story ID
+     */
     showStoryOnce(id: number | string, appearanceManager: AppearanceManager): Promise<void>;
+
+    /**
+     * Opens a game by its instance ID.
+     * @param gameInstanceId Game instance identifier
+     * @param appearanceManager Appearance manager instance
+     */
     openGame(
         gameInstanceId: string | number,
-        appearanceManager: AppearanceManager,
-        gameOptions?: { demoMode?: boolean }
+        appearanceManager: AppearanceManager
     ): Promise<void>;
+
+    /**
+     * Closes the currently active game, if any.
+     * @returns Whether the game was closed
+     */
     closeGame(): Promise<boolean>;
+
+    /**
+     * Closes the story reader, if it is open.
+     */
     closeStoryReader(): Promise<boolean | undefined>;
+
+    /**
+     * Closes the goods widget, if it is open.
+     */
     closeGoodsWidget(): void;
+
+    /**
+     * Retrieves the UGC editor configuration.
+     */
     getUgcEditorConfig(): Promise<UgcEditorConfig>;
+
+    /**
+     * Retrieves the nonce, if set.
+     */
     getNonce(): string | undefined;
+
+    /**
+     * Sets the user ID.
+     * @param userId User identifier
+     * @param sign Optional signature
+     */
     setUserId(userId: string | number, sign?: string): Promise<void>;
+
+    /**
+     * Logs out the current user.
+     */
     userLogout(): Promise<void>;
+
+    /**
+     * Sets the content language.
+     */
     setLang(lang: string): void;
+
+    /**
+     * Sets tags for filtering stories.
+     */
     setTags(tags: string[]): void;
+
+    /**
+     * Sets text placeholders.
+     */
     setPlaceholders(placeholders: Dict<string, string>): void;
+
+    /**
+     * Sets image placeholders.
+     */
     setImagePlaceholders(imagePlaceholders: Dict<string, string>): void;
-    on<Event extends keyof PublicEvents>(eventName: Event, listener: PublicEventHandler<Event>): this;
-    once<Event extends keyof PublicEvents>(eventName: Event, listener: PublicEventHandler<Event>): this;
-    off<Event extends keyof PublicEvents>(eventName: Event, listener: PublicEventHandler<Event>): this;
+
+    /**
+     * Subscribes to an SDK event.
+     * @param eventName The name of the event
+     * @param listener The event handler
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/events.html
+     */
+    on<EventName extends keyof StoryManagerEvents>(
+        eventName: EventName,
+        listener: (event: StoryManagerEvents[EventName]) => void
+    ): this;
+
+    /**
+     * Subscribes to a one-time SDK event.
+     * @param eventName The name of the event
+     * @param listener The event handler
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/events.html
+     */
+    once<EventName extends keyof StoryManagerEvents>(
+        eventName: EventName,
+        listener: (event: StoryManagerEvents[EventName]) => void
+    ): this;
+
+    /**
+     * Unsubscribes from an SDK event.
+     * @param eventName The name of the event
+     * @param listener The event handler
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/events.html
+     */
+    off<EventName extends keyof StoryManagerEvents>(
+        eventName: EventName,
+        listener: (event: StoryManagerEvents[EventName]) => void
+    ): this;
 
     /** @deprecated Use `showSharePage()` instead */
     SharePage: {
         new (storyId: number | string, appearanceManager: AppearanceManager, options?: SharePageOptions): SharePage;
     };
+
+    /**
+     * Component for displaying a list of stories.
+     */
     StoriesList: {
         new (
             mountSelector: string,
@@ -93,6 +288,10 @@ export declare class InAppStoryManager {
             options: { feed?: string; testKey?: string; useUgcCard?: boolean }
         ): StoriesList;
     };
+
+    /**
+     * Component for displaying a list of UGC stories.
+     */
     UGCStoriesList: {
         new (
             mountSelector: string,

package/dist/types/index.d.ts

@@ -2,5 +2,5 @@ export * from "./appearance-manager";
 export * from "./story-list";
 export * from "./share-page";
 export * from "./inAppStoryManager";
-export * from "./publicEvents";
 export * from "./in-app-messaging";
+export * from "./events"

package/dist/types/share-page/sharePage.d.ts

@@ -7,6 +7,10 @@ export type SharePageOptions = {
     handleStoryReaderClose?: () => void;
 };
 
+/**
+ *  @deprecated Use showSharePage() instead
+ *  @see https://docs.inappstory.com/sdk-guides/sharing/sharing.html
+ */
 export declare class SharePage extends EventEmitter {
     constructor(storyId: number | string, appearanceManager: AppearanceManager, options?: SharePageOptions);
 

package/dist/types/story-list/StoryList.d.ts

@@ -2,18 +2,48 @@ import { EventEmitter } from "events";
 import { AppearanceManager } from "../appearance-manager";
 import { StoriesListType } from "./storiesListType";
 
+/**
+ * Component for rendering and managing a list of stories.
+ *
+ * Emits events related to story list loading and interactions.
+ */
 export declare class StoriesList extends EventEmitter {
+    /** Type of the stories list (e.g., regular, UGC, etc.) */
     get type(): StoriesListType;
+
+    /** Feed slug used for loading stories */
     get feedSlug(): string;
+
+    /** Test key for loading stories in test mode */
     get testKey(): string;
+
+    /** Whether the list includes a UGC card */
     get useUgcCard(): boolean;
 
+    /**
+     * Creates a new StoriesList instance and mounts it to the given selector.
+     * @param mountSelector CSS selector or DOM element where the list will be mounted
+     * @param appearanceManager Instance controlling the list’s appearance
+     * @param options Additional configuration:
+     *  - `feed`: Feed slug to load stories from
+     *  - `testKey`: Key for loading test stories
+     *  - `useUgcCard`: Whether to display a UGC card in the list
+     */
     constructor(
         mountSelector: string,
         appearanceManager: AppearanceManager,
         options: { feed?: string; testKey?: string; useUgcCard?: boolean }
     );
 
+    /**
+     * Reloads the list of stories.
+     * @param options Options for reloading:
+     *  - `needLoader`: Whether to show a loading indicator
+     */
     reload(options?: { needLoader: boolean }): Promise<void>;
+
+    /**
+     * Destroys the list instance and removes it from the DOM.
+     */
     destroy(): void;
 }

package/dist/types/story-list/UGCStoryList.d.ts

@@ -2,18 +2,48 @@ import { EventEmitter } from "events";
 import { AppearanceManager } from "../appearance-manager";
 import { StoriesListType } from "./storiesListType";
 
+/**
+ * Component for rendering and managing a list of user-generated content (UGC) stories.
+ *
+ * Emits events related to list loading, filtering, and user interactions.
+ */
 export declare class UGCStoriesList extends EventEmitter {
+    /** Type of the stories list (e.g., regular, UGC, etc.) */
     get type(): StoriesListType;
+
+    /** Feed slug used for loading stories (if applicable) */
     get feedSlug(): string;
+
+    /** Test key for loading stories in test mode */
     get testKey(): string;
+
+    /** Whether the list includes a UGC card */
     get useUgcCard(): boolean;
 
+    /**
+     * Creates a new UGCStoriesList instance and mounts it to the given selector.
+     * @param mountSelector CSS selector or DOM element where the list will be mounted
+     * @param appearanceManager Instance controlling the list’s appearance
+     * @param options Additional configuration:
+     *  - `filter`: Filter parameters for loading specific stories
+     *  - `testKey`: Key for loading test stories
+     *  - `useUgcCard`: Whether to display a UGC card in the list
+     */
     constructor(
         mountSelector: string,
         appearanceManager: AppearanceManager,
         options: { filter?: Record<string, any>; testKey?: string; useUgcCard?: boolean }
     );
 
+    /**
+     * Reloads the list of UGC stories.
+     * @param options Options for reloading:
+     *  - `needLoader`: Whether to show a loading indicator
+     */
     reload(options?: { needLoader: boolean }): Promise<void>;
+
+    /**
+     * Destroys the list instance and removes it from the DOM.
+     */
     destroy(): void;
 }

package/dist/types/story-list/storyListLoadStatus.ts

@@ -1,12 +1,49 @@
+/**
+ * Represents the loading status and metadata for a story list
+ */
 export interface StoryListLoadStatus {
-    feed: string | number,
-    filter: Record<string, any> | null,
-    defaultListLength: number,
-    favoriteListLength: number,
-    success: boolean,
+    /**
+     * The feed identifier that was loaded
+     */
+    feed: string;
+
+    /**
+     * Applied filters for the story list, or null if no filters were applied
+     */
+    filter: Record<string, any> | null;
+
+    /**
+     * Number of items in the default (non-favorite) story list
+     */
+    defaultListLength: number;
+
+    /**
+     * Number of items in the favorites list
+     */
+    favoriteListLength: number;
+
+    /**
+     * Indicates whether the loading operation was successful
+     */
+    success: boolean;
+
+    /**
+     * Error details if the loading failed, or null if successful
+     */
     error: {
-        name: string,
-        networkStatus: number,
-        networkMessage: string
-    } | null
+        /**
+         * Name/type of the error that occurred
+         */
+        name: string;
+
+        /**
+         * HTTP status code or network error code
+         */
+        networkStatus: number;
+
+        /**
+         * Human-readable error message from the network request
+         */
+        networkMessage: string;
+    } | null;
 }