@moviie/player-sdk 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,6 +1,55 @@
 import { z } from 'zod';
 export { PLAYER_API_EVENTS, PlayerAPIEvent, PlayerState } from '@moviie/player-types';
 
+/** A single moment in the video where the term occurs. */
+interface TranscriptSearchMatch {
+    segmentIndex: number;
+    startSeconds: number;
+    endSeconds: number;
+    /** The sentence/segment containing the term (length-bounded by the server). */
+    text: string;
+}
+/** Result set for one transcript search query. */
+interface TranscriptSearchResult {
+    query: string;
+    language: string | null;
+    total: number;
+    matches: TranscriptSearchMatch[];
+    nextCursor: number | null;
+}
+/** Default debounce and minimum query length for the in-player search UI. */
+declare const TRANSCRIPT_SEARCH_DEBOUNCE_MS = 250;
+declare const TRANSCRIPT_SEARCH_MIN_LENGTH = 2;
+/** Low-level fetch of the transcript search endpoint, with error mapping. */
+declare function fetchTranscriptSearch(params: {
+    url: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}): Promise<TranscriptSearchResult>;
+interface TranscriptSearchController {
+    /** Schedule a debounced search for the (trimmed) query. */
+    search(query: string): void;
+    /** Cancel any pending debounce and in-flight request. */
+    cancel(): void;
+    /** Tear down the controller. */
+    destroy(): void;
+}
+/**
+ * UI controller that applies debounce + a minimum query length before calling
+ * the search endpoint, and aborts any in-flight request when a newer query
+ * arrives. Queries below the minimum length clear the results without hitting
+ * the network — this is what keeps incomplete words from flooding the backend
+ * (FR-003 / SC-002).
+ */
+declare function createTranscriptSearchController(opts: {
+    fetcher: (query: string, signal: AbortSignal) => Promise<TranscriptSearchResult>;
+    onResult: (result: TranscriptSearchResult) => void;
+    onError?: (error: unknown) => void;
+    onLoadingChange?: (loading: boolean) => void;
+    debounceMs?: number;
+    minLength?: number;
+}): TranscriptSearchController;
+
 interface MoviieClientInfo {
     bundleId?: string;
     platform: "ios" | "android" | "web";
@@ -103,6 +152,30 @@ declare class MoviieClient {
     });
     private headers;
     getPlayback(embedId: string, signal?: AbortSignal): Promise<MoviiePlaybackData>;
+    /**
+     * Search the spoken content of the video a playback session is playing, and
+     * return the moments where the term appears (each with a timestamp). The
+     * session scopes the search to the video it actually loaded (swap-safe) and
+     * authorizes the request — it was gated when bootstrapped. Obtain the session
+     * id from the telemetry bootstrap. Matching is case- and accent-insensitive.
+     */
+    search(sessionId: string, query: string, opts?: {
+        limit?: number;
+        cursor?: number | null;
+        signal?: AbortSignal;
+    }): Promise<TranscriptSearchResult>;
+    /**
+     * Private transcript search for an embed's video (feature 183) — the
+     * authenticated twin of {@link search}. Requires a PRIVATE API key (publishable
+     * keys are rejected) and is scoped to the key's organization; the embed must
+     * belong to it. Unlike {@link search} it needs no playback session. Matching is
+     * case- and accent-insensitive.
+     */
+    searchEmbedTranscript(embedId: string, query: string, opts?: {
+        limit?: number;
+        cursor?: number | null;
+        signal?: AbortSignal;
+    }): Promise<TranscriptSearchResult>;
     getVideo(videoId: string, signal?: AbortSignal): Promise<MoviieVideo>;
     resolveEmbedIdFromVideoId(videoId: string, signal?: AbortSignal): Promise<string>;
     getEventsBaseUrl(): string;
@@ -267,4 +340,4 @@ declare const MOVIIE_WATCH_BASE = "https://watch.moviie.ai";
 
 declare function deriveTelemetryEventsBaseUrlFromBootstrapUrl(bootstrapUrl: string): string | null;
 
-export { HEARTBEAT_CONFIG, MOVIIE_CDN_BASE, MOVIIE_DEFAULT_API_BASE_URL, MOVIIE_TELEMETRY_API_PATH_PREFIX, MOVIIE_WATCH_BASE, MemoryViewerTokenStore, MoviieAuthError, MoviieBundleBlockedError, type MoviieCTA, type MoviieCaption, type MoviieChapter, MoviieClient, type MoviieClientInfo, type MoviieEndpointsConfiguration, type MoviieErrorCode, MoviieNetworkError, MoviieNotFoundError, type MoviiePlaybackControls, type MoviiePlaybackData, MoviieRateLimitError, MoviieReferrerBlockedError, MoviieSubscriptionInactiveError, type MoviieVideo, PLAYBACK_EVENT_TYPE, SDK_PLAYBACK_AUTH_ERROR_MESSAGE, SDK_PUBLIC_API_KEY_PREFIX_PUBLISHABLE, TELEMETRY_TOKEN_CONFIG, TelemetryClient, type ViewerTokenStore, buildClientHeaders, configureMoviieEndpoints, deriveMoviieTelemetryBaseUrlFromApiBaseUrl, deriveTelemetryEventsBaseUrlFromBootstrapUrl, fetchPlaybackData, getMoviieApiBaseUrl, getMoviieEventsBaseUrl, planRefresh, resetMoviieEndpointsConfiguration };
+export { HEARTBEAT_CONFIG, MOVIIE_CDN_BASE, MOVIIE_DEFAULT_API_BASE_URL, MOVIIE_TELEMETRY_API_PATH_PREFIX, MOVIIE_WATCH_BASE, MemoryViewerTokenStore, MoviieAuthError, MoviieBundleBlockedError, type MoviieCTA, type MoviieCaption, type MoviieChapter, MoviieClient, type MoviieClientInfo, type MoviieEndpointsConfiguration, type MoviieErrorCode, MoviieNetworkError, MoviieNotFoundError, type MoviiePlaybackControls, type MoviiePlaybackData, MoviieRateLimitError, MoviieReferrerBlockedError, MoviieSubscriptionInactiveError, type MoviieVideo, PLAYBACK_EVENT_TYPE, SDK_PLAYBACK_AUTH_ERROR_MESSAGE, SDK_PUBLIC_API_KEY_PREFIX_PUBLISHABLE, TELEMETRY_TOKEN_CONFIG, TRANSCRIPT_SEARCH_DEBOUNCE_MS, TRANSCRIPT_SEARCH_MIN_LENGTH, TelemetryClient, type TranscriptSearchController, type TranscriptSearchMatch, type TranscriptSearchResult, type ViewerTokenStore, buildClientHeaders, configureMoviieEndpoints, createTranscriptSearchController, deriveMoviieTelemetryBaseUrlFromApiBaseUrl, deriveTelemetryEventsBaseUrlFromBootstrapUrl, fetchPlaybackData, fetchTranscriptSearch, getMoviieApiBaseUrl, getMoviieEventsBaseUrl, planRefresh, resetMoviieEndpointsConfiguration };

package/dist/index.d.ts

@@ -1,6 +1,55 @@
 import { z } from 'zod';
 export { PLAYER_API_EVENTS, PlayerAPIEvent, PlayerState } from '@moviie/player-types';
 
+/** A single moment in the video where the term occurs. */
+interface TranscriptSearchMatch {
+    segmentIndex: number;
+    startSeconds: number;
+    endSeconds: number;
+    /** The sentence/segment containing the term (length-bounded by the server). */
+    text: string;
+}
+/** Result set for one transcript search query. */
+interface TranscriptSearchResult {
+    query: string;
+    language: string | null;
+    total: number;
+    matches: TranscriptSearchMatch[];
+    nextCursor: number | null;
+}
+/** Default debounce and minimum query length for the in-player search UI. */
+declare const TRANSCRIPT_SEARCH_DEBOUNCE_MS = 250;
+declare const TRANSCRIPT_SEARCH_MIN_LENGTH = 2;
+/** Low-level fetch of the transcript search endpoint, with error mapping. */
+declare function fetchTranscriptSearch(params: {
+    url: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}): Promise<TranscriptSearchResult>;
+interface TranscriptSearchController {
+    /** Schedule a debounced search for the (trimmed) query. */
+    search(query: string): void;
+    /** Cancel any pending debounce and in-flight request. */
+    cancel(): void;
+    /** Tear down the controller. */
+    destroy(): void;
+}
+/**
+ * UI controller that applies debounce + a minimum query length before calling
+ * the search endpoint, and aborts any in-flight request when a newer query
+ * arrives. Queries below the minimum length clear the results without hitting
+ * the network — this is what keeps incomplete words from flooding the backend
+ * (FR-003 / SC-002).
+ */
+declare function createTranscriptSearchController(opts: {
+    fetcher: (query: string, signal: AbortSignal) => Promise<TranscriptSearchResult>;
+    onResult: (result: TranscriptSearchResult) => void;
+    onError?: (error: unknown) => void;
+    onLoadingChange?: (loading: boolean) => void;
+    debounceMs?: number;
+    minLength?: number;
+}): TranscriptSearchController;
+
 interface MoviieClientInfo {
     bundleId?: string;
     platform: "ios" | "android" | "web";
@@ -103,6 +152,30 @@ declare class MoviieClient {
     });
     private headers;
     getPlayback(embedId: string, signal?: AbortSignal): Promise<MoviiePlaybackData>;
+    /**
+     * Search the spoken content of the video a playback session is playing, and
+     * return the moments where the term appears (each with a timestamp). The
+     * session scopes the search to the video it actually loaded (swap-safe) and
+     * authorizes the request — it was gated when bootstrapped. Obtain the session
+     * id from the telemetry bootstrap. Matching is case- and accent-insensitive.
+     */
+    search(sessionId: string, query: string, opts?: {
+        limit?: number;
+        cursor?: number | null;
+        signal?: AbortSignal;
+    }): Promise<TranscriptSearchResult>;
+    /**
+     * Private transcript search for an embed's video (feature 183) — the
+     * authenticated twin of {@link search}. Requires a PRIVATE API key (publishable
+     * keys are rejected) and is scoped to the key's organization; the embed must
+     * belong to it. Unlike {@link search} it needs no playback session. Matching is
+     * case- and accent-insensitive.
+     */
+    searchEmbedTranscript(embedId: string, query: string, opts?: {
+        limit?: number;
+        cursor?: number | null;
+        signal?: AbortSignal;
+    }): Promise<TranscriptSearchResult>;
     getVideo(videoId: string, signal?: AbortSignal): Promise<MoviieVideo>;
     resolveEmbedIdFromVideoId(videoId: string, signal?: AbortSignal): Promise<string>;
     getEventsBaseUrl(): string;
@@ -267,4 +340,4 @@ declare const MOVIIE_WATCH_BASE = "https://watch.moviie.ai";
 
 declare function deriveTelemetryEventsBaseUrlFromBootstrapUrl(bootstrapUrl: string): string | null;
 
-export { HEARTBEAT_CONFIG, MOVIIE_CDN_BASE, MOVIIE_DEFAULT_API_BASE_URL, MOVIIE_TELEMETRY_API_PATH_PREFIX, MOVIIE_WATCH_BASE, MemoryViewerTokenStore, MoviieAuthError, MoviieBundleBlockedError, type MoviieCTA, type MoviieCaption, type MoviieChapter, MoviieClient, type MoviieClientInfo, type MoviieEndpointsConfiguration, type MoviieErrorCode, MoviieNetworkError, MoviieNotFoundError, type MoviiePlaybackControls, type MoviiePlaybackData, MoviieRateLimitError, MoviieReferrerBlockedError, MoviieSubscriptionInactiveError, type MoviieVideo, PLAYBACK_EVENT_TYPE, SDK_PLAYBACK_AUTH_ERROR_MESSAGE, SDK_PUBLIC_API_KEY_PREFIX_PUBLISHABLE, TELEMETRY_TOKEN_CONFIG, TelemetryClient, type ViewerTokenStore, buildClientHeaders, configureMoviieEndpoints, deriveMoviieTelemetryBaseUrlFromApiBaseUrl, deriveTelemetryEventsBaseUrlFromBootstrapUrl, fetchPlaybackData, getMoviieApiBaseUrl, getMoviieEventsBaseUrl, planRefresh, resetMoviieEndpointsConfiguration };
+export { HEARTBEAT_CONFIG, MOVIIE_CDN_BASE, MOVIIE_DEFAULT_API_BASE_URL, MOVIIE_TELEMETRY_API_PATH_PREFIX, MOVIIE_WATCH_BASE, MemoryViewerTokenStore, MoviieAuthError, MoviieBundleBlockedError, type MoviieCTA, type MoviieCaption, type MoviieChapter, MoviieClient, type MoviieClientInfo, type MoviieEndpointsConfiguration, type MoviieErrorCode, MoviieNetworkError, MoviieNotFoundError, type MoviiePlaybackControls, type MoviiePlaybackData, MoviieRateLimitError, MoviieReferrerBlockedError, MoviieSubscriptionInactiveError, type MoviieVideo, PLAYBACK_EVENT_TYPE, SDK_PLAYBACK_AUTH_ERROR_MESSAGE, SDK_PUBLIC_API_KEY_PREFIX_PUBLISHABLE, TELEMETRY_TOKEN_CONFIG, TRANSCRIPT_SEARCH_DEBOUNCE_MS, TRANSCRIPT_SEARCH_MIN_LENGTH, TelemetryClient, type TranscriptSearchController, type TranscriptSearchMatch, type TranscriptSearchResult, type ViewerTokenStore, buildClientHeaders, configureMoviieEndpoints, createTranscriptSearchController, deriveMoviieTelemetryBaseUrlFromApiBaseUrl, deriveTelemetryEventsBaseUrlFromBootstrapUrl, fetchPlaybackData, fetchTranscriptSearch, getMoviieApiBaseUrl, getMoviieEventsBaseUrl, planRefresh, resetMoviieEndpointsConfiguration };

package/dist/index.js

@@ -268,6 +268,102 @@ async function fetchPlaybackData(params) {
   }
   return parsed.data;
 }
+var matchSchema = z.object({
+  segmentIndex: z.number().int(),
+  startSeconds: z.number(),
+  endSeconds: z.number(),
+  text: z.string()
+});
+var resultSchema = z.object({
+  query: z.string(),
+  language: z.string().nullable(),
+  total: z.number().int(),
+  matches: z.array(matchSchema),
+  nextCursor: z.number().int().nullable()
+});
+var TRANSCRIPT_SEARCH_DEBOUNCE_MS = 250;
+var TRANSCRIPT_SEARCH_MIN_LENGTH = 2;
+var EMPTY_RESULT = (query) => ({
+  query,
+  language: null,
+  total: 0,
+  matches: [],
+  nextCursor: null
+});
+async function fetchTranscriptSearch(params) {
+  const response = await fetchWithRetry(params.url, {
+    method: "GET",
+    headers: params.headers,
+    signal: params.signal
+  });
+  if (response.status === 401) throw new MoviieAuthError();
+  if (response.status === 404) throw new MoviieNotFoundError();
+  if (response.status >= 500) throw new MoviieNetworkError();
+  if (!response.ok) throw new MoviieNetworkError();
+  const json = await response.json();
+  const parsed = resultSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new MoviieNetworkError("Resposta de busca inv\xE1lida");
+  }
+  return parsed.data;
+}
+function createTranscriptSearchController(opts) {
+  const debounceMs = opts.debounceMs ?? TRANSCRIPT_SEARCH_DEBOUNCE_MS;
+  const minLength = opts.minLength ?? TRANSCRIPT_SEARCH_MIN_LENGTH;
+  let timer = null;
+  let inFlight = null;
+  function clearTimer() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  function cancelInFlight() {
+    if (inFlight) {
+      inFlight.abort();
+      inFlight = null;
+    }
+  }
+  function search(rawQuery) {
+    const query = rawQuery.trim();
+    clearTimer();
+    if (query.length < minLength) {
+      cancelInFlight();
+      opts.onResult(EMPTY_RESULT(query));
+      return;
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      cancelInFlight();
+      const controller = new AbortController();
+      inFlight = controller;
+      opts.onLoadingChange?.(true);
+      opts.fetcher(query, controller.signal).then((result) => {
+        if (!controller.signal.aborted) opts.onResult(result);
+      }).catch((error) => {
+        if (controller.signal.aborted) return;
+        if (error instanceof Error && error.name === "AbortError") return;
+        opts.onError?.(error);
+      }).finally(() => {
+        if (inFlight === controller) {
+          inFlight = null;
+          opts.onLoadingChange?.(false);
+        }
+      });
+    }, debounceMs);
+  }
+  return {
+    search,
+    cancel() {
+      clearTimer();
+      cancelInFlight();
+    },
+    destroy() {
+      clearTimer();
+      cancelInFlight();
+    }
+  };
+}
 
 // src/client/moviie-client.ts
 var videoEmbedResponseSchema = z.object({
@@ -305,6 +401,50 @@ var MoviieClient = class {
       signal
     });
   }
+  /**
+   * Search the spoken content of the video a playback session is playing, and
+   * return the moments where the term appears (each with a timestamp). The
+   * session scopes the search to the video it actually loaded (swap-safe) and
+   * authorizes the request — it was gated when bootstrapped. Obtain the session
+   * id from the telemetry bootstrap. Matching is case- and accent-insensitive.
+   */
+  async search(sessionId, query, opts) {
+    const key = this.options.publishableKey?.trim();
+    if (!key) {
+      throw new MoviieAuthError(SDK_PLAYBACK_AUTH_ERROR_MESSAGE.KEY_REQUIRED);
+    }
+    if (!key.startsWith(SDK_PUBLIC_API_KEY_PREFIX_PUBLISHABLE)) {
+      throw new MoviieAuthError(SDK_PLAYBACK_AUTH_ERROR_MESSAGE.PRIVATE_KEY_FORBIDDEN);
+    }
+    const base = getMoviieApiBaseUrl().replace(/\/+$/, "");
+    const params = new URLSearchParams({ q: query });
+    if (opts?.limit != null) params.set("limit", String(opts.limit));
+    if (opts?.cursor != null) params.set("cursor", String(opts.cursor));
+    const url = `${base}/sessions/${encodeURIComponent(sessionId)}/search?${params.toString()}`;
+    return fetchTranscriptSearch({ url, headers: this.headers(), signal: opts?.signal });
+  }
+  /**
+   * Private transcript search for an embed's video (feature 183) — the
+   * authenticated twin of {@link search}. Requires a PRIVATE API key (publishable
+   * keys are rejected) and is scoped to the key's organization; the embed must
+   * belong to it. Unlike {@link search} it needs no playback session. Matching is
+   * case- and accent-insensitive.
+   */
+  async searchEmbedTranscript(embedId, query, opts) {
+    const key = this.options.publishableKey?.trim();
+    if (!key) {
+      throw new MoviieAuthError(SDK_PLAYBACK_AUTH_ERROR_MESSAGE.KEY_REQUIRED);
+    }
+    if (key.startsWith(SDK_PUBLIC_API_KEY_PREFIX_PUBLISHABLE)) {
+      throw new MoviieAuthError("A busca privada exige uma chave de API privada (n\xE3o publishable).");
+    }
+    const base = getMoviieApiBaseUrl().replace(/\/+$/, "");
+    const params = new URLSearchParams({ q: query });
+    if (opts?.limit != null) params.set("limit", String(opts.limit));
+    if (opts?.cursor != null) params.set("cursor", String(opts.cursor));
+    const url = `${base}/embeds/${encodeURIComponent(embedId)}/transcript/search?${params.toString()}`;
+    return fetchTranscriptSearch({ url, headers: this.headers(), signal: opts?.signal });
+  }
   async getVideo(videoId, signal) {
     const key = this.options.publishableKey?.trim();
     if (!key) {
@@ -730,6 +870,6 @@ function deriveTelemetryEventsBaseUrlFromBootstrapUrl(bootstrapUrl) {
   }
 }
 
-export { HEARTBEAT_CONFIG, MOVIIE_CDN_BASE, MOVIIE_DEFAULT_API_BASE_URL, MOVIIE_TELEMETRY_API_PATH_PREFIX, MOVIIE_WATCH_BASE, MemoryViewerTokenStore, MoviieAuthError, MoviieBundleBlockedError, MoviieClient, MoviieNetworkError, MoviieNotFoundError, MoviieRateLimitError, MoviieReferrerBlockedError, MoviieSubscriptionInactiveError, PLAYBACK_EVENT_TYPE, SDK_PLAYBACK_AUTH_ERROR_MESSAGE, SDK_PUBLIC_API_KEY_PREFIX_PUBLISHABLE, TELEMETRY_TOKEN_CONFIG, TelemetryClient, buildClientHeaders, configureMoviieEndpoints, deriveMoviieTelemetryBaseUrlFromApiBaseUrl, deriveTelemetryEventsBaseUrlFromBootstrapUrl, fetchPlaybackData, getMoviieApiBaseUrl, getMoviieEventsBaseUrl, planRefresh, resetMoviieEndpointsConfiguration };
+export { HEARTBEAT_CONFIG, MOVIIE_CDN_BASE, MOVIIE_DEFAULT_API_BASE_URL, MOVIIE_TELEMETRY_API_PATH_PREFIX, MOVIIE_WATCH_BASE, MemoryViewerTokenStore, MoviieAuthError, MoviieBundleBlockedError, MoviieClient, MoviieNetworkError, MoviieNotFoundError, MoviieRateLimitError, MoviieReferrerBlockedError, MoviieSubscriptionInactiveError, PLAYBACK_EVENT_TYPE, SDK_PLAYBACK_AUTH_ERROR_MESSAGE, SDK_PUBLIC_API_KEY_PREFIX_PUBLISHABLE, TELEMETRY_TOKEN_CONFIG, TRANSCRIPT_SEARCH_DEBOUNCE_MS, TRANSCRIPT_SEARCH_MIN_LENGTH, TelemetryClient, buildClientHeaders, configureMoviieEndpoints, createTranscriptSearchController, deriveMoviieTelemetryBaseUrlFromApiBaseUrl, deriveTelemetryEventsBaseUrlFromBootstrapUrl, fetchPlaybackData, fetchTranscriptSearch, getMoviieApiBaseUrl, getMoviieEventsBaseUrl, planRefresh, resetMoviieEndpointsConfiguration };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map