@xhub-short/contracts 0.1.0-beta.14 → 0.1.0-beta.17

package/dist/index.d.ts

@@ -74,19 +74,18 @@ interface ContentStats {
     shares: number;
     /** Total bookmark/save count (optional) */
     bookmarks?: number;
-}
-/**
- * Video statistics (extends base with views)
- */
-interface VideoStats extends ContentStats {
     /** Total view count */
     views: number;
 }
 /**
- * Image post statistics (alias for ContentStats)
+ * Article statistics (alias for ContentStats)
  * @see ContentStats
  */
-type ImagePostStats = ContentStats;
+type ArticleStats = ContentStats;
+/**
+ * @deprecated Use ArticleStats instead. Will be removed in v3.0
+ */
+type ImagePostStats = ArticleStats;
 /**
  * Base content item shared by all content types
  */
@@ -122,51 +121,31 @@ interface VideoItem extends BaseContentItem {
     /** Video title/description */
     title?: string;
     /** Video statistics */
-    stats: VideoStats;
+    stats: ContentStats;
 }
 /**
- * Image Post content structure
- * Represents a carousel of images in the feed
+ * Article content structure
+ * Represents a carousel of images/other content in the feed
  */
-interface ImagePost extends BaseContentItem {
+interface Article extends BaseContentItem {
     /** Content type discriminator */
-    type: 'image';
+    type: 'article';
     /** Array of image URLs (1 or more) */
     images: string[];
     /** Post caption/description */
     caption?: string;
     /** Post statistics */
-    stats: ImagePostStats;
+    stats: ArticleStats;
 }
 /**
- * Union type for all feed content types
- * Use type guards to narrow the type
+ * @deprecated Use Article instead. Will be removed in v3.0
  */
-type ContentItem = VideoItem | ImagePost;
+type ImagePost = Article;
 /**
- * Type guard to check if content is a VideoItem
- *
- * @example
- * ```typescript
- * if (isVideoItem(item)) {
- *   // item is VideoItem here
- *   console.log(item.source.url);
- * }
- * ```
- */
-declare function isVideoItem(item: ContentItem): item is VideoItem;
-/**
- * Type guard to check if content is an ImagePost
- *
- * @example
- * ```typescript
- * if (isImagePost(item)) {
- *   // item is ImagePost here
- *   console.log(item.images.length);
- * }
- * ```
+ * Union type for all feed content types
+ * Use type guards to narrow the type
  */
-declare function isImagePost(item: ContentItem): item is ImagePost;
+type ContentItem = VideoItem | Article;
 /**
  * Feed pagination response
  *
@@ -181,7 +160,7 @@ declare function isImagePost(item: ContentItem): item is ImagePost;
  * const mixedFeed: FeedResponse<ContentItem> = await dataSource.fetchFeed();
  * ```
  */
-interface FeedResponse<T = VideoItem> {
+interface FeedResponse<T = ContentItem> {
     /** List of content items */
     items: T[];
     /** Cursor for next page (null if no more data) */
@@ -193,9 +172,9 @@ interface FeedResponse<T = VideoItem> {
  * Feed state for state management
  */
 interface FeedState {
-    /** Map of video items by ID (for O(1) lookup and deduplication) */
-    itemsMap: Map<string, VideoItem>;
-    /** Ordered list of video IDs for rendering */
+    /** Map of content items by ID (for O(1) lookup and deduplication) */
+    itemsMap: Map<string, ContentItem>;
+    /** Ordered list of item IDs for rendering */
     orderedIds: string[];
     /** Current cursor for pagination */
     cursor: string | null;
@@ -249,8 +228,10 @@ interface PlayerError {
  * Used by Lifecycle Manager for state restoration
  */
 interface SessionSnapshot {
-    /** Video items from feed (for offline restore) */
-    items: VideoItem[];
+    /** Content items from feed (for offline restore) */
+    items: ContentItem[];
+    /** @deprecated Use items instead. Will be removed in v3.0 */
+    videos?: VideoItem[];
     /** Feed cursor position for pagination */
     cursor: string | null;
     /** Index of the currently focused video */
@@ -372,6 +353,19 @@ interface LogEntry {
     stack?: string;
 }
 
+/**
+ * Type guard to check if content is a VideoItem
+ */
+declare function isVideoItem(item: ContentItem): item is VideoItem;
+/**
+ * Type guard to check if content is an Article
+ */
+declare function isArticle(item: ContentItem): item is Article;
+/**
+ * @deprecated Use isArticle instead. Will be removed in v3.0
+ */
+declare function isImagePost(item: ContentItem): item is Article;
+
 /**
  * Comment Feature Types
  * Supports nested replies (1 level), pagination, and optimistic updates
@@ -607,7 +601,7 @@ declare const DEFAULT_COMMENT_CONFIG: CommentConfig;
 /**
  * IDataSource - Data Port Interface
  *
- * This interface defines the contract for fetching video data.
+ * This interface defines the contract for fetching feed content.
  * SDK core never knows about specific APIs - it only talks to this interface.
  *
  * Implementations:
@@ -631,7 +625,7 @@ declare const DEFAULT_COMMENT_CONFIG: CommentConfig;
  */
 interface IDataSource {
     /**
-     * Fetch a page of videos for the feed
+     * Fetch a page of items for the feed
      *
      * @param cursor - Pagination cursor from previous response (undefined for first page)
      * @returns Promise resolving to feed response with items and pagination info
@@ -644,21 +638,25 @@ interface IDataSource {
      */
     fetchFeed(cursor?: string): Promise<FeedResponse>;
     /**
-     * Get detailed information for a specific video
+     * Get detailed information for a specific content item
      *
-     * @param id - Video ID
-     * @returns Promise resolving to video item details
-     * @throws Error if video not found or network fails
+     * @param id - Content ID
+     * @returns Promise resolving to content item details
+     * @throws Error if content not found or network fails
      *
      * Implementation notes:
      * - May return cached data if available
-     * - Should throw specific error for 404 (video deleted/not found)
+     * - Should throw specific error for 404 (content deleted/not found)
      */
-    getVideoDetail(id: string): Promise<VideoItem>;
+    getContentDetail(id: string): Promise<ContentItem>;
     /**
-     * Optional: Prefetch videos for smoother scrolling
+     * @deprecated Use getContentDetail instead. Will be removed in v3.0
+     */
+    getVideoDetail?(id: string): Promise<VideoItem>;
+    /**
+     * Optional: Prefetch content for smoother scrolling
      *
-     * @param ids - Array of video IDs to prefetch
+     * @param ids - Array of content IDs to prefetch
      * @returns Promise resolving when prefetch is complete
      *
      * Implementation notes:
@@ -825,7 +823,7 @@ interface IInteraction {
  * Data structure for prefetch cache
  *
  * Stored in localStorage for instant feed loading on fresh app open.
- * Contains video metadata (NOT video data) for immediate display.
+ * Contains content metadata (NOT heavy media data) for immediate display.
  *
  * @example
  * ```typescript
@@ -839,10 +837,10 @@ interface IInteraction {
  */
 interface PrefetchCacheData {
     /**
-     * Cached video items (tail of feed - videos user hasn't seen)
+     * Cached content items (tail of feed - items user hasn't seen)
      * These are shown instantly on fresh load
      */
-    items: VideoItem[];
+    items: ContentItem[];
     /**
      * Timestamp when cache was saved
      * Used for debugging and potential TTL features
@@ -939,6 +937,18 @@ interface IStorage {
      * - Used for debugging and LRU eviction
      */
     keys(): Promise<string[]>;
+    /**
+     * Get a value from storage synchronously (optional)
+     *
+     * Used for zero-flash cache hydration during React render phase.
+     * Only implement if the underlying storage supports synchronous reads
+     * (e.g., localStorage). Async-only storage (e.g., IndexedDB) should
+     * not implement this.
+     *
+     * @param key - Storage key
+     * @returns The stored value or null if not found / not supported
+     */
+    getSync?<T>(key: string): T | null;
 }
 /**
  * Specialized interface for session snapshot storage
@@ -1789,7 +1799,9 @@ type UIComponent<P = object> = (props: P) => UINode;
  * Feed state from useFeed() hook
  */
 interface UIFeedState {
-    /** List of video items */
+    /** List of content items (Video or Article) */
+    items: ContentItem[];
+    /** @deprecated Use items instead. Will be removed in v3.0 */
     videos: VideoItem[];
     /** Whether feed is loading */
     isLoading: boolean;
@@ -1897,7 +1909,7 @@ interface UIInteractionState {
 interface UIInteractionActions {
     /** Toggle like state (debounced - updates UI immediately, API call is debounced) */
     toggleLike: () => void;
-    /** Share video */
+    /** Share content */
     share: () => Promise<void>;
     /** Open comments */
     openComments: () => void;
@@ -1923,16 +1935,18 @@ interface UIAuthorActions {
     openProfile: () => void;
 }
 /**
- * Video info state for VideoInfo component
+ * Content info state for VideoInfo/ArticleInfo component
  */
 interface UIVideoInfoState {
-    /** Video item */
-    video: VideoItem;
+    /** Content item (Video or Article) */
+    content: ContentItem;
+    /** @deprecated Use content instead. Will be removed in v3.0 */
+    video?: VideoItem;
     /** Author name */
     authorName: string;
     /** Whether author is verified */
     isVerified: boolean;
-    /** Video caption/title */
+    /** Content caption/title */
     caption: string;
     /** Hashtags array */
     hashtags: string[];
@@ -1960,10 +1974,41 @@ interface UIVideoInfoActions {
     onLocationClick?: () => void;
 }
 /**
- * VideoFeed headless component props
+ * Article-specific UI state
  */
-interface VideoFeedHeadlessProps {
-    /** Feed state (videos, loading, etc.) */
+interface UIArticleState {
+    /** Article item */
+    article: Article;
+    /** Current image index */
+    currentImageIndex: number;
+    /** Whether music is playing */
+    isMusicPlaying: boolean;
+    /** Last music toggle timestamp (for synchronization) */
+    lastMusicToggleTime: number;
+}
+/**
+ * Article-specific UI actions
+ */
+interface UIArticleActions {
+    /** Set current image index */
+    setCurrentIndex: (index: number) => void;
+    /** Toggle music playback */
+    toggleMusic: () => void;
+    /** Toggle like state */
+    toggleLike: () => Promise<void>;
+    /** Toggle bookmark state */
+    toggleBookmark: () => void;
+    /** Open detail view */
+    openDetail: () => void;
+    /** Close detail view */
+    closeDetail: () => void;
+}
+/**
+ * Feed headless component props
+ * Position-based virtual scroller for mixed content.
+ */
+interface FeedHeadlessProps {
+    /** Feed state (items, loading, etc.) */
     feedState: UIFeedState;
     /** Swipe/scroll state */
     swipeState: UISwipeState;
@@ -1971,8 +2016,8 @@ interface VideoFeedHeadlessProps {
     height?: number | string;
     /** Additional CSS classes */
     className?: string;
-    /** Render function for each video slot */
-    renderSlot: (video: VideoItem, index: number) => UINode;
+    /** Render function for each content slot */
+    renderSlot: (item: ContentItem, index: number) => UINode;
     /** Called when active index changes */
     onIndexChange?: (index: number) => void;
     /** Called when reaching near end of feed */
@@ -1980,6 +2025,8 @@ interface VideoFeedHeadlessProps {
     /** Threshold for triggering onEndReached (default: 2) */
     endReachedThreshold?: number;
 }
+/** @deprecated Use FeedHeadlessProps instead. Will be removed in v3.0 */
+type VideoFeedHeadlessProps = FeedHeadlessProps;
 /**
  * VideoSlot headless component props
  */
@@ -2153,6 +2200,84 @@ interface VideoInfoHeadlessProps {
     /** Children (for compound pattern) */
     children?: UINode;
 }
+/**
+ * ArticleSlot headless component props
+ */
+interface ArticleSlotHeadlessProps {
+    /** Article to display */
+    article: Article;
+    /** Whether slot is active */
+    isActive: boolean;
+    /** Current image index */
+    currentImageIndex: number;
+    /** Index change handler */
+    onImageIndexChange: (index: number) => void;
+    /** Music toggle handler */
+    onToggleMusic: () => void;
+    /** Whether music is playing */
+    isMusicPlaying: boolean;
+    /** Last music toggle timestamp */
+    lastMusicToggleTime?: number;
+    /** Double tap handler (usually for like) */
+    onDoubleTap?: () => void;
+    /** "Read More" click handler */
+    onReadMoreClick?: () => void;
+    /** Long press handler */
+    onLongPress?: () => void;
+    /** Single tap handler */
+    onTap?: () => void;
+    /** Swipe direction change handler (for gesture locking) */
+    onSwipeDirectionChange?: (direction: 'horizontal' | 'vertical' | null) => void;
+    /** Children (overlay content) */
+    children?: UINode;
+    /** Additional CSS classes */
+    className?: string;
+    /** Music info (optional) */
+    music?: {
+        id: string;
+        title: string;
+        artist: string;
+    };
+}
+/** @deprecated Use ArticleSlotHeadlessProps instead */
+type ImagePostSlotHeadlessProps = ArticleSlotHeadlessProps;
+/**
+ * DetailView headless component props
+ */
+interface DetailViewHeadlessProps {
+    /** Whether open */
+    isOpen: boolean;
+    /** Close handler */
+    onClose: () => void;
+    /** Article to display */
+    article: Article;
+    /** Initial index */
+    initialImageIndex?: number;
+    /** Header title */
+    headerTitle?: string;
+    /** Liked state */
+    isLiked?: boolean;
+    /** Following state */
+    isFollowing?: boolean;
+    /** Bookmarked state */
+    isBookmarked?: boolean;
+    /** Like handler */
+    onLike?: () => void;
+    /** Comment handler */
+    onComment?: () => void;
+    /** Share handler */
+    onShare?: () => void;
+    /** Bookmark handler */
+    onBookmark?: () => void;
+    /** Follow handler */
+    onFollow?: () => void;
+    /** Gesture lock handler */
+    onGestureLock?: (locked: boolean) => void;
+    /** Children (compound components) */
+    children?: UINode;
+    /** Custom bottom bar renderer */
+    renderBottomBar?: (props: any) => UINode;
+}
 /**
  * ErrorBoundary component props
  */
@@ -2184,15 +2309,17 @@ interface SkeletonProps {
     className?: string;
 }
 /**
- * VideoFeed wired component props
+ * Feed wired component props
  * feedState and swipeState are injected by SDK
  */
-interface VideoFeedProps extends Omit<VideoFeedHeadlessProps, 'feedState' | 'swipeState'> {
+interface FeedProps extends Omit<FeedHeadlessProps, 'feedState' | 'swipeState'> {
     /** Override feed state (optional) */
     feedState?: UIFeedState;
     /** Override swipe state (optional) */
     swipeState?: UISwipeState;
 }
+/** @deprecated Use FeedProps instead. Will be removed in v3.0 */
+type VideoFeedProps = FeedProps;
 /**
  * VideoSlot wired component props
  * resourceState, playerState, playerControls are injected by SDK
@@ -2218,8 +2345,10 @@ interface VideoPlayerWiredProps extends Partial<VideoPlayerHeadlessProps> {
  * interactionState and interactionActions are injected by SDK
  */
 interface ActionBarProps extends Omit<ActionBarHeadlessProps, 'interactionState' | 'interactionActions'> {
-    /** Video to get interaction state for */
-    video: VideoItem;
+    /** Content to get interaction state for */
+    content: ContentItem;
+    /** @deprecated Use content instead. Will be removed in v3.0 */
+    video?: VideoItem;
     /** Override interaction state (optional) */
     interactionState?: UIInteractionState;
     /** Override interaction actions (optional) */
@@ -2230,8 +2359,10 @@ interface ActionBarProps extends Omit<ActionBarHeadlessProps, 'interactionState'
  * authorState and authorActions are injected by SDK
  */
 interface AuthorInfoProps extends Omit<AuthorInfoHeadlessProps, 'authorState' | 'authorActions'> {
-    /** Video to get author from */
-    video: VideoItem;
+    /** Content to get author from */
+    content: ContentItem;
+    /** @deprecated Use content instead. Will be removed in v3.0 */
+    video?: VideoItem;
     /** Override author state (optional) */
     authorState?: UIAuthorState;
     /** Override author actions (optional) */
@@ -2242,8 +2373,10 @@ interface AuthorInfoProps extends Omit<AuthorInfoHeadlessProps, 'authorState' |
  * videoInfoState and videoInfoActions are injected by SDK
  */
 interface VideoInfoProps extends Omit<VideoInfoHeadlessProps, 'videoInfoState' | 'videoInfoActions'> {
-    /** Video to get info from */
-    video: VideoItem;
+    /** Content to get info from */
+    content: ContentItem;
+    /** @deprecated Use content instead. Will be removed in v3.0 */
+    video?: VideoItem;
     /** Override video info state (optional) */
     videoInfoState?: UIVideoInfoState;
     /** Override video info actions (optional) */
@@ -2465,4 +2598,4 @@ type IconComponent = UIComponent<{
  */
 type FormatCountFn = (count: number) => string;
 
-export { type ActionBarHeadlessProps, type ActionBarProps, type ActionButtonHeadlessProps, type AnalyticsConfig, type AnalyticsEvent, type AnalyticsEventType, type Author, type AuthorInfoHeadlessProps, type AuthorInfoProps, type BaseContentItem, type Comment, type CommentAdapterConfig, type CommentAuthor, type CommentConfig, type CommentEndpoints, type CommentInputHeadlessProps, type CommentItem, type CommentItemHeadlessProps, type CommentListResponse, type CommentManagerState, type CommentReportReason, type CommentSheetHeadlessProps, type CommentSheetProps, type CommentState, type CommentTransformers, type ContentItem, type ContentStats, DEFAULT_COMMENT_CONFIG, DEFAULT_COMMENT_ENDPOINTS, type DeleteCommentPayload, type EditCommentPayload, type ErrorBoundaryProps, type FeedResponse, type FeedState, type FormatCountFn, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILocalization, type ILogger, type INetworkAdapter, type IPlaylistDataSource, type IPosterLoader, type ISessionStorage, type IStorage, type IVideoLoader, type IconComponent, type ImagePost, type ImagePostStats, type InternalLogger, type LocalizationConfig, type LogEntry, type LogLevel, type LoggerConfig, type MessageCatalog, type MessageKey, type MessageKey as MessageKeyType, type MessageValue, type MessageValues, type MockCommentAdapterConfig, type MusicInfo, type NetworkQuality, type NetworkType, type OptimisticAction, type PartialMessageCatalog, type PlaybackState, type PlayerError, type PlayerState, type PlaylistCollectionResponse, type PlaylistData, type PlaylistItem, type PlaylistSummary, type PostCommentPayload, type PostReplyPayload, type PrefetchCacheData, type PreloadConfig, type PreloadResult, type PreloadStatus, type ProgressBarHeadlessProps, type ReplyItem, type ReplyItemHeadlessProps, type ReplyListResponse, type ReportCommentPayload, type ReportReason, type SDKConfig, type SessionSnapshot, type SkeletonProps, type UIAuthorActions, type UIAuthorState, type UICommentActions, type UICommentState, type UIComponent, type UIFeedState, type UIInteractionActions, type UIInteractionState, type UINode, type UIPlayerControls, type UIPlayerState, type UIRef, type UIResourceState, type UISwipeState, type UIVideoInfoActions, type UIVideoInfoState, type VideoFeedHeadlessProps, type VideoFeedProps, type VideoInfoHeadlessProps, type VideoInfoProps, type VideoItem, type VideoPlayerHeadlessProps, type VideoPlayerWiredProps, type VideoQuality, type VideoSlotHeadlessProps, type VideoSlotProps, type VideoSource, type VideoStats, type WiredComponent, type WiredComponentConfig, isImagePost, isVideoItem };
+export { type ActionBarHeadlessProps, type ActionBarProps, type ActionButtonHeadlessProps, type AnalyticsConfig, type AnalyticsEvent, type AnalyticsEventType, type Article, type ArticleSlotHeadlessProps, type ArticleStats, type Author, type AuthorInfoHeadlessProps, type AuthorInfoProps, type BaseContentItem, type Comment, type CommentAdapterConfig, type CommentAuthor, type CommentConfig, type CommentEndpoints, type CommentInputHeadlessProps, type CommentItem, type CommentItemHeadlessProps, type CommentListResponse, type CommentManagerState, type CommentReportReason, type CommentSheetHeadlessProps, type CommentSheetProps, type CommentState, type CommentTransformers, type ContentItem, type ContentStats, DEFAULT_COMMENT_CONFIG, DEFAULT_COMMENT_ENDPOINTS, type DeleteCommentPayload, type DetailViewHeadlessProps, type EditCommentPayload, type ErrorBoundaryProps, type FeedResponse, type FeedState, type FormatCountFn, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILocalization, type ILogger, type INetworkAdapter, type IPlaylistDataSource, type IPosterLoader, type ISessionStorage, type IStorage, type IVideoLoader, type IconComponent, type ImagePost, type ImagePostSlotHeadlessProps, type ImagePostStats, type InternalLogger, type LocalizationConfig, type LogEntry, type LogLevel, type LoggerConfig, type MessageCatalog, type MessageKey, type MessageKey as MessageKeyType, type MessageValue, type MessageValues, type MockCommentAdapterConfig, type MusicInfo, type NetworkQuality, type NetworkType, type OptimisticAction, type PartialMessageCatalog, type PlaybackState, type PlayerError, type PlayerState, type PlaylistCollectionResponse, type PlaylistData, type PlaylistItem, type PlaylistSummary, type PostCommentPayload, type PostReplyPayload, type PrefetchCacheData, type PreloadConfig, type PreloadResult, type PreloadStatus, type ProgressBarHeadlessProps, type ReplyItem, type ReplyItemHeadlessProps, type ReplyListResponse, type ReportCommentPayload, type ReportReason, type SDKConfig, type SessionSnapshot, type SkeletonProps, type UIArticleActions, type UIArticleState, type UIAuthorActions, type UIAuthorState, type UICommentActions, type UICommentState, type UIComponent, type UIFeedState, type UIInteractionActions, type UIInteractionState, type UINode, type UIPlayerControls, type UIPlayerState, type UIRef, type UIResourceState, type UISwipeState, type UIVideoInfoActions, type UIVideoInfoState, type VideoFeedHeadlessProps, type VideoFeedProps, type VideoInfoHeadlessProps, type VideoInfoProps, type VideoItem, type VideoPlayerHeadlessProps, type VideoPlayerWiredProps, type VideoQuality, type VideoSlotHeadlessProps, type VideoSlotProps, type VideoSource, type WiredComponent, type WiredComponentConfig, isArticle, isImagePost, isVideoItem };

package/dist/index.js

@@ -1,9 +1,15 @@
-// src/types.ts
+// src/type-guards.ts
 function isVideoItem(item) {
   return item.type === "video";
 }
+function isArticle(item) {
+  return item.type === "article";
+}
 function isImagePost(item) {
-  return item.type === "image";
+  if (process.env.NODE_ENV !== "production") {
+    console.warn("[xhub-short] isImagePost is deprecated. Use isArticle instead.");
+  }
+  return isArticle(item);
 }
 
 // src/comment-types.ts
@@ -33,4 +39,4 @@ var DEFAULT_COMMENT_ENDPOINTS = {
   report: "/comments/:id/report"
 };
 
-export { DEFAULT_COMMENT_CONFIG, DEFAULT_COMMENT_ENDPOINTS, isImagePost, isVideoItem };
+export { DEFAULT_COMMENT_CONFIG, DEFAULT_COMMENT_ENDPOINTS, isArticle, isImagePost, isVideoItem };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xhub-short/contracts",
   "sideEffects": false,
-  "version": "0.1.0-beta.14",
+  "version": "0.1.0-beta.17",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -20,14 +20,20 @@
     "dist"
   ],
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "tsup": "^8.3.0",
     "typescript": "^5.7.0",
-    "@xhub-short/tsconfig": "0.0.1-beta.2"
+    "vitest": "^2.1.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "@xhub-short/tsconfig": "0.0.1-beta.2",
+    "@xhub-short/vitest-config": "0.1.0-beta.13"
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "clean": "rm -rf dist"
   }
 }