@shortkitsdk/react-native 0.2.23 → 0.2.25

package/src/specs/NativeShortKitModule.ts

@@ -109,6 +109,25 @@ type FeedReadyEvent = Readonly<{
   feedId: string;
 }>;
 
+type DownloadStartedEvent = Readonly<{
+  itemId: string;
+}>;
+
+type DownloadProgressEvent = Readonly<{
+  itemId: string;
+  progress: number;
+}>;
+
+type DownloadCompletedEvent = Readonly<{
+  itemId: string;
+  fileUrl: string;
+}>;
+
+type DownloadFailedEvent = Readonly<{
+  itemId: string;
+  error: string;
+}>;
+
 // --- Overlay per-surface event payload types ---
 
 type OverlayActiveEvent = Readonly<{
@@ -158,12 +177,38 @@ type CarouselActiveImageEvent = Readonly<{
   activeImageIndex: Int32;
 }>;
 
+type CarouselItemChangedEvent = Readonly<{
+  surfaceId: string;
+  item: string;              // JSON-serialized ImageCarouselItem (with local file:// URLs where cached)
+  isActive: boolean;
+  activeImageIndex: Int32;
+}>;
+
 type VideoCarouselActiveVideoEvent = Readonly<{
   surfaceId: string;
   activeVideo: string;
   activeVideoIndex: Int32;
 }>;
 
+type VideoCarouselItemChangedEvent = Readonly<{
+  surfaceId: string;
+  carouselItem: string;         // JSON-serialized VideoCarouselItem
+  activeVideo: string | null;   // JSON-serialized ContentItem; null when item has no videos
+  activeVideoIndex: Int32;
+  isActive: boolean;
+  playerState: string;
+  isMuted: boolean;
+}>;
+
+type CarouselActiveVideoCompletedEvent = Readonly<{
+  surfaceId: string;
+  contentItem: string;          // JSON-serialized ContentItem
+  indexInCarousel: Int32;
+  carouselItem: string;          // JSON-serialized VideoCarouselItem
+  wasLast: boolean;
+  willAutoAdvance: boolean;
+}>;
+
 type OverlayFullStateEvent = Readonly<{
   surfaceId: string;
   isActive: boolean;
@@ -171,8 +216,20 @@ type OverlayFullStateEvent = Readonly<{
   isMuted: boolean;
   playbackRate: Double;
   captionsEnabled: boolean;
-  activeCue: string;
-  feedScrollPhase: string;
+  activeCue: string | null;
+  feedScrollPhase: string | null;
+}>;
+
+type OverlayItemChangedEvent = Readonly<{
+  surfaceId: string;
+  item: string; // JSON-serialized ContentItem
+  isActive: boolean;
+  playerState: string;
+  isMuted: boolean;
+  playbackRate: Double;
+  captionsEnabled: boolean;
+  activeCue: string | null;
+  feedScrollPhase: string | null;
 }>;
 
 export interface Spec extends TurboModule {
@@ -198,6 +255,9 @@ export interface Spec extends TurboModule {
   seekAndPlay(seconds: Double): void;
   skipToNext(): void;
   skipToPrevious(): void;
+  carouselNext(): boolean;
+  carouselPrevious(): boolean;
+  carouselSetActiveIndex(index: Int32): boolean;
   setMuted(muted: boolean): void;
   setPlaybackRate(rate: Double): void;
   setCaptionsEnabled(enabled: boolean): void;
@@ -216,6 +276,14 @@ export interface Spec extends TurboModule {
   prefetchStoryboard(playbackId: string): void;
   getStoryboardData(playbackId: string): Promise<string>;
 
+  // --- Download ---
+  downloadVideo(itemId: string, mode: string): Promise<string>;
+  cancelDownload(): void;
+
+  // --- Carousel accessors ---
+  getCarouselActiveIndex(): Int32;
+  getCarouselVideoCount(): Int32;
+
   // --- Event emitters ---
   readonly onPlayerStateChanged: EventEmitter<PlayerStateEvent>;
   readonly onCurrentItemChanged: EventEmitter<CurrentItemEvent>;
@@ -247,8 +315,18 @@ export interface Spec extends TurboModule {
   readonly onOverlayFeedScrollPhaseChanged: EventEmitter<OverlayFeedScrollPhaseEvent>;
   readonly onOverlayTimeUpdate: EventEmitter<OverlayTimeUpdateEvent>;
   readonly onOverlayFullState: EventEmitter<OverlayFullStateEvent>;
+  readonly onOverlayItemChanged: EventEmitter<OverlayItemChangedEvent>;
   readonly onCarouselActiveImageChanged: EventEmitter<CarouselActiveImageEvent>;
+  readonly onCarouselItemChanged: EventEmitter<CarouselItemChangedEvent>;
   readonly onVideoCarouselActiveVideoChanged: EventEmitter<VideoCarouselActiveVideoEvent>;
+  readonly onVideoCarouselItemChanged: EventEmitter<VideoCarouselItemChangedEvent>;
+  readonly onCarouselActiveVideoCompleted: EventEmitter<CarouselActiveVideoCompletedEvent>;
+
+  // --- Download events ---
+  readonly onDownloadStarted: EventEmitter<DownloadStartedEvent>;
+  readonly onDownloadProgress: EventEmitter<DownloadProgressEvent>;
+  readonly onDownloadCompleted: EventEmitter<DownloadCompletedEvent>;
+  readonly onDownloadFailed: EventEmitter<DownloadFailedEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('ShortKitModule');

package/src/specs/ShortKitFeedViewNativeComponent.ts

@@ -6,6 +6,14 @@ export interface NativeProps extends ViewProps {
   feedId?: string;
   startAtItemId?: string;
   preloadId?: string;
+  /**
+   * URL of a thumbnail already rendered/cached on the host side (e.g. the
+   * grid tile the user tapped to open this feed). When expo-image or FastImage
+   * is used on iOS, SDK fetches the decoded UIImage from SDWebImage's memory
+   * cache and paints it onto the first cell with zero network and zero
+   * latency. Falls back to network fetch for non-SDWebImage clients.
+   */
+  seedThumbnailUrl?: string;
 }
 
 export default codegenNativeComponent<NativeProps>(

package/src/types.ts

@@ -68,6 +68,21 @@ export interface ContentItem {
   articleUrl?: string;
   commentCount?: number;
   fallbackUrl?: string;
+  downloadUrl?: string;
+}
+
+export type DownloadStatus = 'idle' | 'downloading' | 'completed' | 'failed';
+
+export interface DownloadState {
+  status: DownloadStatus;
+  /** ID of the content item being downloaded, if any. */
+  itemId?: string;
+  /** 0.0 to 1.0 progress fraction. */
+  progress: number;
+  /** Local file URL after successful download. */
+  fileUrl?: string;
+  /** Error message if download failed. */
+  error?: string;
 }
 
 // --- Custom Feed Types ---
@@ -98,10 +113,41 @@ export interface VideoCarouselItem {
   articleUrl?: string;
 }
 
+export type ContentOrigin = 'ios_upload' | 'other';
+
+/**
+ * Per-slide input for a VideoCarouselInput. Mirrors the `{ type: 'video' }`
+ * FeedInput variant — host apps pass a playback ID and the SDK constructs
+ * the streaming and thumbnail URLs internally.
+ */
+export interface VideoCarouselVideoInput {
+  playbackId: string;
+  origin?: ContentOrigin;
+  fallbackUrl?: string;
+}
+
+/**
+ * Compact input type for video carousels passed to
+ * `{ type: 'videoCarousel', item: VideoCarouselInput }`.
+ *
+ * The SDK hydrates each playback ID into a full ContentItem internally
+ * before rendering. Overlays continue to receive the fully-hydrated
+ * VideoCarouselItem shape via VideoCarouselOverlayProps.carouselItem.
+ */
+export interface VideoCarouselInput {
+  id: string;
+  videos: VideoCarouselVideoInput[];
+  title?: string;
+  description?: string;
+  author?: string;
+  section?: string;
+  articleUrl?: string;
+}
+
 export type FeedInput =
-  | { type: 'video'; playbackId: string; fallbackUrl?: string }
+  | { type: 'video'; playbackId: string; origin?: ContentOrigin; fallbackUrl?: string }
   | { type: 'imageCarousel'; item: ImageCarouselItem }
-  | { type: 'videoCarousel'; item: VideoCarouselItem };
+  | { type: 'videoCarousel'; item: VideoCarouselInput };
 
 export type JSONValue =
   | string
@@ -257,6 +303,17 @@ export interface ShortKitFeedProps {
   style?: ViewStyle;
   /** Item ID to scroll to on initial load. */
   startAtItemId?: string;
+  /**
+   * URL of the thumbnail already displayed in your UI (e.g. the grid tile
+   * the user just tapped). If your app uses expo-image or FastImage, the SDK
+   * will extract the already-decoded UIImage from SDWebImage's memory cache
+   * and paint it on the first feed cell with zero network overhead — closing
+   * the black-frame gap before video playback begins.
+   *
+   * Falls back silently (no extra network beyond the existing fallback) for
+   * apps on React Native's core <Image> or other image libraries.
+   */
+  seedThumbnailUrl?: string;
   onLoop?: (event: LoopEvent) => void;
   onFeedTransition?: (event: FeedTransitionEvent) => void;
   onFormatChange?: (event: FormatChangeEvent) => void;
@@ -273,6 +330,15 @@ export interface ShortKitFeedProps {
   /** 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;
+  /** Called when the active video in a video carousel completes playback. */
+  onCarouselActiveVideoCompleted?: (event: {
+    surfaceId: string;
+    contentItem: ContentItem;
+    indexInCarousel: number;
+    carouselItem: VideoCarouselItem;
+    wasLast: boolean;
+    willAutoAdvance: boolean;
+  }) => void;
 }
 
 /**
@@ -339,6 +405,9 @@ export interface ShortKitWidgetProps {
 
 // --- Hook Return Types ---
 
+export type { ShortKitCarouselState } from './useShortKitCarousel';
+
+
 export interface ShortKitPlayerState {
   playerState: PlayerState;
   currentItem: ContentItem | null;

package/src/useShortKitCarousel.ts

@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useState } from 'react';
+import NativeShortKitModule from './specs/NativeShortKitModule';
+import { ShortKitCommands } from './ShortKitCommands';
+import type { VideoCarouselItem } from './types';
+
+export interface ShortKitCarouselState {
+  /** Index of the currently active video in the carousel, or null if no carousel is active. */
+  activeIndex: number | null;
+  /** Number of videos in the active carousel item, or 0 if none. */
+  videoCount: number;
+  /** The active carousel item, or null if no carousel is active. */
+  activeCarouselItem: VideoCarouselItem | null;
+  /** Advance to the next video in the carousel. Returns true if the command was dispatched. */
+  next: () => boolean;
+  /** Go back to the previous video in the carousel. Returns true if the command was dispatched. */
+  previous: () => boolean;
+  /** Jump to a specific index in the carousel. Returns true if the command was dispatched. */
+  setActiveIndex: (index: number) => boolean;
+}
+
+/**
+ * Hook to access video carousel state and commands.
+ *
+ * Subscribes to `onVideoCarouselItemChanged` and
+ * `onVideoCarouselActiveVideoChanged` from the native TurboModule and surfaces
+ * carousel state as reactive values. The imperative commands (`next`,
+ * `previous`, `setActiveIndex`) delegate to `ShortKitCommands`.
+ *
+ * Does not require a `<ShortKitProvider>` — it subscribes directly to native
+ * events and is suitable for use inside overlay components.
+ */
+export function useShortKitCarousel(): ShortKitCarouselState {
+  const [activeIndex, setActiveIndexState] = useState<number | null>(() => {
+    const v = NativeShortKitModule?.getCarouselActiveIndex?.() ?? -1;
+    return v < 0 ? null : v;
+  });
+  const [activeCarouselItem, setActiveCarouselItem] = useState<VideoCarouselItem | null>(null);
+
+  useEffect(() => {
+    if (!NativeShortKitModule) return;
+    const subItem = NativeShortKitModule.onVideoCarouselItemChanged((e: any) => {
+      try {
+        const item = e.carouselItem
+          ? (JSON.parse(e.carouselItem) as VideoCarouselItem)
+          : null;
+        setActiveCarouselItem(item);
+        setActiveIndexState(
+          typeof e.activeVideoIndex === 'number' ? e.activeVideoIndex : null,
+        );
+      } catch {
+        // ignore parse errors
+      }
+    });
+    const subIdx = NativeShortKitModule.onVideoCarouselActiveVideoChanged((e: any) => {
+      setActiveIndexState(
+        typeof e.activeVideoIndex === 'number' ? e.activeVideoIndex : null,
+      );
+    });
+    return () => {
+      subItem?.remove?.();
+      subIdx?.remove?.();
+    };
+  }, []);
+
+  const next = useCallback(() => ShortKitCommands.carouselNext(), []);
+  const previous = useCallback(() => ShortKitCommands.carouselPrevious(), []);
+  const setActiveIndex = useCallback(
+    (i: number) => ShortKitCommands.carouselSetActiveIndex(i),
+    [],
+  );
+
+  return {
+    activeIndex,
+    videoCount: activeCarouselItem?.videos?.length ?? 0,
+    activeCarouselItem,
+    next,
+    previous,
+    setActiveIndex,
+  };
+}