@oddin-gg/havik-player 2.18.0 → 2.20.0

package/dist/index.d.cts

@@ -622,8 +622,30 @@ export declare type FrameToHost = {
     type: 'oddin:error';
     code: PlaybackErrorCode;
     message: string;
+    /** Set with code GEO_DENIED: the viewer's country the server refused (alpha-2). */
+    country?: string;
 };
 
+/**
+ * Whether a fullscreen presentation for `video` can work, by the same
+ * ladder enterVideoFullscreen walks. False means a request is KNOWN to
+ * fail, so the caller should hide its button:
+ *
+ *  - the element API exists on `container` (or the video) but the document
+ *    reports `fullscreenEnabled === false` — the Fullscreen spec sets that
+ *    exactly when permissions policy blocks the feature, which is what a
+ *    cross-origin iframe without `fullscreen` in its `allow` list looks
+ *    like (prefixed `webkitFullscreenEnabled` on older Safari);
+ *  - no element API at all, media already loaded, and the video does not
+ *    offer the video-native presentation either (a webview with nothing).
+ *
+ * True otherwise — including "not known yet": with no element API and
+ * media not loaded (iPhone before the first play) the video-native flag
+ * is not readable, so the answer stays optimistic. Re-check on
+ * `loadedmetadata`; the managed control bar does.
+ */
+export declare function fullscreenSupported(video: HTMLVideoElement, container?: HTMLElement): boolean;
+
 export declare function getDeviceId(): string;
 
 /**
@@ -852,10 +874,15 @@ export declare class PlaybackError extends Error {
      * far-future matches.
      */
     readonly liveStartsAtMs?: number;
+    /**
+     * Set for GEO_DENIED: the viewer's country the server refused, as an
+     * upper-case ISO 3166-1 alpha-2 tag (e.g. "RU"). Absent on every other code.
+     */
+    readonly country?: string;
     constructor(code: PlaybackErrorCode, httpStatus: number, message: string, init?: PlaybackErrorInit);
 }
 
-export declare type PlaybackErrorCode = 'INVALID_URN' | 'NOT_FOUND' | 'GONE' | 'TOO_EARLY' | 'UNAVAILABLE' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'DRM_CLIENT' | 'RATE_LIMITED' | 'INTERNAL' | 'NETWORK' | 'TIMEOUT' | 'ABORTED';
+export declare type PlaybackErrorCode = 'INVALID_URN' | 'NOT_FOUND' | 'GEO_DENIED' | 'GONE' | 'TOO_EARLY' | 'UNAVAILABLE' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'DRM_CLIENT' | 'RATE_LIMITED' | 'INTERNAL' | 'NETWORK' | 'TIMEOUT' | 'ABORTED';
 
 export declare interface PlaybackErrorInit {
     retryAfterMs?: number;
@@ -868,6 +895,11 @@ export declare interface PlaybackErrorInit {
      * matches without a separate catalog call.
      */
     liveStartsAtMs?: number;
+    /**
+     * The viewer's country as the server saw it (upper-case ISO 3166-1 alpha-2),
+     * carried on a GEO_DENIED body so the player can name it.
+     */
+    country?: string;
     cause?: unknown;
 }
 
@@ -997,6 +1029,14 @@ export declare interface Player {
     enterFullscreen(): Promise<boolean>;
     /** Leave fullscreen (element or video-native). Safe when not fullscreen. */
     exitFullscreen(): Promise<void>;
+    /**
+     * Whether enterFullscreen can work here: false when the page's permissions
+     * policy blocks fullscreen (an iframe without `fullscreen` in `allow`) or
+     * the platform has no mechanism, so a custom UI can hide its button. Stays
+     * true before media loads on iPhone (not knowable yet); re-check on the
+     * video's `loadedmetadata`.
+     */
+    fullscreenSupported(): boolean;
     /** Retry playback after an error (re-resolves and re-attaches). */
     retry(): Promise<void>;
     /** Re-resolve playback (refreshes the signed license URL) and re-attach. */
@@ -1300,7 +1340,7 @@ export declare interface WatchStatusOptions {
     onChange: (status: MatchStatus) => void;
     /**
      * Fired on a poll error. Polling continues, except after a terminal answer
-     * about the URN itself (`NOT_FOUND`, `GONE`, `INVALID_URN`): the watcher
+     * about the URN itself (`NOT_FOUND`, `GONE`, `GEO_DENIED`, `INVALID_URN`): the watcher
      * stops on its own and this is the last call it makes.
      */
     onError?: (err: PlaybackError) => void;

package/dist/index.d.ts

@@ -622,8 +622,30 @@ export declare type FrameToHost = {
     type: 'oddin:error';
     code: PlaybackErrorCode;
     message: string;
+    /** Set with code GEO_DENIED: the viewer's country the server refused (alpha-2). */
+    country?: string;
 };
 
+/**
+ * Whether a fullscreen presentation for `video` can work, by the same
+ * ladder enterVideoFullscreen walks. False means a request is KNOWN to
+ * fail, so the caller should hide its button:
+ *
+ *  - the element API exists on `container` (or the video) but the document
+ *    reports `fullscreenEnabled === false` — the Fullscreen spec sets that
+ *    exactly when permissions policy blocks the feature, which is what a
+ *    cross-origin iframe without `fullscreen` in its `allow` list looks
+ *    like (prefixed `webkitFullscreenEnabled` on older Safari);
+ *  - no element API at all, media already loaded, and the video does not
+ *    offer the video-native presentation either (a webview with nothing).
+ *
+ * True otherwise — including "not known yet": with no element API and
+ * media not loaded (iPhone before the first play) the video-native flag
+ * is not readable, so the answer stays optimistic. Re-check on
+ * `loadedmetadata`; the managed control bar does.
+ */
+export declare function fullscreenSupported(video: HTMLVideoElement, container?: HTMLElement): boolean;
+
 export declare function getDeviceId(): string;
 
 /**
@@ -852,10 +874,15 @@ export declare class PlaybackError extends Error {
      * far-future matches.
      */
     readonly liveStartsAtMs?: number;
+    /**
+     * Set for GEO_DENIED: the viewer's country the server refused, as an
+     * upper-case ISO 3166-1 alpha-2 tag (e.g. "RU"). Absent on every other code.
+     */
+    readonly country?: string;
     constructor(code: PlaybackErrorCode, httpStatus: number, message: string, init?: PlaybackErrorInit);
 }
 
-export declare type PlaybackErrorCode = 'INVALID_URN' | 'NOT_FOUND' | 'GONE' | 'TOO_EARLY' | 'UNAVAILABLE' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'DRM_CLIENT' | 'RATE_LIMITED' | 'INTERNAL' | 'NETWORK' | 'TIMEOUT' | 'ABORTED';
+export declare type PlaybackErrorCode = 'INVALID_URN' | 'NOT_FOUND' | 'GEO_DENIED' | 'GONE' | 'TOO_EARLY' | 'UNAVAILABLE' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'DRM_CLIENT' | 'RATE_LIMITED' | 'INTERNAL' | 'NETWORK' | 'TIMEOUT' | 'ABORTED';
 
 export declare interface PlaybackErrorInit {
     retryAfterMs?: number;
@@ -868,6 +895,11 @@ export declare interface PlaybackErrorInit {
      * matches without a separate catalog call.
      */
     liveStartsAtMs?: number;
+    /**
+     * The viewer's country as the server saw it (upper-case ISO 3166-1 alpha-2),
+     * carried on a GEO_DENIED body so the player can name it.
+     */
+    country?: string;
     cause?: unknown;
 }
 
@@ -997,6 +1029,14 @@ export declare interface Player {
     enterFullscreen(): Promise<boolean>;
     /** Leave fullscreen (element or video-native). Safe when not fullscreen. */
     exitFullscreen(): Promise<void>;
+    /**
+     * Whether enterFullscreen can work here: false when the page's permissions
+     * policy blocks fullscreen (an iframe without `fullscreen` in `allow`) or
+     * the platform has no mechanism, so a custom UI can hide its button. Stays
+     * true before media loads on iPhone (not knowable yet); re-check on the
+     * video's `loadedmetadata`.
+     */
+    fullscreenSupported(): boolean;
     /** Retry playback after an error (re-resolves and re-attaches). */
     retry(): Promise<void>;
     /** Re-resolve playback (refreshes the signed license URL) and re-attach. */
@@ -1300,7 +1340,7 @@ export declare interface WatchStatusOptions {
     onChange: (status: MatchStatus) => void;
     /**
      * Fired on a poll error. Polling continues, except after a terminal answer
-     * about the URN itself (`NOT_FOUND`, `GONE`, `INVALID_URN`): the watcher
+     * about the URN itself (`NOT_FOUND`, `GONE`, `GEO_DENIED`, `INVALID_URN`): the watcher
      * stops on its own and this is the last call it makes.
      */
     onError?: (err: PlaybackError) => void;