@kromatv/sdk 0.1.40-canary.0

package/types/client/src/api/playback/client.d.ts

@@ -0,0 +1,681 @@
+import { z } from 'zod';
+import type { RequestContext } from '../../core/client';
+import { ItemId, ShowId, type SubjectId } from '../media';
+import type { PlaybackSessionId } from './ids';
+import type { PlaybackPing } from './schemas';
+/** Playback progress, resume rails and live-session heartbeats. */
+export default function playbackApi(ctx: RequestContext): {
+    /** All of the user's saved positions. */
+    progress: () => Promise<{
+        positionMs: number;
+        durationMs: number | null;
+        updatedAt: string;
+        itemId: string & z.$brand<"ItemId">;
+    }[]>;
+    /** Saved position for a single item, or null if none. */
+    itemProgress: (itemId: ItemId) => Promise<{
+        positionMs: number;
+        durationMs: number | null;
+        updatedAt: string;
+        itemId: string & z.$brand<"ItemId">;
+    } | null>;
+    /** Save (upsert) the playback position for an item. */
+    save: (itemId: ItemId, positionMs: number, durationMs?: number | null) => Promise<void>;
+    /** Forget an item's position (finished / removed from Continue Watching). */
+    forget: (itemId: ItemId) => Promise<void>;
+    /** Resumable items, newest first (the "Reprendre la lecture" rail). */
+    continueWatching: () => Promise<{
+        positionMs: number;
+        durationMs: number | null;
+        updatedAt: string;
+        item: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            title: string;
+            year: number | null;
+            library: string & z.$brand<"LibraryId">;
+            addedAt: string;
+            metadata?: {
+                provider: string;
+                tmdbId: number;
+                imdbId?: string | null | undefined;
+                title: string | null;
+                tagline?: string | null | undefined;
+                overview: string | null;
+                releaseDate?: string | null | undefined;
+                genres: string[];
+                tmdbGenreIds?: number[] | null | undefined;
+                rating?: number | null | undefined;
+                certification?: string | null | undefined;
+                posterUrl?: string | null | undefined;
+                backdropUrl?: string | null | undefined;
+                logoUrl?: string | null | undefined;
+                themeUrl?: string | null | undefined;
+                cast?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    character?: string | null | undefined;
+                }[] | null | undefined;
+                crew?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    job: string;
+                }[] | null | undefined;
+                tmdbUrl: string;
+            } | null | undefined;
+            id: string & z.$brand<"ItemId">;
+            kind: "episode" | "movie" | "video";
+            showId: (string & z.$brand<"ShowId">) | null;
+            showTitle: string | null;
+            season: number | null;
+            episode: number | null;
+            episodeEnd: number | null;
+            episodeTitle: string | null;
+            files: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                id: string & z.$brand<"MediaFileId">;
+                size: number | null;
+                edition?: string | null | undefined;
+                probed: boolean;
+            }[];
+            defaultFileId?: (string & z.$brand<"MediaFileId">) | null | undefined;
+            markers?: {
+                kind: "credits" | "intro";
+                startMs: number;
+                endMs: number;
+            }[] | null | undefined;
+            audioAnalysis?: {
+                lufsI: number;
+                lra: number;
+                truePeak: number;
+                dialogLufs?: number | null | undefined;
+                verdict: "highDynamics" | "ok" | "quietDialog";
+            } | null | undefined;
+        };
+    }[]>;
+    /** The episode to play to CONTINUE a show (resume in-progress, else next
+     * unwatched, else first) plus a `resume` flag for the button label. `null`
+     * when the show has no episodes. */
+    upNext: (showId: ShowId) => Promise<{
+        item: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            title: string;
+            year: number | null;
+            library: string & z.$brand<"LibraryId">;
+            addedAt: string;
+            metadata?: {
+                provider: string;
+                tmdbId: number;
+                imdbId?: string | null | undefined;
+                title: string | null;
+                tagline?: string | null | undefined;
+                overview: string | null;
+                releaseDate?: string | null | undefined;
+                genres: string[];
+                tmdbGenreIds?: number[] | null | undefined;
+                rating?: number | null | undefined;
+                certification?: string | null | undefined;
+                posterUrl?: string | null | undefined;
+                backdropUrl?: string | null | undefined;
+                logoUrl?: string | null | undefined;
+                themeUrl?: string | null | undefined;
+                cast?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    character?: string | null | undefined;
+                }[] | null | undefined;
+                crew?: {
+                    name: string;
+                    tmdbId?: number | null | undefined;
+                    profileUrl?: string | null | undefined;
+                    job: string;
+                }[] | null | undefined;
+                tmdbUrl: string;
+            } | null | undefined;
+            id: string & z.$brand<"ItemId">;
+            kind: "episode" | "movie" | "video";
+            showId: (string & z.$brand<"ShowId">) | null;
+            showTitle: string | null;
+            season: number | null;
+            episode: number | null;
+            episodeEnd: number | null;
+            episodeTitle: string | null;
+            files: {
+                container: string;
+                durationMs: number | null;
+                relPath: string | null;
+                video: {
+                    codec: string;
+                    width: number | null;
+                    height: number | null;
+                    hdr: boolean;
+                    bitDepth: number | null;
+                } | null;
+                audio: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                } | null;
+                audioTracks: {
+                    index: number;
+                    codec: string;
+                    channels: number | null;
+                    language: string | null;
+                    title?: string | null | undefined;
+                    default: boolean;
+                }[];
+                subtitles: {
+                    language: string | null;
+                    codec: string;
+                }[];
+                id: string & z.$brand<"MediaFileId">;
+                size: number | null;
+                edition?: string | null | undefined;
+                probed: boolean;
+            }[];
+            defaultFileId?: (string & z.$brand<"MediaFileId">) | null | undefined;
+            markers?: {
+                kind: "credits" | "intro";
+                startMs: number;
+                endMs: number;
+            }[] | null | undefined;
+            audioAnalysis?: {
+                lufsI: number;
+                lra: number;
+                truePeak: number;
+                dialogLufs?: number | null | undefined;
+                verdict: "highDynamics" | "ok" | "quietDialog";
+            } | null | undefined;
+        };
+        resume: boolean;
+    } | null>;
+    /** The next episode after `itemId` in its show, or `null` for a movie / the
+     * last episode. Drives player autoplay. */
+    nextEpisode: (itemId: ItemId) => Promise<{
+        container: string;
+        durationMs: number | null;
+        relPath: string | null;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        audio: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        } | null;
+        audioTracks: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        }[];
+        subtitles: {
+            language: string | null;
+            codec: string;
+        }[];
+        title: string;
+        year: number | null;
+        library: string & z.$brand<"LibraryId">;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & z.$brand<"ItemId">;
+        kind: "episode" | "movie" | "video";
+        showId: (string & z.$brand<"ShowId">) | null;
+        showTitle: string | null;
+        season: number | null;
+        episode: number | null;
+        episodeEnd: number | null;
+        episodeTitle: string | null;
+        files: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            id: string & z.$brand<"MediaFileId">;
+            size: number | null;
+            edition?: string | null | undefined;
+            probed: boolean;
+        }[];
+        defaultFileId?: (string & z.$brand<"MediaFileId">) | null | undefined;
+        markers?: {
+            kind: "credits" | "intro";
+            startMs: number;
+            endMs: number;
+        }[] | null | undefined;
+        audioAnalysis?: {
+            lufsI: number;
+            lra: number;
+            truePeak: number;
+            dialogLufs?: number | null | undefined;
+            verdict: "highDynamics" | "ok" | "quietDialog";
+        } | null | undefined;
+    } | null>;
+    /** The upcoming episodes after `itemId`, for the player's "up next" rail.
+     * Empty for a movie / the last episode. */
+    following: (itemId: ItemId) => Promise<{
+        container: string;
+        durationMs: number | null;
+        relPath: string | null;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        audio: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        } | null;
+        audioTracks: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        }[];
+        subtitles: {
+            language: string | null;
+            codec: string;
+        }[];
+        title: string;
+        year: number | null;
+        library: string & z.$brand<"LibraryId">;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & z.$brand<"ItemId">;
+        kind: "episode" | "movie" | "video";
+        showId: (string & z.$brand<"ShowId">) | null;
+        showTitle: string | null;
+        season: number | null;
+        episode: number | null;
+        episodeEnd: number | null;
+        episodeTitle: string | null;
+        files: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            id: string & z.$brand<"MediaFileId">;
+            size: number | null;
+            edition?: string | null | undefined;
+            probed: boolean;
+        }[];
+        defaultFileId?: (string & z.$brand<"MediaFileId">) | null | undefined;
+        markers?: {
+            kind: "credits" | "intro";
+            startMs: number;
+            endMs: number;
+        }[] | null | undefined;
+        audioAnalysis?: {
+            lufsI: number;
+            lra: number;
+            truePeak: number;
+            dialogLufs?: number | null | undefined;
+            verdict: "highDynamics" | "ok" | "quietDialog";
+        } | null | undefined;
+    }[]>;
+    /** Personalized "For You" picks from the watch history (Bearer). Empty until
+     * the account has watched something embeddable. */
+    forYou: () => Promise<{
+        container: string;
+        durationMs: number | null;
+        relPath: string | null;
+        video: {
+            codec: string;
+            width: number | null;
+            height: number | null;
+            hdr: boolean;
+            bitDepth: number | null;
+        } | null;
+        audio: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        } | null;
+        audioTracks: {
+            index: number;
+            codec: string;
+            channels: number | null;
+            language: string | null;
+            title?: string | null | undefined;
+            default: boolean;
+        }[];
+        subtitles: {
+            language: string | null;
+            codec: string;
+        }[];
+        title: string;
+        year: number | null;
+        library: string & z.$brand<"LibraryId">;
+        addedAt: string;
+        metadata?: {
+            provider: string;
+            tmdbId: number;
+            imdbId?: string | null | undefined;
+            title: string | null;
+            tagline?: string | null | undefined;
+            overview: string | null;
+            releaseDate?: string | null | undefined;
+            genres: string[];
+            tmdbGenreIds?: number[] | null | undefined;
+            rating?: number | null | undefined;
+            certification?: string | null | undefined;
+            posterUrl?: string | null | undefined;
+            backdropUrl?: string | null | undefined;
+            logoUrl?: string | null | undefined;
+            themeUrl?: string | null | undefined;
+            cast?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                character?: string | null | undefined;
+            }[] | null | undefined;
+            crew?: {
+                name: string;
+                tmdbId?: number | null | undefined;
+                profileUrl?: string | null | undefined;
+                job: string;
+            }[] | null | undefined;
+            tmdbUrl: string;
+        } | null | undefined;
+        id: string & z.$brand<"ItemId">;
+        kind: "episode" | "movie" | "video";
+        showId: (string & z.$brand<"ShowId">) | null;
+        showTitle: string | null;
+        season: number | null;
+        episode: number | null;
+        episodeEnd: number | null;
+        episodeTitle: string | null;
+        files: {
+            container: string;
+            durationMs: number | null;
+            relPath: string | null;
+            video: {
+                codec: string;
+                width: number | null;
+                height: number | null;
+                hdr: boolean;
+                bitDepth: number | null;
+            } | null;
+            audio: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            } | null;
+            audioTracks: {
+                index: number;
+                codec: string;
+                channels: number | null;
+                language: string | null;
+                title?: string | null | undefined;
+                default: boolean;
+            }[];
+            subtitles: {
+                language: string | null;
+                codec: string;
+            }[];
+            id: string & z.$brand<"MediaFileId">;
+            size: number | null;
+            edition?: string | null | undefined;
+            probed: boolean;
+        }[];
+        defaultFileId?: (string & z.$brand<"MediaFileId">) | null | undefined;
+        markers?: {
+            kind: "credits" | "intro";
+            startMs: number;
+            endMs: number;
+        }[] | null | undefined;
+        audioAnalysis?: {
+            lufsI: number;
+            lra: number;
+            truePeak: number;
+            dialogLufs?: number | null | undefined;
+            verdict: "highDynamics" | "ok" | "quietDialog";
+        } | null | undefined;
+    }[]>;
+    /** Item ids the user has marked (or finished) as watched. Clients hydrate
+     * this into a set once and badge cards from it. */
+    watched: () => Promise<(string & z.$brand<"ItemId">)[]>;
+    /** Mark an item as watched (also clears its resume position). */
+    markWatched: (itemId: ItemId) => Promise<void>;
+    /** Clear an item's watched flag. */
+    unmarkWatched: (itemId: ItemId) => Promise<void>;
+    /** Item AND show ids in the user's "Ma liste", newest first. */
+    myList: () => Promise<((string & z.$brand<"ItemId">) | (string & z.$brand<"ShowId">))[]>;
+    /** Add a title to the user's list. */
+    addToList: (id: SubjectId) => Promise<void>;
+    /** Remove a title from the user's list. */
+    removeFromList: (id: SubjectId) => Promise<void>;
+    /** Report playback state so the admin dashboard can show a live session. */
+    ping: (ping: PlaybackPing) => Promise<void>;
+    /** End a playback session (logs it to history immediately). */
+    stop: (sessionId: PlaybackSessionId) => Promise<void>;
+};
+declare module '../../core/client' {
+    interface Domains {
+        playback: ReturnType<typeof playbackApi>;
+    }
+}

package/types/client/src/api/playback/ids.d.ts

@@ -0,0 +1,3 @@
+import type { z } from 'zod';
+export declare const PlaybackSessionId: z.core.$ZodBranded<z.ZodString, "PlaybackSessionId", "out">;
+export type PlaybackSessionId = z.infer<typeof PlaybackSessionId>;

package/types/client/src/api/playback/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './ids';
+export * from './schemas';