@inappstory/react-sdk 1.7.3 → 1.8.0-rc.0

package/dist/types/ias-container/appearanceOptionsProps.d.ts

@@ -2,12 +2,31 @@ import {
     AppearanceCommonOptions,
     GameReaderOptions,
     GoodsWidgetOptions,
-    StoryReaderOptions,
+    StoryReaderOptions
 } from "../appearance-manager";
 
+/**
+ * Appearance customization options.
+ * Allows styling different parts of the InAppStory
+ */
 export interface AppearanceOptionsProps {
+    /**
+     * Common appearance options applied across All IAS components
+     */
     commonOptions?: AppearanceCommonOptions;
+
+    /**
+     * Customization options specific to the Story Reader component
+     */
     storyReaderOptions?: StoryReaderOptions;
+
+    /**
+     * Customization options specific to the Game Reader component
+     */
     gameReaderOptions?: GameReaderOptions;
+
+    /**
+     * Customization options for the Goods Widget (V1) appearance
+     */
     goodsWidgetOptions?: GoodsWidgetOptions;
 }

package/dist/types/ias-container/storyManagerEventsProps.d.ts

@@ -14,18 +14,96 @@ import {
     WidgetEvent
 } from "./publicEvents";
 
+/**
+ * Interface for `StoryManager` event handlers.
+ * Contains callback props for various events that occur during story interactions.
+ * All event handlers are optional and follow the naming pattern `on[EventName]`.
+ *
+ * Each event handler receives a specific event object with relevant data about the interaction.
+ *
+ * @example
+ * // Example of using event handlers
+ * <IASContainer
+ *   onShowStory={(event) => console.log('Story shown:', event.id)}
+ *   onCloseStory={(event) => console.log('Story closed:', event.id)}
+ * />
+ */
 export interface StoryManagerEventsProps {
+    /**
+     * Called when a user clicks on a story in the story list
+     * @param event - Contains story ID and other metadata
+     */
     onClickOnStory?: (event: ClickOnStoryEvent) => void;
+
+    /**
+     * Called when a story becomes visible in the reader
+     * @param event - Contains story ID and opening context
+     */
     onShowStory?: (event: ShowStoryEvent) => void;
+
+    /**
+     * Called when a story is closed
+     * @param event - Contains story ID and close action
+     */
     onCloseStory?: (event: CloseStoryEvent) => void;
+
+    /**
+     * Called when a new slide is shown in the story
+     * @param event - Contains story ID and slide index
+     */
     onShowSlide?: (event: ShowSlideEvent) => void;
+
+    /**
+     * Called when a user clicks on an interactive button in the story
+     * @param event - Contains URL
+     */
     onClickOnButton?: (event: ClickOnButtonEvent) => void;
+
+    /**
+     * Called when a user likes a story
+     * @param event - Contains story ID and like status
+     */
     onLikeStory?: (event: LikeStoryEvent) => void;
+
+    /**
+     * Called when a user dislikes a story
+     * @param event - Contains story ID and dislike status
+     */
     onDislikeStory?: (event: DislikeStoryEvent) => void;
+
+    /**
+     * Called when a user favorites a story
+     * @param event - Contains story ID and favorite status
+     */
     onFavoriteStory?: (event: FavoriteStoryEvent) => void;
+
+    /**
+     * Called when a user shares a story (without specific path)
+     * @param event - Contains story ID and share method
+     */
     onShareStory?: (event: ShareStoryEvent) => void;
+
+    /**
+     * Called when a user shares a story with a specific path/slide
+     * @param event - Contains story ID, slide index, and share method
+     */
     onShareStoryWithPath?: (event: ShareStoryWithPathEvent) => void;
+
+    /**
+     * Called when stories feed becomes visible to the user
+     * @param event - Contains feed slug and impression data
+     */
     onFeedImpression?: (event: FeedImpressionEvent) => void;
+
+    /**
+     * Called when the visible area of stories in a feed changes
+     * @param event - Contains visibility information for stories in viewport
+     */
     onVisibleAreaUpdated?: (event: VisibleAreaUpdatedEvent) => void;
+
+    /**
+     * Generic handler for widget-specific events
+     * @param event - Contains widget type and event-specific data
+     */
     onWidgetEvent?: (event: WidgetEvent) => void;
 }

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

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;