@shortkitsdk/react-native 0.2.6 → 0.2.12

package/src/specs/NativeShortKitModule.ts

@@ -22,6 +22,7 @@ type CurrentItemEvent = Readonly<{
   author?: string;
   articleUrl?: string;
   commentCount?: Int32;
+  fallbackUrl?: string;
 }>;
 
 type TimeUpdateEvent = Readonly<{
@@ -84,16 +85,16 @@ type PrefetchedAheadCountEvent = Readonly<{
 }>;
 
 type RemainingContentCountEvent = Readonly<{
+  feedId: string;
   count: Int32;
 }>;
 
-type ErrorEvent = Readonly<{
-  code: string;
-  message: string;
-}>;
+type DismissEvent = Readonly<{}>;
+
+type RefreshRequestedEvent = Readonly<{}>;
 
-type ShareTappedEvent = Readonly<{
-  item: string; // JSON-serialized ContentItem
+type DidFetchContentItemsEvent = Readonly<{
+  items: string; // JSON-serialized ContentItem[]
 }>;
 
 type SurveyResponseEvent = Readonly<{
@@ -102,50 +103,75 @@ type SurveyResponseEvent = Readonly<{
   optionText: string;
 }>;
 
-type OverlayConfigureEvent = Readonly<{
-  item: string; // JSON-serialized ContentItem
+type ContentTappedEvent = Readonly<{
+  contentId: string;
+  index: Int32;
 }>;
 
-type OverlayActivateEvent = Readonly<{
-  item: string; // JSON-serialized ContentItem
+type FeedReadyEvent = Readonly<{
+  feedId: string;
 }>;
 
-type OverlayResetEvent = Readonly<{
-  item: string; // JSON-serialized ContentItem
+// --- Overlay per-surface event payload types ---
+
+type OverlayActiveEvent = Readonly<{
+  surfaceId: string;
+  isActive: boolean;
 }>;
 
-type ContentTappedEvent = Readonly<{
-  contentId: string;
-  index: Int32;
+type OverlayPlayerStateEvent = Readonly<{
+  surfaceId: string;
+  playerState: string;
 }>;
 
-type CarouselOverlayConfigureEvent = Readonly<{
-  item: string; // JSON-serialized ImageCarouselItem
+type OverlayMutedEvent = Readonly<{
+  surfaceId: string;
+  isMuted: boolean;
 }>;
 
-type CarouselOverlayActivateEvent = Readonly<{
-  item: string; // JSON-serialized ImageCarouselItem
+type OverlayPlaybackRateEvent = Readonly<{
+  surfaceId: string;
+  playbackRate: Double;
 }>;
 
-type CarouselOverlayResetEvent = Readonly<{}>;
+type OverlayCaptionsEnabledEvent = Readonly<{
+  surfaceId: string;
+  captionsEnabled: boolean;
+}>;
 
-type CarouselPageChangedEvent = Readonly<{
-  page: Int32;
-  pageCount: Int32;
+type OverlayActiveCueEvent = Readonly<{
+  surfaceId: string;
+  activeCue: string;
 }>;
 
-type OverlayTapEvent = Readonly<{}>;
+type OverlayFeedScrollPhaseEvent = Readonly<{
+  surfaceId: string;
+  feedScrollPhase: string;
+}>;
 
-type OverlayDoubleTapEvent = Readonly<{
-  x: Double;
-  y: Double;
+type OverlayTimeUpdateEvent = Readonly<{
+  surfaceId: string;
+  current: Double;
+  duration: Double;
+  buffered: Double;
+}>;
+
+type OverlayFullStateEvent = Readonly<{
+  surfaceId: string;
+  isActive: boolean;
+  playerState: string;
+  isMuted: boolean;
+  playbackRate: Double;
+  captionsEnabled: boolean;
+  activeCue: string;
+  feedScrollPhase: string;
 }>;
 
 export interface Spec extends TurboModule {
   // --- Lifecycle ---
   initialize(
     apiKey: string,
-    config: string, // JSON-serialized FeedConfig
+    hasLoadingView: boolean,
     clientAppName?: string,
     clientAppVersion?: string,
     customDimensions?: string, // JSON-serialized Record<string, string>
@@ -171,17 +197,16 @@ export interface Spec extends TurboModule {
   setMaxBitrate(bitrate: Double): void;
 
   // --- Custom feed ---
-  setFeedItems(items: string): void;
-  appendFeedItems(items: string): void;
-  fetchContent(limit: Int32): Promise<string>;
+  setFeedItems(feedId: string, items: string): void;
+  appendFeedItems(feedId: string, items: string): void;
+  fetchContent(limit: Int32, filterJSON: string | null): Promise<string>;
+  applyFilter(feedId: string, filterJSON: string | null): void;
+  preloadFeed(configJSON: string, itemsJSON: string | null): Promise<string>;
 
   // --- Storyboard / seek thumbnails ---
   prefetchStoryboard(playbackId: string): void;
   getStoryboardData(playbackId: string): Promise<string>;
 
-  // --- Overlay lifecycle ---
-  notifyOverlayReady(): void;
-
   // --- Event emitters ---
   readonly onPlayerStateChanged: EventEmitter<PlayerStateEvent>;
   readonly onCurrentItemChanged: EventEmitter<CurrentItemEvent>;
@@ -197,19 +222,23 @@ export interface Spec extends TurboModule {
   readonly onFormatChange: EventEmitter<FormatChangeEvent>;
   readonly onPrefetchedAheadCountChanged: EventEmitter<PrefetchedAheadCountEvent>;
   readonly onRemainingContentCountChanged: EventEmitter<RemainingContentCountEvent>;
-  readonly onError: EventEmitter<ErrorEvent>;
-  readonly onShareTapped: EventEmitter<ShareTappedEvent>;
   readonly onSurveyResponse: EventEmitter<SurveyResponseEvent>;
-  readonly onOverlayConfigure: EventEmitter<OverlayConfigureEvent>;
-  readonly onOverlayActivate: EventEmitter<OverlayActivateEvent>;
-  readonly onOverlayReset: EventEmitter<OverlayResetEvent>;
-  readonly onOverlayTap: EventEmitter<OverlayTapEvent>;
-  readonly onOverlayDoubleTap: EventEmitter<OverlayDoubleTapEvent>;
   readonly onContentTapped: EventEmitter<ContentTappedEvent>;
-  readonly onCarouselOverlayConfigure: EventEmitter<CarouselOverlayConfigureEvent>;
-  readonly onCarouselOverlayActivate: EventEmitter<CarouselOverlayActivateEvent>;
-  readonly onCarouselOverlayReset: EventEmitter<CarouselOverlayResetEvent>;
-  readonly onCarouselPageChanged: EventEmitter<CarouselPageChangedEvent>;
+  readonly onDismiss: EventEmitter<DismissEvent>;
+  readonly onRefreshRequested: EventEmitter<RefreshRequestedEvent>;
+  readonly onDidFetchContentItems: EventEmitter<DidFetchContentItemsEvent>;
+  readonly onFeedReady: EventEmitter<FeedReadyEvent>;
+
+  // --- Overlay per-surface events ---
+  readonly onOverlayActiveChanged: EventEmitter<OverlayActiveEvent>;
+  readonly onOverlayPlayerStateChanged: EventEmitter<OverlayPlayerStateEvent>;
+  readonly onOverlayMutedChanged: EventEmitter<OverlayMutedEvent>;
+  readonly onOverlayPlaybackRateChanged: EventEmitter<OverlayPlaybackRateEvent>;
+  readonly onOverlayCaptionsEnabledChanged: EventEmitter<OverlayCaptionsEnabledEvent>;
+  readonly onOverlayActiveCueChanged: EventEmitter<OverlayActiveCueEvent>;
+  readonly onOverlayFeedScrollPhaseChanged: EventEmitter<OverlayFeedScrollPhaseEvent>;
+  readonly onOverlayTimeUpdate: EventEmitter<OverlayTimeUpdateEvent>;
+  readonly onOverlayFullState: EventEmitter<OverlayFullStateEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('ShortKitModule');

package/src/specs/ShortKitFeedViewNativeComponent.ts

@@ -1,10 +1,11 @@
 import type { HostComponent, ViewProps } from 'react-native';
 import { codegenNativeComponent } from 'react-native';
-import type { WithDefault } from 'react-native/Libraries/Types/CodegenTypes';
 
 export interface NativeProps extends ViewProps {
   config: string;
-  overlayType?: WithDefault<'none' | 'custom', 'none'>;
+  feedId?: string;
+  startAtItemId?: string;
+  preloadId?: string;
 }
 
 export default codegenNativeComponent<NativeProps>(

package/src/types.ts

@@ -1,29 +1,45 @@
+import type React from 'react';
 import type { ViewStyle } from 'react-native';
 
 // --- Configuration ---
 
 export type FeedSource = 'algorithmic' | 'custom';
 
+export interface FeedFilter {
+  tags?: string[];
+  section?: string;
+  author?: string;
+  contentType?: string;
+  metadata?: Record<string, string>;
+}
+
+export type CaptionSource = 'embedded' | 'external' | 'generated';
+
 export interface FeedConfig {
   feedHeight?: FeedHeight;
+  scrollAxis?: ScrollAxis;
   overlay?: OverlayConfig;
   carouselOverlay?: CarouselOverlayConfig;
   surveyMode?: SurveyMode;
   muteOnStart?: boolean;
   feedSource?: FeedSource;
+  autoplay?: boolean;
+  filter?: FeedFilter;
 }
 
 export type FeedHeight =
   | { type: 'fullscreen' }
   | { type: 'percentage'; value: number };
 
+export type ScrollAxis = 'vertical' | 'horizontal';
+
 export type OverlayConfig =
   | 'none'
-  | { type: 'custom'; component: React.ComponentType };
+  | { type: 'custom'; name: string; component: React.ComponentType<OverlayProps> };
 
 export type CarouselOverlayConfig =
   | 'none'
-  | { type: 'custom'; component: React.ComponentType };
+  | { type: 'custom'; name: string; component: React.ComponentType<CarouselOverlayProps> };
 
 export type SurveyMode =
   | 'none'
@@ -44,6 +60,7 @@ export interface ContentItem {
   author?: string;
   articleUrl?: string;
   commentCount?: number;
+  fallbackUrl?: string;
 }
 
 // --- Custom Feed Types ---
@@ -56,7 +73,6 @@ export interface CarouselImage {
 export interface ImageCarouselItem {
   id: string;
   images: CarouselImage[];
-  autoScrollInterval?: number;
   caption?: string;
   title?: string;
   description?: string;
@@ -66,7 +82,7 @@ export interface ImageCarouselItem {
 }
 
 export type FeedInput =
-  | { type: 'video'; playbackId: string }
+  | { type: 'video'; playbackId: string; fallbackUrl?: string }
   | { type: 'imageCarousel'; item: ImageCarouselItem };
 
 export type JSONValue =
@@ -97,7 +113,10 @@ export interface StoryboardData {
 export interface CaptionTrack {
   language: string;
   label: string;
-  sourceUrl: string;
+  source?: CaptionSource;
+  url?: string;
+  /** @deprecated Use `url` instead. */
+  sourceUrl?: string;
 }
 
 export interface PlayerTime {
@@ -148,35 +167,89 @@ export interface SurveyOption {
   text: string;
 }
 
-export interface ShortKitError {
-  code: string;
-  message: string;
+// --- Overlay Props ---
+
+/** Props passed to video overlay components rendered inside feed cells. */
+export interface OverlayProps {
+  /** The content item for this cell. */
+  item: ContentItem;
+  /** Whether this cell is the active playback cell. */
+  isActive: boolean;
+  /** Current player state. */
+  playerState: PlayerState;
+  /** Current playback time. Only updates when isActive is true. */
+  time: PlayerTime;
+  /** Whether audio is muted. */
+  isMuted: boolean;
+  /** Current playback speed. */
+  playbackRate: number;
+  /** Whether captions are enabled. */
+  captionsEnabled: boolean;
+  /** The currently active caption cue, or null. */
+  activeCue: { text: string; startTime: number; endTime: number } | null;
+  /** Current feed scroll phase — use to fade overlay during swipes. */
+  feedScrollPhase: FeedScrollPhase | null;
+}
+
+/** Props passed to carousel overlay components rendered inside feed cells. */
+export interface CarouselOverlayProps {
+  /** The carousel item for this cell. */
+  item: ImageCarouselItem;
 }
 
 // --- Provider Props ---
 
 export interface ShortKitProviderProps {
   apiKey: string;
-  config: FeedConfig;
   userId?: string;
 
   clientAppName?: string;
   clientAppVersion?: string;
   customDimensions?: Record<string, string>;
   children: React.ReactNode;
+  /** Custom loading view rendered while the feed loads or during filter changes.
+   *  When omitted, the SDK uses a default spinner. */
+  loadingViewComponent?: React.ComponentType<{}>;
 }
 
 // --- Feed Component Props ---
 
 export interface ShortKitFeedProps {
+  config?: FeedConfig;
+  preloadId?: string;
   style?: ViewStyle;
-  onError?: (error: ShortKitError) => void;
-  onShareTapped?: (item: ContentItem) => void;
+  /** Item ID to scroll to on initial load. */
+  startAtItemId?: string;
   onSurveyResponse?: (surveyId: string, option: SurveyOption) => void;
   onLoop?: (event: LoopEvent) => void;
   onFeedTransition?: (event: FeedTransitionEvent) => void;
   onFormatChange?: (event: FormatChangeEvent) => void;
   onContentTapped?: (contentId: string, index: number) => void;
+  /** Called when the user dismisses the feed (swipe-down or back gesture). */
+  onDismiss?: () => void;
+  /** Called when the user pulls to refresh in custom feed mode. */
+  onRefreshRequested?: () => void;
+  /** Called when the SDK fetches content items from the algorithmic feed.
+   *  Use to pre-fetch your own metadata for the given items. */
+  onDidFetchContentItems?: (items: ContentItem[]) => void;
+  /** Called when the number of remaining items in this feed changes. */
+  onRemainingContentCountChange?: (count: number) => void;
+  /** Called once when this feed has loaded content and assigned a player
+   *  to the first cell. Use to dismiss a splash screen or loading overlay. */
+  onFeedReady?: () => void;
+}
+
+/**
+ * Imperative handle for per-feed-instance operations.
+ * Obtained via `ref` on `<ShortKitFeed>`.
+ */
+export interface ShortKitFeedHandle {
+  /** Replace all items in this feed instance. */
+  setFeedItems: (items: FeedInput[]) => void;
+  /** Append items to this feed instance. */
+  appendFeedItems: (items: FeedInput[]) => void;
+  /** Apply a content filter to this feed instance. Pass null to clear. */
+  applyFilter: (filter: FeedFilter | null) => void;
 }
 
 // --- Single Player Config ---
@@ -232,8 +305,6 @@ export interface ShortKitWidgetProps {
 export interface ShortKitPlayerState {
   playerState: PlayerState;
   currentItem: ContentItem | null;
-  nextItem: ContentItem | null;
-  activeCellType: 'video' | 'carousel' | null;
   time: PlayerTime;
   isMuted: boolean;
   playbackRate: number;
@@ -241,11 +312,8 @@ export interface ShortKitPlayerState {
   activeCaptionTrack: CaptionTrack | null;
   activeCue: { text: string; startTime: number; endTime: number } | null;
   prefetchedAheadCount: number;
-  remainingContentCount: number;
   isActive: boolean;
   feedScrollPhase: FeedScrollPhase | null;
-  lastOverlayTap: number;
-  lastOverlayDoubleTap: { x: number; y: number; id: number } | null;
 
   play: () => void;
   pause: () => void;

package/src/useShortKit.ts

@@ -16,9 +16,7 @@ export function useShortKit() {
   return {
     setUserId: context.setUserId,
     clearUserId: context.clearUserId,
-    setFeedItems: context.setFeedItems,
-    appendFeedItems: context.appendFeedItems,
     fetchContent: context.fetchContent,
-    remainingContentCount: context.remainingContentCount,
+    preloadFeed: context.preloadFeed,
   };
 }

package/src/useShortKitPlayer.ts

@@ -7,6 +7,12 @@ import type { ShortKitPlayerState } from './types';
  *
  * Must be used within a `<ShortKitProvider>`.
  *
+ * **Note:** This hook is NOT available inside overlay components registered via
+ * `config.overlay.component` / `config.carouselOverlay.component`. Overlays run
+ * in isolated React surfaces and receive data via props (OverlayProps /
+ * CarouselOverlayProps). Use `ShortKitCommands` for imperative player control
+ * from overlays.
+ *
  * @returns Player state (playerState, currentItem, time, etc.) and
  *          command functions (play, pause, seek, etc.).
  */
@@ -16,19 +22,13 @@ export function useShortKitPlayer(): ShortKitPlayerState {
     throw new Error('useShortKitPlayer must be used within a ShortKitProvider');
   }
 
-  // Return only player-related state and commands (exclude SDK operations,
-  // carousel state, and internal fields)
+  // Return only player-related state and commands (exclude SDK operations)
   const {
     setUserId: _setUserId,
     clearUserId: _clearUserId,
     setFeedItems: _setFeedItems,
     appendFeedItems: _appendFeedItems,
     fetchContent: _fetchContent,
-    currentCarouselItem: _currentCarouselItem,
-    nextCarouselItem: _nextCarouselItem,
-    isCarouselActive: _isCarouselActive,
-    _overlayConfig: _overlay,
-    _carouselOverlayConfig: _carouselOverlay,
     ...playerState
   } = context;
 

package/android/src/main/java/com/shortkit/reactnative/ShortKitCarouselOverlayBridge.kt

@@ -1,48 +0,0 @@
-package com.shortkit.reactnative
-
-import android.content.Context
-import android.graphics.Color
-import android.widget.FrameLayout
-import com.facebook.react.bridge.Arguments
-import com.shortkit.sdk.model.ImageCarouselItem
-import com.shortkit.sdk.overlay.CarouselOverlay
-import kotlinx.serialization.encodeToString
-import kotlinx.serialization.json.Json
-
-/**
- * A transparent [FrameLayout] that implements [CarouselOverlay] and bridges
- * carousel overlay lifecycle calls to JS events via [ShortKitModule].
- *
- * The actual carousel overlay UI is rendered by React Native on the JS side
- * through the `CarouselOverlayManager` component. This view simply relays
- * the SDK lifecycle events so the JS carousel overlay knows when to
- * configure, activate, reset, etc.
- *
- * Android equivalent of iOS `ShortKitCarouselOverlayBridge.swift`.
- */
-class ShortKitCarouselOverlayBridge(context: Context) : FrameLayout(context), CarouselOverlay {
-
-    init {
-        setBackgroundColor(Color.TRANSPARENT)
-    }
-
-    override fun configure(item: ImageCarouselItem) {
-        val json = Json.encodeToString(item)
-        val params = Arguments.createMap().apply {
-            putString("item", json)
-        }
-        ShortKitModule.shared?.emitCarouselOverlayEvent("onCarouselOverlayConfigure", params)
-    }
-
-    override fun resetState() {
-        ShortKitModule.shared?.emitCarouselOverlayEvent("onCarouselOverlayReset", Arguments.createMap())
-    }
-
-    override fun fadeOutForTransition() {
-        ShortKitModule.shared?.emitCarouselOverlayEvent("onCarouselOverlayFadeOut", Arguments.createMap())
-    }
-
-    override fun restoreFromTransition() {
-        ShortKitModule.shared?.emitCarouselOverlayEvent("onCarouselOverlayRestore", Arguments.createMap())
-    }
-}

package/android/src/main/java/com/shortkit/reactnative/ShortKitOverlayBridge.kt

@@ -1,128 +0,0 @@
-package com.shortkit.reactnative
-
-import android.content.Context
-import android.graphics.Color
-import android.os.Handler
-import android.os.Looper
-import android.view.GestureDetector
-import android.view.MotionEvent
-import android.widget.FrameLayout
-import com.facebook.react.bridge.Arguments
-import com.shortkit.ContentItem
-import com.shortkit.FeedOverlay
-import com.shortkit.ShortKitPlayer
-
-/**
- * A transparent [FrameLayout] that implements [FeedOverlay] and bridges
- * overlay lifecycle calls to JS events via [ShortKitModule].
- *
- * The actual overlay UI is rendered by React Native on the JS side through
- * the `OverlayManager` component. This view simply relays the SDK lifecycle
- * events so the JS overlay knows when to configure, activate, reset, etc.
- *
- * Android equivalent of iOS `ShortKitOverlayBridge.swift`.
- */
-class ShortKitOverlayBridge(context: Context) : FrameLayout(context), FeedOverlay {
-
-    // -----------------------------------------------------------------------
-    // State
-    // -----------------------------------------------------------------------
-
-    /**
-     * Stores the last configured [ContentItem] so we can pass it with
-     * lifecycle events that don't receive the item as a parameter.
-     */
-    private var currentItem: ContentItem? = null
-
-    /**
-     * Deferred configure emission — cancelled if [activatePlayback] fires
-     * on the same message-queue iteration (handleSwipe re-configure of the
-     * active cell, not a prefetch for the next cell).
-     */
-    private var pendingConfigureRunnable: Runnable? = null
-
-    private val handler = Handler(Looper.getMainLooper())
-
-    // -----------------------------------------------------------------------
-    // Gestures
-    // -----------------------------------------------------------------------
-
-    private val gestureDetector = GestureDetector(context, object : GestureDetector.SimpleOnGestureListener() {
-        override fun onSingleTapConfirmed(e: MotionEvent): Boolean {
-            ShortKitModule.shared?.emitOverlayEvent("onOverlayTap", Arguments.createMap())
-            return true
-        }
-
-        override fun onDoubleTap(e: MotionEvent): Boolean {
-            val params = Arguments.createMap().apply {
-                putDouble("x", e.x.toDouble())
-                putDouble("y", e.y.toDouble())
-            }
-            ShortKitModule.shared?.emitOverlayEvent("onOverlayDoubleTap", params)
-            return true
-        }
-    })
-
-    // -----------------------------------------------------------------------
-    // Init
-    // -----------------------------------------------------------------------
-
-    init {
-        setBackgroundColor(Color.TRANSPARENT)
-        isClickable = true
-    }
-
-    override fun onTouchEvent(event: MotionEvent): Boolean {
-        return gestureDetector.onTouchEvent(event) || super.onTouchEvent(event)
-    }
-
-    // -----------------------------------------------------------------------
-    // FeedOverlay
-    // -----------------------------------------------------------------------
-
-    override fun attach(player: ShortKitPlayer) {
-        // No-op on the native side. The JS overlay subscribes to player
-        // state via the TurboModule's flow publishers.
-    }
-
-    override fun configure(item: ContentItem) {
-        currentItem = item
-
-        // Defer the configure event by one message-queue tick. If activatePlayback()
-        // fires before then (handleSwipe sequence: configure → reset → activate),
-        // the event is cancelled — preventing nextItem from being overwritten
-        // with the current cell's data.
-        pendingConfigureRunnable?.let { handler.removeCallbacks(it) }
-        val runnable = Runnable {
-            currentItem?.let { ShortKitModule.shared?.emitOverlayEvent("onOverlayConfigure", it) }
-            pendingConfigureRunnable = null
-        }
-        pendingConfigureRunnable = runnable
-        handler.post(runnable)
-    }
-
-    override fun resetPlaybackProgress() {
-        val item = currentItem ?: return
-        ShortKitModule.shared?.emitOverlayEvent("onOverlayReset", item)
-    }
-
-    override fun activatePlayback() {
-        // Cancel the pending configure — it was for the current cell (part of
-        // handleSwipe), not a prefetch for the next cell.
-        pendingConfigureRunnable?.let { handler.removeCallbacks(it) }
-        pendingConfigureRunnable = null
-
-        val item = currentItem ?: return
-        ShortKitModule.shared?.emitOverlayEvent("onOverlayActivate", item)
-    }
-
-    override fun fadeOutForTransition() {
-        val item = currentItem ?: return
-        ShortKitModule.shared?.emitOverlayEvent("onOverlayFadeOut", item)
-    }
-
-    override fun restoreFromTransition() {
-        val item = currentItem ?: return
-        ShortKitModule.shared?.emitOverlayEvent("onOverlayRestore", item)
-    }
-}