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

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

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

@@ -1,27 +1,111 @@
 import { StoriesListCardOptions, StoriesListCardCoverQuality, StoriesListCardViewVariant } from "../appearance-manager";
 
+/**
+ * Represents the view model for a story preview card in the stories list
+ */
 export interface StoryCardViewModel {
+    /**
+     * Unique identifier of the story
+     */
     id: number;
+
+    /**
+     * Title of the story
+     */
     title: string;
+
+    /**
+     * Color of the title text in HEX format
+     */
     titleColor: string;
-    magazineName: string;
+
+    /**
+     * Background color of the card in HEX format
+     */
     backgroundColor: string;
+
+    /**
+     * Background configuration of the card
+     */
     background: {
+        /**
+         * Background color in HEX format
+         */
         color: string;
+
+        /**
+         * Whether the background uses gradient effect
+         */
         gradient: boolean;
     };
+
+    /**
+     * Indicates if the story is marked as favorite
+     */
     favorite: boolean;
+
+    /**
+     * Number of likes the story has received
+     */
     like: number;
+
+    /**
+     * Deeplink URL for navigation when card is clicked (null if not available)
+     */
     deeplink: string | null;
+
+    /**
+     * Whether the story should be hidden in the reader
+     */
     hideInReader: boolean | null;
+
+    /**
+     * Game instance details (if the story is a game)
+     */
     gameInstance?: { id?: string };
+
+    /**
+     * Whether the story contains audio
+     */
     hasAudio: boolean | null;
+
+    /**
+     * Whether this card represents a favorite stories collection
+     */
     isFavoriteCard: boolean;
+
+    /**
+     * Whether this is a User Generated Content (UGC) card
+     */
     isUgcCard: boolean;
+
+    /**
+     * Whether the story is currently opened/being viewed
+     */
     isOpened: boolean;
+
+    /**
+     * URL source for the video cover (null if not available)
+     */
     videoCoverSrc: string | null;
 
-    getAspectRatio(variant: StoriesListCardViewVariant): number
-    getImageSrcByCoverQuality(coverQuality: StoriesListCardCoverQuality): string | undefined
+    /**
+     * Calculates the aspect ratio for the card based on view variant
+     * @param variant - The card view variant/style
+     * @returns The aspect ratio (width/height)
+     */
+    getAspectRatio(variant: StoriesListCardViewVariant): number;
+
+    /**
+     * Gets the appropriate image source URL based on requested quality
+     * @param coverQuality - The desired image quality level
+     * @returns The image URL or undefined if not available
+     */
+    getImageSrcByCoverQuality(coverQuality: StoriesListCardCoverQuality): string | undefined;
+
+    /**
+     * Handles click interaction with the story card
+     * @param index - Optional position index of the card in the list
+     */
     onClick(index?: number): void;
 }

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

@@ -1,3 +1,4 @@
 export interface StoryListApi {
-    reload(): void
-}
+    /** Reload stories */
+    reload(): 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;
+}

package/dist/types/storyManager.d.ts

@@ -1,52 +1,154 @@
 import { PublicEventHandler, PublicEvents } from "./ias-container";
 import { InAppMessaging } from "./in-app-messaging/inAppMessaging";
 
+/**
+ * Source of the link click within stories.
+ */
 export declare enum LinkSource {
     StoryList = "storyList",
     StoryReader = "storyReader",
     GameReader = "gameReader"
 }
 
+/**
+ * Configuration options for initializing the StoryManager.
+ */
 export type StoryManagerConfig = {
+    /** API integration 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 used to filter stories (optional)
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/tags.html
+     */
     tags?: Array<string>;
+    /** Text placeholders to be replaced in stories (optional)
+     * @see https://docs.inappstory.com/sdk-guides/js-sdk/placeholders.html
+     * @example
+     * placeholders: {
+     *   "your-placeholder-key": "value"
+     * }
+     */
     placeholders?: Record<string, string>;
+    /** Image placeholders to be replaced in stories (optional)
+     * @see https://docs.inappstory.com/sdk-guides/js-sdk/placeholders.html
+     * @example 
+     * imagePlaceholders: {
+     *   "your-image-placeholder-key": "value"
+     * }
+     */
     imagePlaceholders?: Record<string, string>;
+    /** Language code for content display (e.g., 'en-US') (optional) */
     lang?: string;
+    /** Text direction (optional): '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 (customizable externally) */
     editor: Record<any, any>;
+    /** SDK version */
     sdkVersion: string;
+    /** App package identifier (optional) */
     appPackageId?: string;
+    /** Unique device identifier */
     deviceId: string;
+    /** User identifier (optional) */
     userId?: string;
+    /** Language code for the editor */
     lang: string;
 };
 
+/**
+ * Handler for story link click events.
+ * @deprecated Use `clickOnButton` event instead
+ */
 export type StoryLinkClickHandler = (payload: {
     data: { id: number; index: number; isDeeplink: boolean; url: string };
     src: LinkSource;
 }) => void;
 
+/**
+ * Interface for external plugin integration with the StoryManager.
+ */
 export interface Plugin {
+    /** Unique plugin name */
     name: string;
+    /** Called when the plugin is installed */
     install(storyManager: StoryManager, options?: any): void;
+    /** Called when the plugin is uninstalled */
     uninstall(storyManager: StoryManager, options?: any): void;
 }
 
+/**
+ * Main class for managing stories and games
+ */
 export declare class StoryManager {
+    /** 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
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/in-app-messaging.html
+     */
     inAppMessaging: InAppMessaging;
 
+    /** Handler for story link clicks
+     *
+     * @example
+     * storyManager.storyLinkClickHandler = ({ data, src }) => {
+     *   console.log("Link clicked:", data.url, "from", src);
+     * };
+     * @deprecated Use `clickOnButton` event instead
+     * @see https://docs.inappstory.com/sdk-guides/reack-sdk/link-handling.html
+     */
     set storyLinkClickHandler(value: StoryLinkClickHandler);
+
+    /**
+     * Displays onboarding stories, optionally filtered by feed, tags, or limit.
+     * @param options Filter options and limit
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/onboardings.html
+     * @example 
+     *  import { StoryManagerConfig, IASContainer, storyManager } from "@inappstory/react-sdk";
+        import { useEffect } from "react";
+
+        export const App = () => {
+            useEffect(() => {
+                storyManager.showOnboardingStories().then((result) => {
+                    console.log("Onboarding stories displayed:", result.stories);
+                }).catch((error) => {
+                    console.error("Error displaying onboarding stories:", error);
+                });
+            }, []);
+
+            const storyManagerConfig: StoryManagerConfig = {
+                apiKey: "{projectToken}",
+                userId,
+            };
+
+            return <IASContainer config={storyManagerConfig} />;
+        };
+
+     */
     showOnboardingStories(options?: { feed?: string; customTags?: Array<string>; limit?: number }): Promise<{
         stories: {
             title: Option<string>;
@@ -58,18 +160,95 @@ export declare class StoryManager {
         feed?: Option<string>;
         filter?: Option<Record<string, any>>;
     }>;
+
+    /**
+     * Displays the share page for a specific story.
+     * @param storyId The story ID
+     * @see https://docs.inappstory.com/sdk-guides/sharing/sharing.html
+     * @example
+     * storyManager.showSharePage("yout-story-id").catch(console.error)
+     */
     showSharePage(storyId: number | string): Promise<void>;
+
+    /**
+     * Displays a specific story.
+     * @param id The story ID
+     */
     showStory(id: number | string): Promise<void>;
+
+    /**
+     * Displays a story only once.
+     * @param id The story ID
+     */
     showStoryOnce(id: number | string): Promise<void>;
-    openGame(gameInstanceId: string, gameOptions?: { demoMode?: boolean }): Promise<void>;
+
+    /**
+     * Opens a game by its instance ID.
+     * @param gameInstanceId Game instance identifier
+     * @param gameOptions Optional game parameters
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/games.html
+     * @example
+     * storyManager.openGame("your-game-id")
+     */
+    openGame(gameInstanceId: string | number, gameOptions?: { demoMode?: boolean }): Promise<void>;
+
+    /**
+     * Closes the currently active game, if any.
+     * @returns A flag indicating whether the game was closed
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/games.html
+     */
     closeGame(): Promise<boolean>;
+
+    /**
+     * Closes the story reader, if it is open.
+     * @returns A flag indicating whether the reader was closed
+     */
     closeStoryReader(): Promise<boolean | undefined>;
+
+    /**
+     * Closes the goods widget, if it is open.
+     */
     closeGoodsWidget(): void;
+
+    /**
+     * Retrieves the UGC editor configuration.
+     */
     getUgcEditorConfig(): Promise<UgcEditorConfig>;
+
+    /**
+     * 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<Event extends keyof PublicEvents>(eventName: Event, listener: PublicEventHandler<Event>): 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<Event extends keyof PublicEvents>(eventName: Event, listener: PublicEventHandler<Event>): 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<Event extends keyof PublicEvents>(eventName: Event, listener: PublicEventHandler<Event>): this;
+
+    /**
+     * Installs a plugin at the class level.
+     * @param plugin The plugin instance
+     * @param options Optional plugin options
+     * @see https://docs.inappstory.com/sdk-guides/react-sdk/plugins.html
+     */
     static use(plugin: Plugin, options?: any): void;
 }
 
+/**
+ * Instance of StoryManager.
+ */
 export declare const storyManager: StoryManager;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inappstory/react-sdk",
-  "version": "1.7.2",
+  "version": "1.8.0-rc.0",
   "description": "React SDK",
   "keywords": [
     "stories",
@@ -35,6 +35,10 @@
     "./plugins/videoOnDemand": {
       "types": "./plugins/videoOnDemand/iasVideoOnDemandPlugin.d.ts",
       "default": "./plugins/videoOnDemand/iasVideoOnDemandPlugin.umd.js"
+    },
+    "./plugins/banners": {
+      "types": "./plugins/banners/types/index.d.ts",
+      "default": "./plugins/banners/index.esm.mjs"
     }
   },
   "main": "dist/index.umd.js",
@@ -54,7 +58,7 @@
     "Samsung >= 5"
   ],
   "dependencies": {
-    "@inappstory/slide-api": "^0.1.18",
+    "@inappstory/slide-api": "^0.1.20",
     "async-mutex": "^0.5.0",
     "bowser": "^2.11.0",
     "classnames": "^2.5.1",