@moviie/player-expo 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,450 @@
+import * as _moviie_player_sdk from '@moviie/player-sdk';
+import { ViewerTokenStore, MoviiePlaybackData } from '@moviie/player-sdk';
+export * from '@moviie/player-sdk';
+export { MoviieContextValue, MoviieProvider, useMoviieContext } from './layout.cjs';
+import * as expo_video from 'expo-video';
+import { VideoPlayer, VideoViewProps } from 'expo-video';
+import { PLAYER_API_EVENTS } from '@moviie/player-types';
+export { PLAYER_API_EVENTS, PLAYER_API_METHODS, PLAYER_API_PROPERTIES } from '@moviie/player-types';
+import { M as MoviieCastAdapter } from './moviie-cast-adapter-DmSU2u3j.cjs';
+export { a as MoviieCastMediaPayload, b as MoviieCastState } from './moviie-cast-adapter-DmSU2u3j.cjs';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import 'react/jsx-runtime';
+
+declare const MOVIIE_PLAYER_EXPO_PKG_VERSION: "0.4.0";
+declare const MOVIIE_PLAYBACK_MEMORY_CACHE_TTL_MS: number;
+/** Playback profile strings returned by the playback API (aligned with web embed). */
+declare const MOVIIE_PLAYBACK_PROFILE: {
+    readonly VSL: "vsl";
+    readonly CUSTOM: "custom";
+};
+/**
+ * SecureStore key prefix for resume position (`{prefix}{embedId}`).
+ * Embed IDs are UUIDs from the API.
+ */
+declare const MOVIIE_REMEMBER_POSITION_STORAGE_PREFIX: "moviie.resume_position.";
+/** Debounce interval before persisting resume position while playing. */
+declare const MOVIIE_REMEMBER_POSITION_DEBOUNCE_MS: 5000;
+/** Matches embed/web framing defaults when `contentFit` is omitted on `MoviieVideo`. */
+declare const MOVIIE_VIDEO_DEFAULT_CONTENT_FIT: {
+    readonly VERTICAL: "contain";
+    readonly HORIZONTAL: "cover";
+};
+/** Origin público da página watch/embed (sem barra final). Override: `EXPO_PUBLIC_MOVIIE_WATCH_ORIGIN`. */
+declare const MOVIIE_WATCH_ORIGIN_DEFAULT: "https://watch.moviie.ai";
+/**
+ * Variável `EXPO_PUBLIC_*` para override do origin watch/embed em Expo Web (`resolveMoviieWatchOrigin`).
+ */
+declare const EXPO_PUBLIC_MOVIIE_WATCH_ORIGIN_ENV: "EXPO_PUBLIC_MOVIIE_WATCH_ORIGIN";
+/** Path público do script da API JS do embed (relativo ao watch origin). */
+declare const MOVIIE_WATCH_EMBED_JS_PATH: "/embed.js";
+/**
+ * Atributo único no `<script>` injectado em Expo Web para evitar duplicar `embed.js`
+ * quando há vários `MoviieVideo` montados.
+ */
+declare const MOVIIE_PLAYER_EXPO_EMBED_JS_MARKER_ATTR: "data-moviie-player-expo-embed-js";
+/**
+ * Variável `EXPO_PUBLIC_*` que override a base da API Moviie em **dev only**.
+ * O Metro inlina qualquer `EXPO_PUBLIC_*` em build time, sem precisar de
+ * `expo-constants`. Em produção o SDK usa sempre o default `https://api.moviie.ai/v1`.
+ *
+ * Exemplo `.env.local`:
+ *   EXPO_PUBLIC_MOVIIE_API_BASE_URL=http://localhost:3000/api/v1
+ */
+declare const EXPO_PUBLIC_MOVIIE_API_BASE_URL_ENV: "EXPO_PUBLIC_MOVIIE_API_BASE_URL";
+/**
+ * Variável `EXPO_PUBLIC_*` que override a base de telemetria em **dev only**.
+ * Caso omitida, deriva-se de `{origin}/telemetry/v1` a partir de `apiBaseUrl`.
+ */
+declare const EXPO_PUBLIC_MOVIIE_EVENTS_BASE_URL_ENV: "EXPO_PUBLIC_MOVIIE_EVENTS_BASE_URL";
+declare const MOVIIE_SKIN_DEFAULT_ACCENT_HEX: "#6366f1";
+/**
+ * Valor legado para a prop `controlsAutoHideMs` / `autoHideMs`: o chrome da skin Moviie já não
+ * usa temporizador para ocultar — só ao toque fora ou ações (play, seek).
+ */
+declare const MOVIIE_SKIN_CONTROLS_AUTO_HIDE_MS: 3000;
+declare const MOVIIE_SKIN_CONTROL_ICON_PX: 22;
+/** Volume normalizado (0–1) abaixo disto usa o ícone `volume-low` como no Vidstack. */
+declare const MOVIIE_SKIN_VOLUME_LOW_ICON_THRESHOLD: 0.45;
+/**
+ * Segundos antes do fim onde o progresso mostrado fixa em 100% quando não está a reproduzir —
+ * o `currentTime` do motor costuma ficar ligeiramente abaixo de `duration` no fim.
+ */
+declare const MOVIIE_SKIN_TIMELINE_END_SNAP_EPSILON_SECONDS: 0.15;
+
+declare const MOVIIE_VIEWER_TOKEN_SECURE_STORE_KEY: "moviie_viewer_token_v1";
+declare class SecureStoreViewerTokenStore implements ViewerTokenStore {
+    private readonly fallback;
+    private readonly storageKey;
+    constructor(options?: {
+        fallback?: ViewerTokenStore;
+        storageKey?: string;
+    });
+    private loadSecureStore;
+    get(): Promise<string | null>;
+    set(token: string, ttlSec: number): Promise<void>;
+}
+
+interface UseMoviiePlaybackArgs {
+    /** Public embed UUID — client SDK never calls admin APIs or private keys. */
+    embedId?: string;
+}
+interface UseMoviiePlaybackResult {
+    data: MoviiePlaybackData | null;
+    error: Error | null;
+    isLoading: boolean;
+    retry: () => void;
+}
+declare function useMoviiePlayback(args: UseMoviiePlaybackArgs): UseMoviiePlaybackResult;
+
+type MoviieVideoPresentationProps = {
+    allowsPictureInPicture: boolean;
+    startsPictureInPictureAutomatically: boolean;
+    requiresLinearPlayback: boolean;
+};
+interface BuildMoviieVideoPresentationArgs {
+    profile: string;
+    showPip: boolean;
+    /**
+     * Integrator override: when set, replaces embed `showPip` for `allowsPictureInPicture`.
+     * When omitted, `showPip` is used.
+     */
+    pictureInPicture?: boolean;
+    /**
+     * Integrator override for `startsPictureInPictureAutomatically`.
+     * When omitted, defaults to `false` (no embed field today).
+     */
+    pictureInPictureAutoStart?: boolean;
+}
+/**
+ * Maps embed playback flags onto `VideoView` presentation props.
+ * Optional fields let integrators override embed defaults explicitly; omit them to follow the API.
+ */
+declare function buildMoviieVideoPresentationProps(args: BuildMoviieVideoPresentationArgs): MoviieVideoPresentationProps;
+
+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;
+}
+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;
+}
+
+declare function useMoviiePlayer(options: UseMoviiePlayerOptions): UseMoviiePlayerResult;
+
+type PublicPlayerEvent = (typeof PLAYER_API_EVENTS)[keyof typeof PLAYER_API_EVENTS];
+declare function useMoviieEvent(player: VideoPlayer | null, eventName: PublicPlayerEvent, handler: () => void): void;
+
+/**
+ * Natural playback end from expo-video (`playToEnd`), aligned with {@link PLAYER_API_EVENTS.ENDED}.
+ */
+declare function useMoviiePlaybackEnded(player: VideoPlayer | null, onEnded: () => void): void;
+
+type MoviiePlaybackEndedUiArgs = {
+    playing: boolean;
+    currentTime: number;
+    duration: number;
+    isLive: boolean;
+    loop: boolean;
+};
+declare function computeMoviiePlaybackEnded(args: MoviiePlaybackEndedUiArgs): boolean;
+
+type MoviiePlaybackEndedSubscription = {
+    remove: () => void;
+};
+/**
+ * Imperative listener for expo-video `playToEnd`. Prefer {@link useMoviiePlaybackEnded} in React components.
+ */
+declare function addMoviiePlaybackEndedListener(player: VideoPlayer, onEnded: () => void): MoviiePlaybackEndedSubscription;
+
+declare function normalizeWatchOrigin(origin: string): string;
+declare function buildMoviieWatchEmbedUrl(embedId: string, watchOrigin: string): string;
+/**
+ * Resolve o origin público da página watch/embed.
+ * Usa `process.env.EXPO_PUBLIC_MOVIIE_WATCH_ORIGIN` quando definido (nome documentado como `EXPO_PUBLIC_MOVIIE_WATCH_ORIGIN_ENV` em `@moviie/player-expo`).
+ */
+declare function resolveMoviieWatchOrigin(): string;
+
+/**
+ * Hooks opt-in para telemetria do consumer (Sentry, PostHog, Datadog, etc.).
+ *
+ * `@moviie/player-expo` já envia telemetria interna para o backend Moviie via
+ * `TelemetryClient` (impressions, playback duration). Estes callbacks servem
+ * exclusivamente para o consumer também observar eventos em **sua própria**
+ * pipeline de monitoring — não substituem nem ampliam a telemetria interna.
+ *
+ * **Garantias**:
+ * - Callbacks são síncronos e não-bloqueantes: exceções neles são engolidas e
+ *   loggadas via `console.warn` (não derrubam o player).
+ * - Sem PII: eventos só carregam `embedId` público e métricas técnicas.
+ * - Cada evento é entregue at-most-once por ciclo de vida do player.
+ */
+type MoviieTelemetryErrorPhase = 
+/** Falha ao carregar metadata de playback (`useMoviiePlayback`). */
+'playback_fetch'
+/** Falha durante reprodução (network stall, decode error, DRM, etc.). */
+ | 'playback_runtime'
+/** Falha capturada pelo `MoviieErrorBoundary` (render/effect throw). */
+ | 'render_boundary';
+interface MoviieTelemetryErrorContext {
+    /** UUID público do embed em causa, se disponível. */
+    embedId?: string;
+    /** Categorização da fase onde o erro ocorreu. */
+    phase: MoviieTelemetryErrorPhase;
+    /** Código de erro classificado pelo SDK (quando aplicável). */
+    code?: string;
+}
+type MoviieTelemetryLifecycleEventName = 'playback_loaded' | 'playback_started' | 'playback_paused' | 'playback_seeking' | 'playback_ended' | 'fullscreen_enter' | 'fullscreen_exit' | 'pip_enter' | 'pip_exit' | 'cast_session_started' | 'cast_session_ended';
+interface MoviieTelemetryLifecycleEvent {
+    name: MoviieTelemetryLifecycleEventName;
+    embedId?: string;
+    /** Posição (segundos) no momento do evento, quando relevante. */
+    positionSeconds?: number;
+    /** Duração total (segundos) quando conhecida. */
+    durationSeconds?: number;
+}
+type MoviieTelemetryOnError = (error: Error, context: MoviieTelemetryErrorContext) => void;
+type MoviieTelemetryOnEvent = (event: MoviieTelemetryLifecycleEvent) => void;
+
+/**
+ * Subconjunto do elemento iframe usado na integração web (embed watch).
+ * Evita acoplar o pacote à lib DOM completa no tsconfig.
+ */
+type MoviieWatchEmbedIframeHandle = {
+    readonly contentWindow: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    } | null;
+};
+type MoviieWatchEmbedIframeRefCallback = (iframe: MoviieWatchEmbedIframeHandle | null) => void;
+type MoviieVideoProps = Omit<VideoViewProps, 'player'> & {
+    /**
+     * Instância `VideoPlayer` do expo-video (iOS / Android).
+     * Na web, `useMoviiePlayer` devolve `null` e `MoviieVideo` usa iframe do embed.
+     */
+    player: VideoPlayer | null;
+    nativeControls?: boolean;
+    /**
+     * When `true`, uses the platform `VideoView` chrome. When `false` or omitted, uses the Moviie custom chrome (default).
+     */
+    native?: boolean;
+    playback?: MoviiePlaybackData | null;
+    /**
+     * Optional override: when set, replaces embed `showPip` for PiP capability (with {@link pictureInPictureAutoStart}).
+     * Raw `VideoView` props (`allowsPictureInPicture`, …) still win when passed explicitly.
+     */
+    pictureInPicture?: boolean;
+    /**
+     * Optional override for auto-start PiP. Embed has no field for this; omit for `false` unless set here or on the hook.
+     */
+    pictureInPictureAutoStart?: boolean;
+    /**
+     * Ignorado quando `native` é omitido ou `false`: o chrome Moviie não usa temporizador para ocultar.
+     */
+    controlsAutoHideMs?: number;
+    controlsVisibleByDefault?: boolean;
+    children?: ReactNode;
+    /**
+     * Web: callback com referência ao iframe após montagem, para `Moviie.getPlayer(iframe)` (`embed.js`).
+     */
+    onEmbedIframeRef?: MoviieWatchEmbedIframeRefCallback;
+    /**
+     * Web: injeta `<script src="{watchOrigin}/embed.js">` uma vez. Ignorado em nativo. Default `true`.
+     */
+    loadEmbedScript?: boolean;
+    /**
+     * Erro vindo de `useMoviiePlayer`/`useMoviiePlayback`. Quando preenchido (e sem `playback`),
+     * a shell built-in mostra feedback de erro com CTA mapeado por código.
+     */
+    error?: Error | null;
+    /**
+     * Indica que o fetch de playback está em curso. Quando `true` (e sem `playback`), a shell
+     * built-in mostra estado de carregamento.
+     */
+    isLoading?: boolean;
+    /**
+     * Aspect ratio do container reservado pelo player enquanto não há dimensões intrínsecas do
+     * vídeo. Default `16/9`. Após `playback` chegar, o container passa a usar `videoWidthPx/videoHeightPx`.
+     */
+    aspectRatio?: number;
+    /**
+     * Callback opcional para erros transientes (network/rate_limit). Override do retry built-in.
+     * Tem precedência sobre {@link retry}.
+     */
+    onRetry?: () => void;
+    /**
+     * Função de retry built-in fornecida por `useMoviiePlayer().retry`. Aceita o spread do hook
+     * sem boilerplate. Quando `onRetry` é fornecido, este é ignorado.
+     */
+    retry?: () => void;
+    /**
+     * Adapter opcional para cast (Chromecast). Crie via factory do subpath
+     * `@moviie/player-expo/cast` (`createGoogleCastAdapter()`) e passe aqui.
+     *
+     * Quando omitido, o botão de cast não aparece. Se o embed pede cast
+     * (`playback.controls.chromecast === true`) e o adapter não foi fornecido,
+     * dispara um `console.warn` único com instruções.
+     */
+    castAdapter?: MoviieCastAdapter | null;
+    /**
+     * Override explícito do flag `playback.controls.chromecast`. Quando definido,
+     * vence o painel:
+     *  - `true`: força exibir botão (se adapter estiver disponível);
+     *  - `false`: força esconder e silencia warning;
+     *  - omitido: usa o flag do painel.
+     */
+    cast?: boolean;
+    /**
+     * Callback opt-in invocado quando um erro relevante ocorre — para integração
+     * com Sentry/PostHog/Datadog do consumer.
+     *
+     * Não substitui nem expande a telemetria interna enviada ao backend Moviie.
+     * Exceções lançadas dentro do callback são engolidas e logged via warn.
+     *
+     * @example
+     * ```tsx
+     * <MoviieVideo
+     *   {...moviie}
+     *   onTelemetryError={(error, ctx) => Sentry.captureException(error, { tags: ctx })}
+     * />
+     * ```
+     */
+    onTelemetryError?: MoviieTelemetryOnError;
+    /**
+     * Callback opt-in invocado em eventos de ciclo de vida do player
+     * (play, pause, seek, fullscreen, cast). Útil para correlacionar UX com erros
+     * em ferramentas de observability do consumer.
+     *
+     * @example
+     * ```tsx
+     * <MoviieVideo
+     *   {...moviie}
+     *   onTelemetryEvent={(e) => posthog.capture(`player.${e.name}`, e)}
+     * />
+     * ```
+     */
+    onTelemetryEvent?: MoviieTelemetryOnEvent;
+};
+
+/** Subconjunto do VideoView nativo usado pela skin (tipagens expo-video × React). */
+type MoviieVideoSurfaceRef = {
+    enterFullscreen?: () => Promise<void>;
+    exitFullscreen?: () => Promise<void>;
+    startPictureInPicture?: () => Promise<void>;
+    stopPictureInPicture?: () => Promise<void>;
+};
+
+declare const MoviieVideo: React.ForwardRefExoticComponent<Omit<VideoViewProps, "player"> & {
+    player: expo_video.VideoPlayer | null;
+    nativeControls?: boolean;
+    native?: boolean;
+    playback?: _moviie_player_sdk.MoviiePlaybackData | null;
+    pictureInPicture?: boolean;
+    pictureInPictureAutoStart?: boolean;
+    controlsAutoHideMs?: number;
+    controlsVisibleByDefault?: boolean;
+    children?: React.ReactNode;
+    onEmbedIframeRef?: MoviieWatchEmbedIframeRefCallback;
+    loadEmbedScript?: boolean;
+    error?: Error | null;
+    isLoading?: boolean;
+    aspectRatio?: number;
+    onRetry?: () => void;
+    retry?: () => void;
+    castAdapter?: MoviieCastAdapter | null;
+    cast?: boolean;
+    onTelemetryError?: MoviieTelemetryOnError;
+    onTelemetryEvent?: MoviieTelemetryOnEvent;
+} & React.RefAttributes<MoviieVideoSurfaceRef>>;
+
+/**
+ * React error boundary que isola crashes do player do resto da árvore.
+ *
+ * Quando uma exceção é lançada durante o render/effect de `MoviieVideo` (ex.: bug
+ * em `expo-video`, lib nativa ausente, payload corrompido), o consumer perderia
+ * a UI inteira se não houvesse boundary. Este wrapper captura o erro, opcionalmente
+ * notifica via `onError` (Sentry/PostHog do consumer) e renderiza um fallback.
+ *
+ * Use em torno de `MoviieVideo`:
+ *
+ * ```tsx
+ * <MoviieErrorBoundary onError={Sentry.captureException}>
+ *   <MoviieVideo embedId={id} />
+ * </MoviieErrorBoundary>
+ * ```
+ */
+
+interface MoviieErrorBoundaryProps {
+    /**
+     * Conteúdo protegido. Tipicamente `<MoviieVideo>` e árvores derivadas.
+     */
+    children: React__default.ReactNode;
+    /**
+     * Render override quando há erro. Recebe `error` e função `reset` que limpa
+     * o estado de erro e força nova montagem dos children.
+     *
+     * Default: `null` (renderiza nada). Recomendado passar um placeholder visual.
+     */
+    fallback?: (args: {
+        error: Error;
+        reset: () => void;
+    }) => React__default.ReactNode;
+    /**
+     * Hook chamado uma vez por erro capturado. Use para telemetria
+     * (Sentry/PostHog/Datadog) — não bloqueia o render do fallback.
+     */
+    onError?: (error: Error, info: React__default.ErrorInfo) => void;
+}
+interface MoviieErrorBoundaryState {
+    error: Error | null;
+}
+declare class MoviieErrorBoundary extends React__default.Component<MoviieErrorBoundaryProps, MoviieErrorBoundaryState> {
+    state: MoviieErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): MoviieErrorBoundaryState;
+    componentDidCatch(error: Error, info: React__default.ErrorInfo): void;
+    reset: () => void;
+    render(): React__default.ReactNode;
+}
+
+export { EXPO_PUBLIC_MOVIIE_API_BASE_URL_ENV, EXPO_PUBLIC_MOVIIE_EVENTS_BASE_URL_ENV, EXPO_PUBLIC_MOVIIE_WATCH_ORIGIN_ENV, MOVIIE_PLAYBACK_MEMORY_CACHE_TTL_MS, MOVIIE_PLAYBACK_PROFILE, MOVIIE_PLAYER_EXPO_EMBED_JS_MARKER_ATTR, MOVIIE_PLAYER_EXPO_PKG_VERSION, MOVIIE_REMEMBER_POSITION_DEBOUNCE_MS, MOVIIE_REMEMBER_POSITION_STORAGE_PREFIX, MOVIIE_SKIN_CONTROLS_AUTO_HIDE_MS, MOVIIE_SKIN_CONTROL_ICON_PX, MOVIIE_SKIN_DEFAULT_ACCENT_HEX, MOVIIE_SKIN_TIMELINE_END_SNAP_EPSILON_SECONDS, MOVIIE_SKIN_VOLUME_LOW_ICON_THRESHOLD, MOVIIE_VIDEO_DEFAULT_CONTENT_FIT, MOVIIE_VIEWER_TOKEN_SECURE_STORE_KEY, MOVIIE_WATCH_EMBED_JS_PATH, MOVIIE_WATCH_ORIGIN_DEFAULT, MoviieCastAdapter, MoviieErrorBoundary, type MoviieErrorBoundaryProps, type MoviiePlaybackEndedSubscription, type MoviiePlaybackEndedUiArgs, type MoviieTelemetryErrorContext, type MoviieTelemetryErrorPhase, type MoviieTelemetryLifecycleEvent, type MoviieTelemetryLifecycleEventName, type MoviieTelemetryOnError, type MoviieTelemetryOnEvent, MoviieVideo, type MoviieVideoPresentationProps, type MoviieVideoProps, type MoviieVideoSurfaceRef, type MoviieWatchEmbedIframeHandle, type MoviieWatchEmbedIframeRefCallback, SecureStoreViewerTokenStore, type UseMoviiePlaybackArgs, type UseMoviiePlaybackResult, type UseMoviiePlayerOptions, type UseMoviiePlayerResult, addMoviiePlaybackEndedListener, buildMoviieVideoPresentationProps, buildMoviieWatchEmbedUrl, computeMoviiePlaybackEnded, normalizeWatchOrigin, resolveMoviieWatchOrigin, useMoviieEvent, useMoviiePlayback, useMoviiePlaybackEnded, useMoviiePlayer };