@inappstory/react-sdk 1.7.3 → 1.7.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/index.d.ts

@@ -2,4 +2,5 @@ export * from "./appearance-manager";
 export * from "./story-list";
 export * from "./storyManager";
 export * from "./ias-container";
-export * from "./in-app-messaging"
+export * from "./in-app-messaging"
+export * from "./events"

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

@@ -2,10 +2,60 @@ import { StoriesListOptions, NavigationViewModel } from "..";
 import { StoryCardViewModel } from "./storyCardViewModel";
 import { OverrideByMediaQuery } from "../appearance-manager/overrideByMediaQuery";
 
+/**
+ * Props for the FavoriteStoryList component that displays a user's favorite stories
+ */
 interface FavoriteStoryListProps {
+    /**
+     * Configuration options for customizing the appearance and behavior of the list
+     */
     options?: StoriesListOptions;
-    optionsOverrideByMediaQuery?: OverrideByMediaQuery<StoriesListOptions>[]
+
+    /**
+     * Custom render function for story cards
+     *
+     * @param storyCard - Data object containing card content and metadata
+     * @returns React node to render for the card
+     *
+     * @example
+     * (storyCard) => (
+     *   <CustomCard
+     *     title={storyCard.title}
+     *     image={storyCard.getImageSrcByCoverQuality('high')}
+     *   />
+     * )
+     */
     storyCardView?: (storyCard: StoryCardViewModel) => React.ReactNode;
+
+    /**
+     * Custom render function for navigation controls
+     *
+     * @param navigation - Data object containing navigation state and methods
+     * @returns React node to render for navigation
+     *
+     * @example
+     * (navigation) => (
+     *   <div className="custom-nav">
+     *     <button onClick={navigation.onPrev} disabled={navigation.reachStart}>
+     *       Previous
+     *     </button>
+     *     <button onClick={navigation.onNext} disabled={navigation.reachEnd}>
+     *       Next
+     *     </button>
+     *   </div>
+     * )
+     */
     navigationView?: (navigation: NavigationViewModel) => React.ReactNode;
 }
+
+/**
+ * Component that displays a scrollable list of a user's favorite stories
+ * with support for custom rendering and responsive configuration
+ *
+ * @param props - Configuration properties for the component
+ * @returns React element representing the favorite stories list
+ *
+ * @example
+ * <FavoriteStoryList />
+ */
 export declare const FavoriteStoryList: (props: FavoriteStoryListProps) => JSX.Element;

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

@@ -6,19 +6,188 @@ import { FavoriteCardCompositeViewModel } from "./favoriteCardCompositeViewModel
 import { StoryListApi } from "./storyListApi";
 import { StoriesListOptions } from "../appearance-manager";
 
+/**
+ * Props for the StoryList component that displays a list of stories previews
+ * @see https://docs.inappstory.com/sdk-guides/react-sdk/story-list.html
+ */
 interface StoryListProps {
+    /**
+     * Ref for accessing the StoryList component API
+     */
     ref?: React.Ref<StoryListApi | null>;
+
+    /**
+     * Appearance settings for the stories list
+     */
     options?: StoriesListOptions;
+
+    /**
+     * Feed identifier for loading stories
+     * @default default
+     */
     feedSlug?: string;
+
+    /**
+     * Use the testKey to see stories with status `Moderation`.
+     */
     testKey?: string;
+
+    /**
+     * Callback when UGC card is clicked
+     */
     onUgcCardClick?: () => void;
+
+    /**
+     * Callback when favorite card is clicked
+     */
     onFavoriteCardClick?: () => void;
+
+    /**
+     * Flag indicating whether to use UGC cards
+     */
     useUgcCard?: boolean;
+
+    /**
+     * Flag indicating whether favorite cards are present
+     */
     hasFavorite?: boolean;
+
+    /**
+     * Callback triggered when story list loading starts
+     */
     onLoadStart?: () => void;
+
+    /**
+     * Callback triggered when story list loading completes
+     * @param storyListLoadStatus - Status of the story list loading
+     */
     onLoadEnd?: (storyListLoadStatus: StoryListLoadStatus) => void;
+
+    /**
+     * Custom render for story cards
+     * @param storyCard - Data for rendering a story card
+     * @returns React element for the story card
+     * @example
+     * // Custom card with gradient overlay
+     * storyCardView={(card) => (
+     *   <div style={{
+     *     position: 'relative',
+     *     borderRadius: 8,
+     *     overflow: 'hidden',
+     *     aspectRatio: card.getAspectRatio('grid')
+     *   }}>
+     *     <img
+     *       src={card.getImageSrcByCoverQuality('medium')}
+     *       alt={card.title}
+     *       style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+     *     />
+     *     <div style={{
+     *       position: 'absolute',
+     *       bottom: 0,
+     *       left: 0,
+     *       right: 0,
+     *       padding: 16,
+     *       background: 'linear-gradient(to top, rgba(0,0,0,0.7) 0%, transparent 100%)'
+     *     }}>
+     *       <h3 style={{ color: '#fff', margin: 0 }}>{card.title}</h3>
+     *     </div>
+     *   </div>
+     * )}
+     */
     storyCardView?: (storyCard: StoryCardViewModel) => React.ReactNode;
+
+    /**
+     * Custom render for navigation
+     * @param navigation - Data for rendering navigation
+     * @returns React element for navigation
+     * @example
+     * // Custom navigation arrows with disabled states
+     * navigationView={(nav) => (
+     *   <div style={{
+     *     display: 'flex',
+     *     justifyContent: 'center',
+     *     gap: 16,
+     *     padding: '16px 0'
+     *   }}>
+     *     <button
+     *       onClick={nav.onPrev}
+     *       disabled={nav.reachStart}
+     *       style={{
+     *         padding: '8px 16px',
+     *         opacity: nav.reachStart ? 0.5 : 1,
+     *         cursor: nav.reachStart ? 'not-allowed' : 'pointer'
+     *       }}
+     *     >
+     *       ← Previous
+     *     </button>
+     *     <button
+     *       onClick={nav.onNext}
+     *       disabled={nav.reachEnd}
+     *       style={{
+     *         padding: '8px 16px',
+     *         opacity: nav.reachEnd ? 0.5 : 1,
+     *         cursor: nav.reachEnd ? 'not-allowed' : 'pointer'
+     *       }}
+     *     >
+     *       Next →
+     *     </button>
+     *   </div>
+     * )}
+     */
     navigationView?: (navigation: NavigationViewModel) => React.ReactNode;
+
+    /**
+     * Custom render function for favorite cards
+     * @param favoriteCardCompositeViewModel - Data for rendering a favorite card
+     * @returns React element for the favorite card
+     * @example
+     * // Favorite card with special badge
+     * favoriteCardView={(favoriteCard) => (
+     *   <div style={{
+     *     border: '2px dashed gold',
+     *     borderRadius: 12,
+     *     padding: 16,
+     *     position: 'relative'
+     *   }}>
+     *     <h3 style={{ marginTop: 0, color: 'gold' }}>
+     *       Favorites Collection ({favoriteCard.favoriteStories.length})
+     *     </h3>
+     *     <div style={{
+     *       display: 'grid',
+     *       gridTemplateColumns: 'repeat(auto-fill, minmax(80px, 1fr))',
+     *       gap: 8
+     *     }}>
+     *       {favoriteCard.favoriteStories.map(story => (
+     *         <img
+     *           key={story.id}
+     *           src={story.getImageSrcByCoverQuality('medium')}
+     *           alt={story.title}
+     *           style={{
+     *             width: '100%',
+     *             aspectRatio: '1',
+     *             objectFit: 'cover',
+     *             borderRadius: 4
+     *           }}
+     *         />
+     *       ))}
+     *     </div>
+     *   </div>
+     * )}
+     */
     favoriteCardView?: (favoriteCardCompositeViewModel: FavoriteCardCompositeViewModel) => React.ReactNode;
 }
+
+/**
+ * Component for displaying a list of stories previews
+ * @param props - Component props
+ * @returns React story list component
+ * @example
+ * // Basic usage with custom card and navigation
+ * <StoryList
+ *   feedSlug="default"
+ *   storyCardView={(card) => <CustomStoryCard card={card} />}
+ *   navigationView={(nav) => <CustomNavigation {...nav} />}
+ *   onLoadEnd={(status) => console.log('Loaded', status.defaultListLength, 'stories')}
+ * />
+ */
 export declare const StoryList: (props: StoryListProps) => JSX.Element;

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

@@ -5,17 +5,78 @@ import { StoryCardViewModel } from "./storyCardViewModel";
 import { StoryListApi } from "./storyListApi";
 import { StoryListLoadStatus } from "./storyListLoadStatus";
 
+/**
+ * Props for the UGCStoryList component that displays user-generated content stories
+ */
 interface UGCStoryListProps {
+    /**
+     * Ref object to access the StoryList API methods imperatively
+     */
     ref?: React.Ref<StoryListApi | null>;
+
+    /**
+     * Appearance settings for the stories list
+     */
     options?: StoriesListOptions;
+
+    /**
+     * Use the testKey to see stories with status `Moderation`.
+     */
     testKey?: string;
+
+    /**
+     * Callback triggered when a UGC story card is clicked
+     */
     onUgcCardClick?: () => void;
+
+    /**
+     * Flag to enable/disable UGC card functionality
+     * @default false
+     */
     useUgcCard?: boolean;
+
+    /**
+     * Flag indicating whether favorites functionality should be enabled
+     * @default false
+     */
     hasFavorite?: boolean;
+
+    /**
+     * Filter criteria to apply when loading stories
+     */
     filter?: Record<string, any>;
+
+    /**
+     * Callback triggered when story list loading begins
+     */
     onLoadStart?: () => void;
+
+    /**
+     * Callback triggered when story list loading completes
+     * @param storyListLoadStatus - Contains loading results and metadata
+     */
     onLoadEnd?: (storyListLoadStatus: StoryListLoadStatus) => void;
+
+    /**
+     * Custom render function for story cards
+     * @param storyCard - Data object containing card content and metadata
+     * @returns React node to render for the card
+     */
     storyCardView?: (storyCard: StoryCardViewModel) => React.ReactNode;
+
+    /**
+     * Custom render function for navigation controls
+     * @param navigation - Data object containing navigation state
+     * @returns React node to render for navigation
+     */
     navigationView?: (navigation: NavigationViewModel) => React.ReactNode;
 }
+
+/**
+ * Component that displays a scrollable list of user-generated content stories
+ * with support for custom rendering and interaction callbacks
+ *
+ * @param props - Configuration properties for the component
+ * @returns React element representing the story list
+ */
 export declare const UGCStoryList: (props: UGCStoryListProps) => JSX.Element;

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

@@ -1,12 +1,55 @@
+/**
+ * Represents the view model for navigation controls in a stories list or carousel
+ */
 export interface NavigationViewModel {
+    /**
+     * CSS styles to be applied to navigation elements by default
+     */
     defaultStyles: Record<string, string>;
+
+    /**
+     * Indicates whether the beginning of the list has been reached
+     * (disabled state for previous/back navigation)
+     */
     reachStart: boolean;
+
+    /**
+     * Indicates whether the end of the list has been reached
+     * (disabled state for next/forward navigation)
+     */
     reachEnd: boolean;
+
+    /**
+     * Handler for previous/back navigation action
+     * Scrolls to the previous item or page
+     */
     onPrev(): void;
+
+    /**
+     * Handler for next/forward navigation action
+     * Scrolls to the next item or page
+     */
     onNext(): void;
+
+    /**
+     * Slider state and properties
+     */
     slider: {
+        /**
+         * Current scroll position of the slider in pixels
+         */
         currentPosition: number;
+
+        /**
+         * Scroll direction of the slider
+         * @default "horizontal"
+         */
         direction: "horizontal" | "vertical";
+
+        /**
+         * Dimensions and position of the visible viewport area
+         * @description Uses DOMRect with properties: x, y, width, height, top, right, bottom, left
+         */
         viewport: DOMRect;
     };
 }