@shortkitsdk/react-native 0.1.0

package/src/ShortKitProvider.tsx

@@ -0,0 +1,526 @@
+import React, { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { AppState } from 'react-native';
+import type { AppStateStatus } from 'react-native';
+import { ShortKitContext } from './ShortKitContext';
+import type { ShortKitContextValue } from './ShortKitContext';
+import type {
+  ShortKitProviderProps,
+  ContentItem,
+  PlayerTime,
+  PlayerState,
+  CaptionTrack,
+  ContentSignal,
+} from './types';
+import {
+  serializeFeedConfigForModule,
+  deserializePlayerState,
+  deserializeContentItem,
+  deserializePlayerTime,
+} from './serialization';
+import NativeShortKitModule from './specs/NativeShortKitModule';
+
+// ---------------------------------------------------------------------------
+// State & Reducer
+// ---------------------------------------------------------------------------
+
+interface State {
+  playerState: PlayerState;
+  currentItem: ContentItem | null;
+  nextItem: ContentItem | null;
+  time: PlayerTime;
+  isMuted: boolean;
+  playbackRate: number;
+  captionsEnabled: boolean;
+  activeCaptionTrack: CaptionTrack | null;
+  activeCue: { text: string; startTime: number; endTime: number } | null;
+  prefetchedAheadCount: number;
+  isActive: boolean;
+  isTransitioning: boolean;
+  lastOverlayTap: number;
+  lastOverlayDoubleTap: { x: number; y: number; id: number } | null;
+}
+
+const initialState: State = {
+  playerState: 'idle',
+  currentItem: null,
+  nextItem: null,
+  time: { current: 0, duration: 0, buffered: 0 },
+  isMuted: true,
+  playbackRate: 1.0,
+  captionsEnabled: false,
+  activeCaptionTrack: null,
+  activeCue: null,
+  prefetchedAheadCount: 0,
+  isActive: false,
+  isTransitioning: false,
+  lastOverlayTap: 0,
+  lastOverlayDoubleTap: null,
+};
+
+type Action =
+  | { type: 'PLAYER_STATE'; payload: PlayerState }
+  | { type: 'CURRENT_ITEM'; payload: ContentItem | null }
+  | { type: 'TIME'; payload: PlayerTime }
+  | { type: 'MUTED'; payload: boolean }
+  | { type: 'PLAYBACK_RATE'; payload: number }
+  | { type: 'CAPTIONS_ENABLED'; payload: boolean }
+  | { type: 'CAPTION_TRACK'; payload: CaptionTrack | null }
+  | { type: 'CUE'; payload: { text: string; startTime: number; endTime: number } | null }
+  | { type: 'PREFETCH_COUNT'; payload: number }
+  | { type: 'OVERLAY_CONFIGURE'; payload: ContentItem }
+  | { type: 'OVERLAY_ACTIVATE' }
+  | { type: 'OVERLAY_RESET' }
+  | { type: 'OVERLAY_FADE_OUT' }
+  | { type: 'OVERLAY_RESTORE' }
+  | { type: 'OVERLAY_TAP' }
+  | { type: 'OVERLAY_DOUBLE_TAP'; payload: { x: number; y: number } };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'PLAYER_STATE': {
+      // Only allow isActive to transition TO true from player state.
+      // Once active, the overlay stays mounted — hiding during transient
+      // states like "loading" between videos would cause a visible flash.
+      const isPlaybackActive =
+        action.payload === 'playing' ||
+        action.payload === 'paused' ||
+        action.payload === 'buffering' ||
+        action.payload === 'seeking';
+      return {
+        ...state,
+        playerState: action.payload,
+        isActive: state.isActive || isPlaybackActive,
+      };
+    }
+    case 'CURRENT_ITEM':
+      return { ...state, currentItem: action.payload };
+    case 'TIME':
+      return { ...state, time: action.payload };
+    case 'MUTED':
+      return { ...state, isMuted: action.payload };
+    case 'PLAYBACK_RATE':
+      return { ...state, playbackRate: action.payload };
+    case 'CAPTIONS_ENABLED':
+      return { ...state, captionsEnabled: action.payload };
+    case 'CAPTION_TRACK':
+      return { ...state, activeCaptionTrack: action.payload };
+    case 'CUE':
+      return { ...state, activeCue: action.payload };
+    case 'PREFETCH_COUNT':
+      return { ...state, prefetchedAheadCount: action.payload };
+    case 'OVERLAY_CONFIGURE':
+      return { ...state, nextItem: action.payload };
+    case 'OVERLAY_ACTIVATE':
+      return { ...state, currentItem: state.nextItem, isActive: true };
+    case 'OVERLAY_RESET':
+      // Don't set isActive = false — the overlay stays mounted during
+      // transitions. In the native SDK each cell has its own overlay
+      // instance, so there's no gap. We replicate this by keeping the
+      // single JS overlay mounted and updating its content on activate.
+      return { ...state, isTransitioning: false };
+    case 'OVERLAY_FADE_OUT':
+      return { ...state, isTransitioning: true };
+    case 'OVERLAY_RESTORE':
+      return { ...state, isTransitioning: false };
+    case 'OVERLAY_TAP':
+      return { ...state, lastOverlayTap: state.lastOverlayTap + 1 };
+    case 'OVERLAY_DOUBLE_TAP':
+      return {
+        ...state,
+        lastOverlayDoubleTap: {
+          x: action.payload.x,
+          y: action.payload.y,
+          id: (state.lastOverlayDoubleTap?.id ?? 0) + 1,
+        },
+      };
+    default:
+      return state;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Provider Component
+// ---------------------------------------------------------------------------
+
+export function ShortKitProvider({
+  apiKey,
+  config,
+  userId,
+  clientAppName,
+  clientAppVersion,
+  customDimensions,
+  children,
+}: ShortKitProviderProps): React.JSX.Element {
+  const [state, dispatch] = useReducer(reducer, initialState);
+  const appStateRef = useRef<AppStateStatus>(AppState.currentState);
+
+  // -----------------------------------------------------------------------
+  // Initialize / Release
+  // -----------------------------------------------------------------------
+  useEffect(() => {
+    if (!NativeShortKitModule) return;
+
+    const serializedConfig = serializeFeedConfigForModule(config);
+    const serializedDimensions = customDimensions
+      ? JSON.stringify(customDimensions)
+      : undefined;
+
+    NativeShortKitModule.initialize(
+      apiKey,
+      serializedConfig,
+      clientAppName,
+      clientAppVersion,
+      serializedDimensions,
+    );
+
+    return () => {
+      NativeShortKitModule.destroy();
+    };
+    // Intentionally only run on mount/unmount. Config changes require a
+    // remount (via a `key` prop on the provider) to take effect.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // -----------------------------------------------------------------------
+  // User ID sync
+  // -----------------------------------------------------------------------
+  useEffect(() => {
+    if (!NativeShortKitModule) return;
+    if (userId) {
+      NativeShortKitModule.setUserId(userId);
+    } else {
+      NativeShortKitModule.clearUserId();
+    }
+  }, [userId]);
+
+  // -----------------------------------------------------------------------
+  // AppState handling (background / foreground)
+  // -----------------------------------------------------------------------
+  useEffect(() => {
+    if (!NativeShortKitModule) return;
+
+    const subscription = AppState.addEventListener(
+      'change',
+      (nextState: AppStateStatus) => {
+        if (
+          appStateRef.current.match(/active/) &&
+          nextState === 'background'
+        ) {
+          NativeShortKitModule.onPause();
+        } else if (
+          appStateRef.current.match(/background/) &&
+          nextState === 'active'
+        ) {
+          NativeShortKitModule.onResume();
+        }
+        appStateRef.current = nextState;
+      },
+    );
+
+    return () => {
+      subscription.remove();
+    };
+  }, []);
+
+  // -----------------------------------------------------------------------
+  // Event subscriptions
+  // -----------------------------------------------------------------------
+  useEffect(() => {
+    if (!NativeShortKitModule) return;
+
+    const subscriptions: Array<{ remove: () => void }> = [];
+
+    // Player state
+    subscriptions.push(
+      NativeShortKitModule.onPlayerStateChanged((event) => {
+        dispatch({
+          type: 'PLAYER_STATE',
+          payload: deserializePlayerState(event),
+        });
+      }),
+    );
+
+    // Current item
+    subscriptions.push(
+      NativeShortKitModule.onCurrentItemChanged((event) => {
+        const item: ContentItem = {
+          id: event.id,
+          title: event.title,
+          description: event.description,
+          duration: event.duration,
+          streamingUrl: event.streamingUrl,
+          thumbnailUrl: event.thumbnailUrl,
+          captionTracks: event.captionTracks
+            ? JSON.parse(event.captionTracks)
+            : [],
+          customMetadata: event.customMetadata
+            ? JSON.parse(event.customMetadata)
+            : undefined,
+          author: event.author,
+          articleUrl: event.articleUrl,
+          commentCount: event.commentCount,
+        };
+        dispatch({ type: 'CURRENT_ITEM', payload: item });
+      }),
+    );
+
+    // Time updates
+    subscriptions.push(
+      NativeShortKitModule.onTimeUpdate((event) => {
+        dispatch({ type: 'TIME', payload: deserializePlayerTime(event) });
+      }),
+    );
+
+    // Muted
+    subscriptions.push(
+      NativeShortKitModule.onMutedChanged((event) => {
+        dispatch({ type: 'MUTED', payload: event.isMuted });
+      }),
+    );
+
+    // Playback rate
+    subscriptions.push(
+      NativeShortKitModule.onPlaybackRateChanged((event) => {
+        dispatch({ type: 'PLAYBACK_RATE', payload: event.rate });
+      }),
+    );
+
+    // Captions enabled
+    subscriptions.push(
+      NativeShortKitModule.onCaptionsEnabledChanged((event) => {
+        dispatch({ type: 'CAPTIONS_ENABLED', payload: event.enabled });
+      }),
+    );
+
+    // Active caption track
+    subscriptions.push(
+      NativeShortKitModule.onActiveCaptionTrackChanged((event) => {
+        dispatch({
+          type: 'CAPTION_TRACK',
+          payload: {
+            language: event.language,
+            label: event.label,
+            sourceUrl: event.sourceUrl,
+          },
+        });
+      }),
+    );
+
+    // Active cue
+    subscriptions.push(
+      NativeShortKitModule.onActiveCueChanged((event) => {
+        dispatch({
+          type: 'CUE',
+          payload: {
+            text: event.text,
+            startTime: event.startTime,
+            endTime: event.endTime,
+          },
+        });
+      }),
+    );
+
+    // Prefetch count
+    subscriptions.push(
+      NativeShortKitModule.onPrefetchedAheadCountChanged((event) => {
+        dispatch({ type: 'PREFETCH_COUNT', payload: event.count });
+      }),
+    );
+
+    // Overlay lifecycle events
+    subscriptions.push(
+      NativeShortKitModule.onOverlayConfigure((event) => {
+        const item = deserializeContentItem(event.item);
+        if (item) {
+          dispatch({ type: 'OVERLAY_CONFIGURE', payload: item });
+        }
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onOverlayActivate((_event) => {
+        dispatch({ type: 'OVERLAY_ACTIVATE' });
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onOverlayReset((_event) => {
+        dispatch({ type: 'OVERLAY_RESET' });
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onOverlayFadeOut((_event) => {
+        dispatch({ type: 'OVERLAY_FADE_OUT' });
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onOverlayRestore((_event) => {
+        dispatch({ type: 'OVERLAY_RESTORE' });
+      }),
+    );
+
+    // Overlay tap events
+    subscriptions.push(
+      NativeShortKitModule.onOverlayTap((_event) => {
+        dispatch({ type: 'OVERLAY_TAP' });
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onOverlayDoubleTap((event) => {
+        dispatch({
+          type: 'OVERLAY_DOUBLE_TAP',
+          payload: { x: event.x, y: event.y },
+        });
+      }),
+    );
+
+    // Note: Feed-level callback events (onDidLoop, onFeedTransition,
+    // onShareTapped, etc.) are subscribed by the ShortKitFeed component
+    // (Task 11), not here. The provider only manages state-driving events.
+
+    return () => {
+      for (const sub of subscriptions) {
+        sub.remove();
+      }
+    };
+  }, []);
+
+  // -----------------------------------------------------------------------
+  // Commands (stable refs)
+  // -----------------------------------------------------------------------
+  const play = useCallback(() => {
+    NativeShortKitModule?.play();
+  }, []);
+
+  const pause = useCallback(() => {
+    NativeShortKitModule?.pause();
+  }, []);
+
+  const seek = useCallback((seconds: number) => {
+    NativeShortKitModule?.seek(seconds);
+  }, []);
+
+  const seekAndPlay = useCallback((seconds: number) => {
+    NativeShortKitModule?.seekAndPlay(seconds);
+  }, []);
+
+  const skipToNext = useCallback(() => {
+    NativeShortKitModule?.skipToNext();
+  }, []);
+
+  const skipToPrevious = useCallback(() => {
+    NativeShortKitModule?.skipToPrevious();
+  }, []);
+
+  const setMuted = useCallback((muted: boolean) => {
+    NativeShortKitModule?.setMuted(muted);
+  }, []);
+
+  const setPlaybackRate = useCallback((rate: number) => {
+    NativeShortKitModule?.setPlaybackRate(rate);
+  }, []);
+
+  const setCaptionsEnabled = useCallback((enabled: boolean) => {
+    NativeShortKitModule?.setCaptionsEnabled(enabled);
+  }, []);
+
+  const selectCaptionTrack = useCallback((language: string) => {
+    NativeShortKitModule?.selectCaptionTrack(language);
+  }, []);
+
+  const sendContentSignal = useCallback((signal: ContentSignal) => {
+    NativeShortKitModule?.sendContentSignal(signal);
+  }, []);
+
+  const setMaxBitrate = useCallback((bitrate: number) => {
+    NativeShortKitModule?.setMaxBitrate(bitrate);
+  }, []);
+
+  const setUserIdCmd = useCallback((id: string) => {
+    NativeShortKitModule?.setUserId(id);
+  }, []);
+
+  const clearUserIdCmd = useCallback(() => {
+    NativeShortKitModule?.clearUserId();
+  }, []);
+
+  // -----------------------------------------------------------------------
+  // Context value (memoized to avoid unnecessary re-renders)
+  // -----------------------------------------------------------------------
+  const value: ShortKitContextValue = useMemo(
+    () => ({
+      // State
+      playerState: state.playerState,
+      currentItem: state.currentItem,
+      nextItem: state.nextItem,
+      time: state.time,
+      isMuted: state.isMuted,
+      playbackRate: state.playbackRate,
+      captionsEnabled: state.captionsEnabled,
+      activeCaptionTrack: state.activeCaptionTrack,
+      activeCue: state.activeCue,
+      prefetchedAheadCount: state.prefetchedAheadCount,
+      isActive: state.isActive,
+      isTransitioning: state.isTransitioning,
+      lastOverlayTap: state.lastOverlayTap,
+      lastOverlayDoubleTap: state.lastOverlayDoubleTap,
+
+      // Commands
+      play,
+      pause,
+      seek,
+      seekAndPlay,
+      skipToNext,
+      skipToPrevious,
+      setMuted,
+      setPlaybackRate,
+      setCaptionsEnabled,
+      selectCaptionTrack,
+      sendContentSignal,
+      setMaxBitrate,
+      setUserId: setUserIdCmd,
+      clearUserId: clearUserIdCmd,
+
+      // Internal — consumed by ShortKitFeed to pass to OverlayManager
+      _overlayConfig: config.overlay ?? 'none',
+    }),
+    [
+      state.playerState,
+      state.currentItem,
+      state.nextItem,
+      state.time,
+      state.isMuted,
+      state.playbackRate,
+      state.captionsEnabled,
+      state.activeCaptionTrack,
+      state.activeCue,
+      state.prefetchedAheadCount,
+      state.isActive,
+      state.isTransitioning,
+      state.lastOverlayTap,
+      state.lastOverlayDoubleTap,
+      play,
+      pause,
+      seek,
+      seekAndPlay,
+      skipToNext,
+      skipToPrevious,
+      setMuted,
+      setPlaybackRate,
+      setCaptionsEnabled,
+      selectCaptionTrack,
+      sendContentSignal,
+      setMaxBitrate,
+      setUserIdCmd,
+      clearUserIdCmd,
+      config.overlay,
+    ],
+  );
+
+  return (
+    <ShortKitContext.Provider value={value}>{children}</ShortKitContext.Provider>
+  );
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export { ShortKitProvider } from './ShortKitProvider';
+export { ShortKitFeed } from './ShortKitFeed';
+export { useShortKitPlayer } from './useShortKitPlayer';
+export { useShortKit } from './useShortKit';
+export type {
+  FeedConfig,
+  FeedHeight,
+  OverlayConfig,
+  CarouselMode,
+  SurveyMode,
+
+  ContentItem,
+  JSONValue,
+  CaptionTrack,
+  PlayerTime,
+  PlayerState,
+  LoopEvent,
+  FeedTransitionEvent,
+  FormatChangeEvent,
+  ContentSignal,
+  SurveyOption,
+  ShortKitError,
+  ShortKitProviderProps,
+  ShortKitFeedProps,
+  ShortKitPlayerState,
+} from './types';

package/src/serialization.ts

@@ -0,0 +1,95 @@
+import type {
+  FeedConfig,
+  ContentItem,
+  PlayerState,
+  PlayerTime,
+} from './types';
+
+/**
+ * Serialized FeedConfig with JSON strings for complex fields.
+ * Used by ShortKitFeedView native component props.
+ */
+export interface SerializedFeedConfig {
+  feedHeight: string;
+  overlay: string;
+  carouselMode: string;
+  surveyMode: string;
+  muteOnStart: boolean;
+}
+
+/**
+ * Serialize FeedConfig for the bridge.
+ * Complex union types are JSON-stringified; the `component` field on custom
+ * overlays is stripped because React component references cannot cross the bridge.
+ */
+export function serializeFeedConfig(config: FeedConfig): SerializedFeedConfig {
+  let overlay: string;
+  const rawOverlay = config.overlay ?? 'none';
+  if (typeof rawOverlay === 'string') {
+    overlay = JSON.stringify(rawOverlay);
+  } else {
+    // Strip the component ref — it stays on the JS side for OverlayManager
+    overlay = JSON.stringify({ type: 'custom' });
+  }
+
+  return {
+    feedHeight: JSON.stringify(config.feedHeight ?? { type: 'fullscreen' }),
+    overlay,
+    carouselMode: JSON.stringify(config.carouselMode ?? 'none'),
+    surveyMode: JSON.stringify(config.surveyMode ?? 'none'),
+    muteOnStart: config.muteOnStart ?? true,
+  };
+}
+
+/**
+ * Serialize a FeedConfig into a single JSON string for the TurboModule
+ * `initialize(config:)` parameter.
+ */
+export function serializeFeedConfigForModule(config: FeedConfig): string {
+  const serialized = serializeFeedConfig(config);
+  return JSON.stringify(serialized);
+}
+
+/**
+ * Deserialize PlayerState from a bridge event.
+ * The native side sends `{ state: string; errorMessage?: string }`.
+ */
+export function deserializePlayerState(event: {
+  state: string;
+  errorMessage?: string;
+}): PlayerState {
+  if (event.state === 'error' && event.errorMessage) {
+    return { error: event.errorMessage };
+  }
+  return event.state as Exclude<PlayerState, { error: string }>;
+}
+
+/**
+ * Deserialize a ContentItem from a bridge JSON string.
+ * Returns null for null/undefined input or malformed JSON.
+ */
+export function deserializeContentItem(
+  json: string | null | undefined,
+): ContentItem | null {
+  if (!json) return null;
+  try {
+    return JSON.parse(json) as ContentItem;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deserialize PlayerTime from a bridge event.
+ */
+export function deserializePlayerTime(event: {
+  current: number;
+  duration: number;
+  buffered: number;
+}): PlayerTime {
+  return {
+    current: event.current,
+    duration: event.duration,
+    buffered: event.buffered,
+  };
+}