@moviie/player-expo 0.4.0

package/src/hooks/use-moviie-playback-ended.ts

@@ -0,0 +1,14 @@
+import type { VideoPlayer } from "expo-video"
+import { PLAYER_API_EVENTS } from "@moviie/player-types"
+
+import { useMoviieEvent } from "./use-moviie-event"
+
+/**
+ * Natural playback end from expo-video (`playToEnd`), aligned with {@link PLAYER_API_EVENTS.ENDED}.
+ */
+export function useMoviiePlaybackEnded(
+  player: VideoPlayer | null,
+  onEnded: () => void
+): void {
+  useMoviieEvent(player, PLAYER_API_EVENTS.ENDED, onEnded)
+}

package/src/hooks/use-moviie-playback-resume-persistence.ts

@@ -0,0 +1,76 @@
+import { useEffect, useRef } from "react"
+
+import type { VideoPlayer } from "expo-video"
+
+import { MOVIIE_REMEMBER_POSITION_DEBOUNCE_MS } from "../constants"
+import {
+  clampResumeTimeSeconds,
+  clearStoredResumeSeconds,
+  writeStoredResumeSeconds,
+} from "../lib/remember-playback-position-storage"
+
+export function useMoviiePlaybackResumePersistence(options: {
+  player: VideoPlayer
+  embedId: string | undefined
+  durationSeconds: number | null | undefined
+  enabled: boolean
+}): void {
+  const { player, embedId, durationSeconds, enabled } = options
+
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (!enabled || embedId == null || embedId === "") {
+      return
+    }
+
+    const clearDebounce = () => {
+      if (debounceTimerRef.current != null) {
+        clearTimeout(debounceTimerRef.current)
+        debounceTimerRef.current = null
+      }
+    }
+
+    const persistNow = (seconds: number) => {
+      const clamped = clampResumeTimeSeconds(seconds, durationSeconds)
+      if (clamped == null) {
+        void clearStoredResumeSeconds(embedId)
+        return
+      }
+      void writeStoredResumeSeconds(embedId, clamped)
+    }
+
+    const schedulePersist = (seconds: number) => {
+      clearDebounce()
+      debounceTimerRef.current = setTimeout(() => {
+        debounceTimerRef.current = null
+        persistNow(seconds)
+      }, MOVIIE_REMEMBER_POSITION_DEBOUNCE_MS)
+    }
+
+    const subTime = player.addListener("timeUpdate", ({ currentTime }) => {
+      if (player.playing) {
+        schedulePersist(currentTime)
+      }
+    })
+
+    const subPlaying = player.addListener("playingChange", ({ isPlaying }) => {
+      if (!isPlaying) {
+        clearDebounce()
+        persistNow(player.currentTime)
+      }
+    })
+
+    const subEnd = player.addListener("playToEnd", () => {
+      clearDebounce()
+      void clearStoredResumeSeconds(embedId)
+    })
+
+    return () => {
+      clearDebounce()
+      subTime.remove()
+      subPlaying.remove()
+      subEnd.remove()
+    }
+  }, [durationSeconds, embedId, enabled, player])
+}

package/src/hooks/use-moviie-playback.ts

@@ -0,0 +1,99 @@
+import { useCallback, useEffect, useState } from "react"
+
+import type { MoviiePlaybackData } from "@moviie/player-sdk"
+
+import { fetchPlaybackFreshWriteCache } from "../playback/fetch-playback-fresh"
+import { readPlaybackCache } from "../playback/playback-memory-cache"
+import { useMoviieContext } from "../provider/moviie-provider"
+
+export interface UseMoviiePlaybackArgs {
+  /** Public embed UUID — client SDK never calls admin APIs or private keys. */
+  embedId?: string
+}
+
+export interface UseMoviiePlaybackResult {
+  data: MoviiePlaybackData | null
+  error: Error | null
+  isLoading: boolean
+  retry: () => void
+}
+
+export function useMoviiePlayback(
+  args: UseMoviiePlaybackArgs
+): UseMoviiePlaybackResult {
+  const trimmedEmbedId = args.embedId?.trim()
+  const missingEmbedId = !trimmedEmbedId
+  const { client, publishableKey } = useMoviieContext()
+
+  const [data, setData] = useState<MoviiePlaybackData | null>(null)
+  const [fetchError, setFetchError] = useState<Error | null>(null)
+  const [isLoading, setIsLoading] = useState(!missingEmbedId)
+  const [retryNonce, setRetryNonce] = useState(0)
+
+  const retry = useCallback(() => {
+    setRetryNonce((n) => n + 1)
+  }, [])
+
+  useEffect(() => {
+    if (!trimmedEmbedId) {
+      return
+    }
+
+    const embedKey = trimmedEmbedId
+
+    const controller = new AbortController()
+    let cancelled = false
+
+    async function load(): Promise<void> {
+      setIsLoading(true)
+      setFetchError(null)
+
+      try {
+        const cached = readPlaybackCache(publishableKey, embedKey)
+        if (cached && !controller.signal.aborted) {
+          setData(cached)
+        }
+
+        const outcome = await fetchPlaybackFreshWriteCache(
+          publishableKey,
+          embedKey,
+          controller.signal,
+          (id, sig) => client.getPlayback(id, sig),
+        )
+
+        if (cancelled || controller.signal.aborted) {
+          return
+        }
+
+        if (outcome.ok) {
+          setData(outcome.data)
+        } else {
+          setFetchError(outcome.error)
+          setData(readPlaybackCache(publishableKey, embedKey))
+        }
+      } finally {
+        if (!cancelled && !controller.signal.aborted) {
+          setIsLoading(false)
+        }
+      }
+    }
+
+    void load()
+
+    return () => {
+      cancelled = true
+      controller.abort()
+    }
+  }, [trimmedEmbedId, client, publishableKey, retryNonce])
+
+  const error = missingEmbedId
+    ? new Error("Informe um embedId válido (UUID público do embed).")
+    : fetchError
+
+  return {
+    data: missingEmbedId ? null : data,
+    error,
+    isLoading: missingEmbedId ? false : isLoading,
+    retry,
+  }
+}

package/src/hooks/use-moviie-player-types.ts

@@ -0,0 +1,55 @@
+import type { VideoPlayer } from "expo-video"
+
+import type { MoviiePlaybackData } from "@moviie/player-sdk"
+
+import type { MoviieVideoPresentationProps } from "../lib/build-moviie-video-presentation"
+
+export interface UseMoviiePlayerOptions {
+  embedId?: string
+  /**
+   * When set, overrides {@link MoviiePlaybackData.controls.autoplay}. When omitted, embed wins.
+   */
+  autoplay?: boolean
+  /**
+   * When set, overrides PiP capability vs embed `showPip` (passed into presentation props).
+   * When omitted, embed wins.
+   */
+  pictureInPicture?: boolean
+  /**
+   * When set, overrides auto-start PiP. When omitted, defaults to `false` in presentation props.
+   */
+  pictureInPictureAutoStart?: boolean
+  /**
+   * Native-only: keep playback active when the app backgrounds (not part of embed controls).
+   * @default false
+   */
+  backgroundPlayback?: boolean
+  /**
+   * Native-only: show Now Playing / lock-screen controls (not part of embed controls).
+   * @default false
+   */
+  lockScreenNowPlaying?: boolean
+  /**
+   * When set, overrides {@link MoviiePlaybackData.controls.rememberPosition}.
+   * When omitted, embed wins.
+   */
+  rememberPosition?: boolean
+}
+
+export interface UseMoviiePlayerResult {
+  /**
+   * Native: `expo-video` player instance. Web (iframe): always `null` — use embed JS API / `onEmbedIframeRef`.
+   */
+  player: VideoPlayer | null
+  playback: MoviiePlaybackData | null
+  error: Error | null
+  isLoading: boolean
+  /**
+   * Presentation props for `MoviieVideo` / `VideoView`: embed defaults, plus explicit hook overrides.
+   */
+  videoPresentation: MoviieVideoPresentationProps
+  /**
+   * Re-runs the playback fetch. Used by the built-in error shell for transient errors (network/rate_limit).
+   */
+  retry: () => void
+}

package/src/hooks/use-moviie-player.ts

@@ -0,0 +1,236 @@
+import { useEffect, useMemo, useRef } from "react"
+
+import { useVideoPlayer } from "expo-video"
+import type { VideoPlayer } from "expo-video"
+import type { VideoSource } from "expo-video"
+
+import {
+  deriveTelemetryEventsBaseUrlFromBootstrapUrl,
+  type MoviiePlaybackData,
+} from "@moviie/player-sdk"
+
+import { useMoviiePlayback } from "./use-moviie-playback"
+import { useMoviieTelemetry } from "./use-moviie-telemetry"
+import { useMoviiePlaybackResumePersistence } from "./use-moviie-playback-resume-persistence"
+import { useMoviieContext } from "../provider/moviie-provider"
+import {
+  buildMoviieVideoPresentationProps,
+  type MoviieVideoPresentationProps,
+} from "../lib/build-moviie-video-presentation"
+import {
+  clampResumeTimeSeconds,
+  readStoredResumeSeconds,
+} from "../lib/remember-playback-position-storage"
+
+import type {
+  UseMoviiePlayerOptions,
+  UseMoviiePlayerResult,
+} from "./use-moviie-player-types"
+
+export type {
+  UseMoviiePlayerOptions,
+  UseMoviiePlayerResult,
+} from "./use-moviie-player-types"
+
+const PLAYBACK_REQUEST_HEADER_ALLOWLIST = new Set([
+  "authorization",
+  "referer",
+  "user-agent",
+  "x-moviie-playback-token",
+  "x-moviie-signature",
+  "x-playback-token",
+])
+
+function filterPlaybackRequestHeaders(
+  raw: Record<string, string> | undefined
+): Record<string, string> | undefined {
+  if (!raw) return undefined
+  const safe: Record<string, string> = {}
+  for (const [name, value] of Object.entries(raw)) {
+    if (typeof name !== "string" || typeof value !== "string") continue
+    if (!PLAYBACK_REQUEST_HEADER_ALLOWLIST.has(name.toLowerCase())) continue
+    if (/[\r\n]/.test(value)) continue
+    safe[name] = value
+  }
+  return Object.keys(safe).length > 0 ? safe : undefined
+}
+
+function buildVideoSource(data: MoviiePlaybackData): VideoSource {
+  const headers = filterPlaybackRequestHeaders(data.playback.requestHeaders)
+  const base: VideoSource = {
+    uri: data.playback.uri,
+    metadata: {
+      title: data.title,
+      artist: data.branding.organizationName ?? undefined,
+      artwork: data.posterUrl ?? undefined,
+    },
+  }
+  if (headers) {
+    return { ...base, headers }
+  }
+  return base
+}
+
+function configurePlaybackDefaults(
+  player: VideoPlayer,
+  data: MoviiePlaybackData
+): void {
+  const c = data.controls
+  player.loop = c.loop
+  player.muted = c.muted
+  player.timeUpdateEventInterval = 1
+}
+
+function applyNativePlaybackPresentation(
+  player: VideoPlayer,
+  opts: Pick<UseMoviiePlayerOptions, "backgroundPlayback" | "lockScreenNowPlaying">
+): void {
+  player.staysActiveInBackground = opts.backgroundPlayback ?? false
+  player.showNowPlayingNotification = opts.lockScreenNowPlaying ?? false
+}
+
+function syncPlaybackIntent(player: VideoPlayer, shouldPlay: boolean): void {
+  if (shouldPlay) {
+    player.play()
+  } else {
+    player.pause()
+  }
+}
+
+const EMPTY_PRESENTATION = buildMoviieVideoPresentationProps({
+  profile: "",
+  showPip: false,
+})
+
+export function useMoviiePlayer(
+  options: UseMoviiePlayerOptions
+): UseMoviiePlayerResult {
+  const ctx = useMoviieContext()
+
+  const { data, error, isLoading, retry } = useMoviiePlayback({
+    embedId: options.embedId,
+  })
+
+  const rememberEnabled = useMemo(() => {
+    if (options.rememberPosition === false) {
+      return false
+    }
+    if (options.rememberPosition === true) {
+      return true
+    }
+    return data?.controls.rememberPosition === true
+  }, [data?.controls.rememberPosition, options.rememberPosition])
+
+  const player = useVideoPlayer(null, (initialPlayer) => {
+    initialPlayer.timeUpdateEventInterval = 1
+  })
+
+  useMoviiePlaybackResumePersistence({
+    durationSeconds: data?.durationSeconds,
+    embedId: data?.embedId,
+    enabled: rememberEnabled && data != null,
+    player,
+  })
+
+  const resumeHandledRef = useRef(false)
+
+  useEffect(() => {
+    resumeHandledRef.current = false
+  }, [data?.embedId, data?.playback.uri])
+
+  useEffect(() => {
+    if (!data) {
+      return
+    }
+
+    const src = buildVideoSource(data)
+    const shouldPlay =
+      options.autoplay !== undefined
+        ? options.autoplay
+        : data.controls.autoplay
+
+    player.replace(src)
+    configurePlaybackDefaults(player, data)
+    applyNativePlaybackPresentation(player, {
+      backgroundPlayback: options.backgroundPlayback,
+      lockScreenNowPlaying: options.lockScreenNowPlaying,
+    })
+
+    const restoreAndSync = async () => {
+      if (player.status !== "readyToPlay") {
+        return
+      }
+
+      if (!resumeHandledRef.current) {
+        resumeHandledRef.current = true
+        if (rememberEnabled) {
+          const stored = await readStoredResumeSeconds(data.embedId)
+          const clamped = clampResumeTimeSeconds(stored, data.durationSeconds)
+          if (clamped != null) {
+            player.currentTime = clamped
+          }
+        }
+      }
+
+      syncPlaybackIntent(player, shouldPlay)
+    }
+
+    const sub = player.addListener("statusChange", (payload) => {
+      if (payload.status === "readyToPlay") {
+        void restoreAndSync()
+      }
+    })
+
+    void restoreAndSync()
+
+    return () => {
+      sub.remove()
+    }
+  }, [
+    data,
+    player,
+    options.autoplay,
+    options.backgroundPlayback,
+    options.lockScreenNowPlaying,
+    rememberEnabled,
+  ])
+
+  const videoPresentation = useMemo((): MoviieVideoPresentationProps => {
+    if (!data) {
+      return EMPTY_PRESENTATION
+    }
+    return buildMoviieVideoPresentationProps({
+      pictureInPicture: options.pictureInPicture,
+      pictureInPictureAutoStart: options.pictureInPictureAutoStart,
+      profile: data.profile,
+      showPip: data.controls.showPip,
+    })
+  }, [
+    data,
+    options.pictureInPicture,
+    options.pictureInPictureAutoStart,
+  ])
+
+  const eventsBaseUrl =
+    data?.telemetry.bootstrapUrl != null
+      ? deriveTelemetryEventsBaseUrlFromBootstrapUrl(data.telemetry.bootstrapUrl) ??
+        ctx.client.getEventsBaseUrl()
+      : ctx.client.getEventsBaseUrl()
+
+  useMoviieTelemetry(
+    player,
+    data,
+    eventsBaseUrl,
+    ctx.telemetryHeaders,
+    ctx.viewerTokenStore
+  )
+
+  return {
+    player,
+    playback: data,
+    error,
+    isLoading,
+    videoPresentation,
+    retry,
+  }
+}

package/src/hooks/use-moviie-player.web.ts

@@ -0,0 +1,57 @@
+import { useMemo } from "react"
+
+import type { MoviiePlaybackData } from "@moviie/player-sdk"
+
+import {
+  buildMoviieVideoPresentationProps,
+  type MoviieVideoPresentationProps,
+} from "../lib/build-moviie-video-presentation"
+import { useMoviiePlayback } from "./use-moviie-playback"
+import type {
+  UseMoviiePlayerOptions,
+  UseMoviiePlayerResult,
+} from "./use-moviie-player-types"
+
+const EMPTY_PRESENTATION = buildMoviieVideoPresentationProps({
+  profile: "",
+  showPip: false,
+})
+
+/**
+ * Expo Web: não usa `expo-video`; obtém playback via SDK e deixa o vídeo ao iframe embed + `embed.js`.
+ * Opções só nativas (`backgroundPlayback`, `lockScreenNowPlaying`, telemetria ligada ao player nativo, resume SecureStore) são ignoradas aqui.
+ */
+export function useMoviiePlayer(
+  options: UseMoviiePlayerOptions
+): UseMoviiePlayerResult {
+  const { data, error, isLoading, retry } = useMoviiePlayback({
+    embedId: options.embedId,
+  })
+
+  const videoPresentation = useMemo((): MoviieVideoPresentationProps => {
+    if (!data) {
+      return EMPTY_PRESENTATION
+    }
+    return buildMoviieVideoPresentationProps({
+      pictureInPicture: options.pictureInPicture,
+      pictureInPictureAutoStart: options.pictureInPictureAutoStart,
+      profile: data.profile,
+      showPip: data.controls.showPip,
+    })
+  }, [
+    data,
+    options.pictureInPicture,
+    options.pictureInPictureAutoStart,
+  ])
+
+  const playback: MoviiePlaybackData | null = data
+
+  return {
+    player: null,
+    playback,
+    error,
+    isLoading,
+    videoPresentation,
+    retry,
+  }
+}

package/src/hooks/use-moviie-telemetry.ts

@@ -0,0 +1,133 @@
+import { useEffect, useRef } from "react"
+
+import { AppState, type AppStateStatus } from "react-native"
+import type { VideoPlayer } from "expo-video"
+import {
+  PLAYBACK_EVENT_TYPE,
+  TelemetryClient,
+  type MoviiePlaybackData,
+  type ViewerTokenStore,
+} from "@moviie/player-sdk"
+
+export function useMoviieTelemetry(
+  player: VideoPlayer,
+  playback: MoviiePlaybackData | null,
+  eventsBaseUrl: string,
+  defaultHeaders: Record<string, string>,
+  viewerTokenStore: ViewerTokenStore
+): void {
+  const hasStartedPlaybackRef = useRef(false)
+
+  useEffect(() => {
+    if (!playback?.telemetry.bootstrapUrl) {
+      return
+    }
+
+    const telemetry = new TelemetryClient({
+      eventsBaseUrl,
+      defaultHeaders,
+      viewerTokenStore,
+      getPositionSeconds: () => player.currentTime,
+    })
+
+    let disposed = false
+    const subs: Array<{ remove: () => void }> = []
+
+    void (async () => {
+      try {
+        await telemetry.bootstrap({
+          bootstrapUrl: playback.telemetry.bootstrapUrl,
+        })
+        if (disposed) {
+          return
+        }
+        await telemetry.recordEvent({
+          eventType: PLAYBACK_EVENT_TYPE.SESSION_START,
+          positionSeconds: 0,
+        })
+      } catch {
+        /* falha de telemetria não bloqueia playback */
+      }
+    })()
+
+    subs.push(
+      player.addListener("playingChange", ({ isPlaying }) => {
+        telemetry.updatePosition(Math.max(0, player.currentTime))
+        if (isPlaying) {
+          void telemetry.recordEvent({
+            eventType: hasStartedPlaybackRef.current
+              ? PLAYBACK_EVENT_TYPE.RESUME
+              : PLAYBACK_EVENT_TYPE.PLAY_START,
+            positionSeconds: Math.floor(Math.max(0, player.currentTime)),
+          })
+          hasStartedPlaybackRef.current = true
+          telemetry.startHeartbeats()
+        } else {
+          void telemetry.recordEvent({
+            eventType: PLAYBACK_EVENT_TYPE.PAUSE,
+            positionSeconds: Math.floor(Math.max(0, player.currentTime)),
+          })
+          telemetry.stopHeartbeats()
+        }
+      })
+    )
+
+    subs.push(
+      player.addListener("playToEnd", () => {
+        telemetry.updatePosition(Math.max(0, player.currentTime))
+        void telemetry.recordEvent({
+          eventType: PLAYBACK_EVENT_TYPE.ENDED,
+          positionSeconds: Math.floor(Math.max(0, player.duration)),
+        })
+        telemetry.stopHeartbeats()
+      })
+    )
+
+    subs.push(
+      player.addListener("statusChange", ({ status }) => {
+        if (status === "error") {
+          void telemetry.recordEvent({
+            eventType: PLAYBACK_EVENT_TYPE.ERROR,
+            positionSeconds: Math.floor(Math.max(0, player.currentTime)),
+            errorCode: "player_status_error",
+          })
+        }
+      })
+    )
+
+    subs.push(
+      player.addListener("timeUpdate", ({ currentTime }) => {
+        telemetry.updatePosition(Math.max(0, currentTime))
+      })
+    )
+
+    const appStateSub = AppState.addEventListener(
+      "change",
+      (next: AppStateStatus) => {
+        if (next === "active") {
+          telemetry.resumeHeartbeats()
+        } else {
+          telemetry.pauseHeartbeats()
+          void telemetry.flush()
+        }
+      }
+    )
+
+    return () => {
+      disposed = true
+      hasStartedPlaybackRef.current = false
+      subs.forEach((s) => {
+        s.remove()
+      })
+      appStateSub.remove()
+      void telemetry.destroy()
+    }
+  }, [
+    player,
+    playback?.embedId,
+    playback?.telemetry.bootstrapUrl,
+    eventsBaseUrl,
+    defaultHeaders,
+    viewerTokenStore,
+  ])
+}