@inappstory/js-sdk 3.6.2 → 3.7.0-rc.0

package/dist/types/appearance-manager/storyReader.d.ts

@@ -0,0 +1,260 @@
+import { CloseButtonPosition } from "./appearanceCommon";
+import { SharePanel } from "./sharePanel";
+import { Nullable, RecursivePartial } from "../global";
+
+/**
+ * Defines the swipe animation style used when navigating between stories.
+ *
+ * This affects the visual transition effect when the user swipes to the next or previous story.
+ */
+export declare enum StoryReaderSwipeStyle {
+    /**
+     * Flat swipe with no 3D or overlay effects.
+     * Simple, fast, and performance-optimized.
+     */
+    FLAT = "flat",
+
+    /**
+     * Cover swipe where the next story over the current one.
+     * Offers a layered visual effect.
+     */
+    COVER = "cover",
+
+    /**
+     * 3D cube rotation effect between stories.
+     * Visually rich but more performance-intensive.
+     */
+    CUBE = "cube"
+}
+/**
+ * Enum representing story reader layout variants
+ *
+ * @property {string} Classic - Classic display variant (default)
+ * @property {string} Modern - Modern experimental display variant
+ */
+export declare enum StoryReaderLayout {
+    /** Classic display variant (default) */
+    Classic = "classic",
+
+    /** Modern experimental display variant */
+    Modern = "modern"
+}
+
+/**
+ * Appearance options for Story Reader.
+ */
+export type StoryReaderOptions = RecursivePartial<{
+    /**
+     * Position of the close button.
+     *
+     * @default CloseButtonPosition.END
+     */
+    closeButtonPosition: CloseButtonPosition | "left" | "right";
+
+    /**
+     * Swipe animation style for switching between stories.
+     *
+     * @default StoryReaderSwipeStyle.FLAT
+     */
+    scrollStyle: StoryReaderSwipeStyle | "flat" | "cover" | "cube";
+
+    /**
+     * Vertical offset for the timeline block (in pixels).
+     * @default 8
+     */
+    timelineBlockTopOffset: Nullable<number>;
+
+    /**
+     * Vertical offset for the bottom action panel (in pixels).
+     * @default 0
+     */
+    actionPanelBottomOffset: Nullable<number>;
+
+    /**
+     * Border radius applied to the story container (in pixels).
+     *
+     * @default 12
+     */
+    borderRadius: number;
+
+    /**
+     * Enables the experimental modern layout variant.
+     *
+     * @default false
+     * @deprecated Use `layout` property instead
+     */
+    useExperimentalModernVariant: boolean;
+
+    /**
+     * Layout style for rendering stories.
+     * Can be `'classic'` or `'modern'`.
+     *
+     * @default StoryReaderLayout.Classic
+     */
+    layout: StoryReaderLayout;
+
+    /**
+     * Loader configuration, supports default and custom options.
+     */
+    loader: {
+        default: {
+            /**
+             * Primary loader color.
+             * @default #FFF
+             */
+            color: string;
+            /**
+             * Accent loader color.
+             * @default transparent
+             */
+            accentColor: string;
+        };
+    };
+
+    /**
+     * Whether the story list should loop back to the beginning after the last story.
+     *
+     * @default false
+     */
+    recycleStoriesList: boolean;
+
+    /**
+     * Automatically closes the viewer after the last slide, using a timer.
+     *
+     * @default false
+     */
+    closeOnLastSlideByTimer: boolean;
+
+    /**
+     * Configuration for the share panel.
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/share-panel.html
+     */
+    sharePanel: SharePanel<string>;
+
+    /**
+     * Global backdrop settings for all slides.
+     */
+    commonBackdrop: {
+        /**
+         * Background color.
+         * @default
+         * rgba(51, 51, 51, 1)
+         */
+        color: string;
+        /**
+         * CSS backdrop filter (e.g., `blur(10px)`).
+         * @default null
+         */
+        backdropFilter: string;
+    };
+
+    /**
+     * Slide-specific backdrop settings.
+     */
+    slideBackdrop: {
+        /**
+         * Opacity of the backdrop layer.
+         * @default 0.56
+         */
+        opacity: number;
+        /**
+         * Blur intensity applied to the backdrop.
+         * @default 30
+         */
+        blur: number;
+        /**
+         * Array of CSS linear-gradient strings used as overlays.
+         * @default
+         * ["rgba(0, 0, 0, 0.1) 0%", "rgba(0, 0, 0, 0.9) 100%"]
+         */
+        linearGradientOverlay: string[];
+    };
+
+    /**
+     * Close button configuration.
+     */
+    closeButton: {
+        svgSrc: {
+            /**
+             * Base (default) SVG icon for the close button.
+             */
+            baseState: string;
+        };
+    };
+
+    /**
+     * Like button configuration.
+     */
+    likeButton: {
+        svgSrc: {
+            /**
+             * SVG icon for the default (inactive) state.
+             */
+            baseState: string;
+            /**
+             * SVG icon for the active (liked) state.
+             */
+            activeState: string;
+        };
+    };
+
+    /**
+     * Dislike button configuration.
+     */
+    dislikeButton: {
+        svgSrc: {
+            /**
+             * SVG icon for the default (inactive) state.
+             */
+            baseState: string;
+            /**
+             * SVG icon for the active (disliked) state.
+             */
+            activeState: string;
+        };
+    };
+
+    /**
+     * Favorite button configuration.
+     */
+    favoriteButton: {
+        svgSrc: {
+            /**
+             * SVG icon for the default (not-favorited) state.
+             */
+            baseState: string;
+            /**
+             * SVG icon for the active (favorited) state.
+             */
+            activeState: string;
+        };
+    };
+
+    /**
+     * Mute button configuration.
+     */
+    muteButton: {
+        svgSrc: {
+            /**
+             * SVG icon for the unmuted state.
+             */
+            baseState: string;
+            /**
+             * SVG icon for the muted state.
+             */
+            activeState: string;
+        };
+    };
+
+    /**
+     * Share button configuration.
+     */
+    shareButton: {
+        svgSrc: {
+            /**
+             * SVG icon for the share button.
+             */
+            baseState: string;
+        };
+    };
+}>;

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

@@ -1,48 +1,52 @@
-export declare class IamNotFoundByEventError extends Error {
-    constructor(eventName: string);
-    name: string;
-}
-
-export declare class IamNotFoundByIdError extends Error {
-    constructor(messageId: string | number);
-    name: string;
-}
-
-export declare class IamNotFoundLimitError extends Error {
-    constructor(messageId: string | number);
-    name: string;
-}
-
-export declare class IamMessageOpenError extends Error {
-    constructor(messageId: string | number);
-    name: string;
-}
-
-export declare class IamOtherReaderIsOpenError extends Error {
-    constructor();
-    name: string;
-}
-
-export declare class IamShowOnlyIfLoadedError extends Error {
-    constructor();
-    name: string;
-}
-
-export declare class IamFrequencyLimitError extends Error {
-    constructor();
-    name: string;
-}
-
-export declare class IamCheckDisplayTimeRangeError extends Error {
-    constructor();
-    name: string;
-}
-
-export declare class IamMessageLimitExceededError extends Error {
-    constructor(messageId: string | number);
-    name: string;
-}
-
+/**
+ * Error thrown when no message is found matching the specified event name
+ */
+export declare class IamNotFoundByEventError extends Error {}
+
+/**
+ * Error thrown when no message is found matching the specified message ID
+ */
+export declare class IamNotFoundByIdError extends Error {}
+
+/**
+ * Error thrown when no display limit configuration is found for the specified message
+ */
+export declare class IamNotFoundLimitError extends Error {}
+
+/**
+ * Error thrown when attempting to open a message that is already open
+ */
+export declare class IamMessageOpenError extends Error {}
+
+/**
+ * Error thrown when attempting to open a message while another reader is active
+ */
+export declare class IamOtherReaderIsOpenError extends Error {}
+
+/**
+ * Error thrown when attempting to show a message that hasn't been preloaded,
+ * when the showOnlyIfLoaded option is enabled
+ */
+export declare class IamShowOnlyIfLoadedError extends Error {}
+
+/**
+ * Error thrown when a message's frequency limit has been exceeded
+ */
+export declare class IamFrequencyLimitError extends Error {}
+
+/**
+ * Error thrown when attempting to show a message outside its allowed display time range
+ */
+export declare class IamCheckDisplayTimeRangeError extends Error {}
+
+/**
+ * Error thrown when a message's display limit has been exceeded
+ */
+export declare class IamMessageLimitExceededError extends Error {}
+
+/**
+ * Union type representing all possible In-App Messaging error types
+ */
 export type IamError =
     | IamNotFoundByEventError
     | IamNotFoundByIdError

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;
 }