@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-domain/src/accounts.rs

@@ -0,0 +1,181 @@
+//! Account types: users, capability permissions, the public profile-picker
+//! shape and registration invites.
+//!
+//! The JSON shape here is a public contract web/TV clients depend on it, so
+//! field names and casing must not drift.
+
+use serde::{Deserialize, Serialize};
+
+/// A user account. `password_hash` lives only in the DB layer and is never part
+/// of this (serialized) shape, so a `User` is always safe to send to clients.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct User {
+    pub id: String,
+    pub email: String,
+    pub username: String,
+    #[serde(rename = "avatarUrl", skip_serializing_if = "Option::is_none")]
+    pub avatar_url: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub language: Option<String>,
+    // An ISO-639 code; `None` falls back to the file's default track. Independent
+    // of the UI `language` above (you might browse in French, watch in Japanese).
+    #[serde(rename = "audioLanguage", skip_serializing_if = "Option::is_none")]
+    pub audio_language: Option<String>,
+    // An ISO-639 code, or the sentinel `"off"` to force subtitles off; `None` is
+    // no preference.
+    #[serde(rename = "subtitleLanguage", skip_serializing_if = "Option::is_none")]
+    pub subtitle_language: Option<String>,
+    pub permissions: Vec<Permission>,
+    #[serde(rename = "createdAt")]
+    pub created_at: String,
+    #[serde(rename = "hasPin")]
+    pub has_pin: bool,
+}
+
+impl User {
+    /// Whether this user holds a given permission. Gates the invite/admin
+    /// endpoints via `crate::api::users`'s `require`.
+    pub fn can(&self, perm: Permission) -> bool {
+        self.permissions.contains(&perm)
+    }
+
+    /// Whether this user holds ANY management capability (unlocks the admin
+    /// console shell). `requests.manage` counts: a requests moderator needs the
+    /// console for the demandes queue even without user/library/settings rights.
+    pub fn is_any_admin(&self) -> bool {
+        self.can(Permission::UsersManage)
+            || self.can(Permission::LibraryManage)
+            || self.can(Permission::SettingsManage)
+            || self.can(Permission::RequestsManage)
+            || self.can(Permission::ReportsManage)
+    }
+}
+
+/// A granular capability. Stored on each user as a JSON array of the string keys
+/// below. Extend this enum (and the TS mirror in `@kroma/core`) to add more
+/// e.g. a `stats.view` for the upcoming stats pages.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum Permission {
+    #[serde(rename = "users.manage")]
+    UsersManage,
+    #[serde(rename = "library.manage")]
+    LibraryManage,
+    #[serde(rename = "settings.manage")]
+    SettingsManage,
+    #[serde(rename = "playback")]
+    Playback,
+    #[serde(rename = "requests.create")]
+    RequestsCreate,
+    #[serde(rename = "requests.manage")]
+    RequestsManage,
+    #[serde(rename = "requests.auto")]
+    RequestsAuto,
+    #[serde(rename = "reports.manage")]
+    ReportsManage,
+}
+
+impl Permission {
+    /// Parse a stored key; `None` for unknown keys (tolerant forward-compat).
+    pub fn parse(s: &str) -> Option<Permission> {
+        match s {
+            "users.manage" => Some(Permission::UsersManage),
+            "library.manage" => Some(Permission::LibraryManage),
+            "settings.manage" => Some(Permission::SettingsManage),
+            "playback" => Some(Permission::Playback),
+            "requests.create" => Some(Permission::RequestsCreate),
+            "requests.manage" => Some(Permission::RequestsManage),
+            "requests.auto" => Some(Permission::RequestsAuto),
+            "reports.manage" => Some(Permission::ReportsManage),
+            _ => None,
+        }
+    }
+
+    /// Every permission granted to the owner account.
+    pub fn all() -> Vec<Permission> {
+        vec![
+            Permission::UsersManage,
+            Permission::LibraryManage,
+            Permission::SettingsManage,
+            Permission::Playback,
+            Permission::RequestsCreate,
+            Permission::RequestsManage,
+            Permission::RequestsAuto,
+            Permission::ReportsManage,
+        ]
+    }
+}
+
+/// Derive a display role label from a capability set. The backend is
+/// capability-based; this is purely for the admin UI's "Rôle" badge.
+pub fn role_label(perms: &[Permission]) -> &'static str {
+    if perms.contains(&Permission::UsersManage) && perms.contains(&Permission::SettingsManage) {
+        "Propriétaire"
+    } else if perms.contains(&Permission::Playback) {
+        "Membre"
+    } else {
+        "Restreint"
+    }
+}
+
+/// The publicly-listable subset of a user, surfaced by `GET /api/users` to
+/// populate the "Qui regarde ?" profile picker (no email).
+#[derive(Debug, Clone, Serialize)]
+pub struct PublicUser {
+    pub id: String,
+    pub username: String,
+    #[serde(rename = "avatarUrl", skip_serializing_if = "Option::is_none")]
+    pub avatar_url: Option<String>,
+    #[serde(rename = "hasPin")]
+    pub has_pin: bool,
+}
+
+/// A registration invitation created by a user with `users.manage`. After the
+/// bootstrap owner, an invite is the only way to create an account.
+#[derive(Debug, Clone, Serialize)]
+pub struct Invite {
+    pub token: String,
+    pub permissions: Vec<Permission>,
+    #[serde(rename = "createdBy", skip_serializing_if = "Option::is_none")]
+    pub created_by: Option<String>,
+    #[serde(rename = "createdAt")]
+    pub created_at: String,
+    #[serde(rename = "expiresAt")]
+    pub expires_at: i64,
+    pub used: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_permission_parses_back_from_its_stored_key() {
+        for perm in Permission::all() {
+            let stored = serde_json::to_string(&perm).unwrap();
+            let key = stored.trim_matches('"');
+            assert_eq!(Permission::parse(key), Some(perm), "{key}");
+        }
+    }
+
+    #[test]
+    fn an_unknown_permission_key_is_ignored_rather_than_failing_the_account() {
+        assert_eq!(Permission::parse("modules.manage"), None);
+        assert_eq!(Permission::parse(""), None);
+    }
+
+    #[test]
+    fn the_role_badge_follows_the_capability_set() {
+        assert_eq!(role_label(&Permission::all()), "Propriétaire");
+        assert_eq!(
+            role_label(&[Permission::UsersManage, Permission::SettingsManage]),
+            "Propriétaire"
+        );
+        assert_eq!(
+            role_label(&[Permission::Playback, Permission::RequestsCreate]),
+            "Membre"
+        );
+        assert_eq!(role_label(&[Permission::RequestsCreate]), "Restreint");
+        assert_eq!(role_label(&[]), "Restreint");
+        assert_eq!(role_label(&[Permission::UsersManage]), "Restreint");
+    }
+}

package/rust/kroma-domain/src/admin.rs

@@ -0,0 +1,197 @@
+//! Admin-console types: the members table row, per-user watch stats and the
+//! raw history/library aggregates that back the dashboard.
+
+use serde::Serialize;
+
+use crate::accounts::Permission;
+
+/// One account as surfaced to the admin "Membres & partage" table. Unlike
+/// [`User`] this carries the email, a derived role, last-activity and a live
+/// `online` flag (set at request time from the playback registry).
+#[derive(Debug, Clone, Serialize)]
+pub struct AdminUser {
+    pub id: String,
+    pub email: String,
+    pub username: String,
+    #[serde(rename = "avatarUrl", skip_serializing_if = "Option::is_none")]
+    pub avatar_url: Option<String>,
+    pub permissions: Vec<Permission>,
+    pub role: String,
+    #[serde(rename = "createdAt")]
+    pub created_at: String,
+    #[serde(rename = "lastSeen", skip_serializing_if = "Option::is_none")]
+    pub last_seen: Option<String>,
+    pub online: bool,
+    #[serde(rename = "emailVerified")]
+    pub email_verified: bool,
+    #[serde(rename = "hasPin")]
+    pub has_pin: bool,
+    /// The user asked for a credential reset from the sign-in screen and the
+    /// owner has not minted one since.
+    #[serde(rename = "resetRequested")]
+    pub reset_requested: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum WatchKind {
+    Movie,
+    Tv,
+}
+
+impl WatchKind {
+    pub const ALL: [WatchKind; 2] = [WatchKind::Movie, WatchKind::Tv];
+
+    /// The kind a logged play counts under. KROMA's `episode` and `video` both
+    /// land on `tv`, and anything unrecognised counts as a film.
+    pub fn from_media_kind(kind: &str) -> WatchKind {
+        match kind {
+            "episode" | "video" | "tv" => WatchKind::Tv,
+            _ => WatchKind::Movie,
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<WatchKind> {
+        match value {
+            "movie" => Some(WatchKind::Movie),
+            "tv" => Some(WatchKind::Tv),
+            _ => None,
+        }
+    }
+}
+
+/// Milliseconds watched per kind.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
+pub struct WatchTotals {
+    pub movie: i64,
+    pub tv: i64,
+}
+
+impl WatchTotals {
+    pub fn add(&mut self, kind: WatchKind, ms: i64) {
+        match kind {
+            WatchKind::Movie => self.movie += ms,
+            WatchKind::Tv => self.tv += ms,
+        }
+    }
+
+    pub fn get(&self, kind: WatchKind) -> i64 {
+        match kind {
+            WatchKind::Movie => self.movie,
+            WatchKind::Tv => self.tv,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TopUser {
+    pub username: String,
+    pub user_id: Option<String>,
+    pub avatar_url: Option<String>,
+    pub plays: i64,
+    pub watched_ms: i64,
+    pub films_ms: i64,
+    pub tv_ms: i64,
+    pub by_kind: WatchTotals,
+}
+
+/// One finished playback, as it is written to the log. Everything the live
+/// session knew, because the answer to "who watched this, when, and on what"
+/// cannot be reconstructed once the session is reaped.
+#[derive(Debug, Clone, Default)]
+pub struct PlayRecord {
+    pub user_id: Option<String>,
+    pub username: Option<String>,
+    pub item_id: Option<String>,
+    pub kind: String,
+    pub title: String,
+    pub library: Option<String>,
+    pub show_title: Option<String>,
+    pub season: Option<u32>,
+    pub episode: Option<u32>,
+    pub device: Option<String>,
+    pub player: Option<String>,
+    pub mode: Option<String>,
+    pub network: Option<String>,
+    pub video_label: Option<String>,
+    pub audio_label: Option<String>,
+    pub started_at: i64,
+    pub ended_at: i64,
+    pub watched_ms: i64,
+}
+
+/// One row of the admin watch log: a finished playback, read back.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PlayEntry {
+    pub id: String,
+    pub user_id: Option<String>,
+    pub username: String,
+    pub item_id: Option<String>,
+    /// The series an episode belongs to, so a row opens the show rather than one
+    /// episode. None for a film, and for an episode the catalog has lost.
+    pub show_id: Option<String>,
+    /// Whether the title is still in the catalog. The log outlives it, so a row
+    /// can name something there is no longer a page for.
+    pub in_catalog: bool,
+    pub kind: String,
+    pub title: String,
+    pub show_title: Option<String>,
+    pub season: Option<u32>,
+    pub episode: Option<u32>,
+    pub device: Option<String>,
+    pub player: Option<String>,
+    pub mode: Option<String>,
+    pub network: Option<String>,
+    pub video_label: Option<String>,
+    pub audio_label: Option<String>,
+    pub library: Option<String>,
+    pub started_at: i64,
+    pub ended_at: i64,
+    pub watched_ms: i64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct HistoryLibrary {
+    pub id: String,
+    pub name: String,
+}
+
+/// One raw play-history record, bucketed server-side into the "Historique de
+/// lecture" chart.
+#[derive(Debug, Clone)]
+pub struct HistoryRow {
+    pub ended_at: i64,
+    pub kind: WatchKind,
+    pub watched_ms: i64,
+}
+
+/// `viewers` counts distinct accounts. A series is one entry, not one per
+/// episode.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MostWatchedEntry {
+    pub item_id: String,
+    pub title: String,
+    pub kind: WatchKind,
+    pub year: Option<u32>,
+    pub poster_url: Option<String>,
+    pub plays: i64,
+    pub viewers: i64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct MostWatchedColumn {
+    pub kind: WatchKind,
+    pub entries: Vec<MostWatchedEntry>,
+}
+
+/// Per-library aggregate (item count + total bytes on disk) for the storage and
+/// libraries admin pages.
+#[derive(Debug, Clone)]
+pub struct LibraryStat {
+    pub id: String,
+    pub item_count: i64,
+    pub total_bytes: i64,
+}

package/rust/kroma-domain/src/cast.rs

@@ -0,0 +1,178 @@
+//! Cast: the wire vocabulary for driving playback on another device. A TV app
+//! is a **receiver**; a phone or browser is a **sender** acting as its remote.
+//! Pure data, no I/O - the live roster lives in `kroma-engine`'s `services::cast`.
+
+use serde::{Deserialize, Serialize};
+
+use crate::media::MediaItem;
+
+/// `Buffering` is "playing, but stalled" - senders keep the pause button.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum CastState {
+    Idle,
+    Playing,
+    Paused,
+    Buffering,
+    // Anything a newer client invents, so an older server never rejects a
+    // heartbeat it merely doesn't recognize.
+    #[serde(other)]
+    Unknown,
+}
+
+/// A track as *the receiver's* player numbers them: its subtitle list also holds
+/// AI-generated tracks the catalog item never had.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CastTrack {
+    pub index: i64,
+    pub label: String,
+}
+
+/// What a receiver reports about its own playback on each heartbeat.
+#[derive(Debug, Clone, Deserialize)]
+pub struct CastPlayback {
+    #[serde(rename = "itemId")]
+    pub item_id: String,
+    #[serde(rename = "positionMs")]
+    pub position_ms: i64,
+    #[serde(rename = "durationMs", default)]
+    pub duration_ms: Option<i64>,
+    pub state: CastState,
+    #[serde(rename = "audioTracks", default)]
+    pub audio_tracks: Vec<CastTrack>,
+    #[serde(rename = "audioIndex", default)]
+    pub audio_index: Option<i64>,
+    // A `None` subtitle_index means subtitles off.
+    #[serde(default)]
+    pub subtitles: Vec<CastTrack>,
+    #[serde(rename = "subtitleIndex", default)]
+    pub subtitle_index: Option<i64>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct CastNowPlaying {
+    pub item: MediaItem,
+    #[serde(rename = "positionMs")]
+    pub position_ms: i64,
+    #[serde(rename = "durationMs")]
+    pub duration_ms: Option<i64>,
+    pub state: CastState,
+    #[serde(rename = "audioTracks")]
+    pub audio_tracks: Vec<CastTrack>,
+    #[serde(rename = "audioIndex", skip_serializing_if = "Option::is_none")]
+    pub audio_index: Option<i64>,
+    pub subtitles: Vec<CastTrack>,
+    #[serde(rename = "subtitleIndex", skip_serializing_if = "Option::is_none")]
+    pub subtitle_index: Option<i64>,
+}
+
+/// A sender currently driving a receiver. Presence is that sender's socket, so
+/// a device that walks out of the room leaves the list on its own.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct CastController {
+    // Server-minted and socket-scoped, never client-supplied, so one sender
+    // cannot impersonate another in the list a television shows.
+    pub id: String,
+    pub name: String,
+    pub username: String,
+    #[serde(rename = "avatarUrl", skip_serializing_if = "Option::is_none")]
+    pub avatar_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct CastReceiver {
+    pub id: String,
+    pub name: String,
+    pub platform: String,
+    // Deliberately the only identity here: the roster is scoped to the account
+    // the receiver is signed into, so a reader needs no account id or "mine"
+    // flag — everything it is shown is its own.
+    pub username: String,
+    pub network: String,
+    #[serde(rename = "nowPlaying", skip_serializing_if = "Option::is_none")]
+    pub now_playing: Option<CastNowPlaying>,
+    pub controllers: Vec<CastController>,
+}
+
+/// An order from a sender to a receiver. `SkipNext` carries no target on
+/// purpose: resolving it here would race the TV's own idea of "current".
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum CastCommand {
+    Play {
+        #[serde(rename = "itemId")]
+        item_id: String,
+        #[serde(rename = "positionMs", default)]
+        position_ms: i64,
+    },
+    Pause,
+    Resume,
+    TogglePlay,
+    Seek {
+        #[serde(rename = "positionMs")]
+        position_ms: i64,
+    },
+    // Relative jump in milliseconds; negative goes back.
+    Skip {
+        #[serde(rename = "deltaMs")]
+        delta_ms: i64,
+    },
+    SkipNext,
+    Stop,
+    SetAudio {
+        index: usize,
+    },
+    // `null` turns subtitles off.
+    SetSubtitle {
+        index: Option<usize>,
+    },
+}
+
+/// Sequenced so a receiver that gets a command twice (WS push *and* the
+/// heartbeat response) applies it once, and acks it by number.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CastCommandEnvelope {
+    pub seq: u64,
+    pub command: CastCommand,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn commands_round_trip_as_tagged_json() {
+        let play = CastCommand::Play {
+            item_id: "it1".into(),
+            position_ms: 42,
+        };
+        let json = serde_json::to_string(&play).unwrap();
+        assert_eq!(json, r#"{"type":"play","itemId":"it1","positionMs":42}"#);
+        assert_eq!(serde_json::from_str::<CastCommand>(&json).unwrap(), play);
+
+        assert_eq!(
+            serde_json::to_string(&CastCommand::SkipNext).unwrap(),
+            r#"{"type":"skipNext"}"#
+        );
+        assert_eq!(
+            serde_json::from_str::<CastCommand>(r#"{"type":"play","itemId":"x"}"#).unwrap(),
+            CastCommand::Play {
+                item_id: "x".into(),
+                position_ms: 0
+            }
+        );
+        // Subtitles off is an explicit null, not an omission.
+        assert_eq!(
+            serde_json::to_string(&CastCommand::SetSubtitle { index: None }).unwrap(),
+            r#"{"type":"setSubtitle","index":null}"#
+        );
+    }
+
+    #[test]
+    fn an_unknown_state_does_not_fail_a_heartbeat() {
+        let p: CastPlayback =
+            serde_json::from_str(r#"{"itemId":"i","positionMs":1,"state":"levitating"}"#).unwrap();
+        assert_eq!(p.state, CastState::Unknown);
+        assert_eq!(p.duration_ms, None);
+    }
+}

package/rust/kroma-domain/src/crash.rs

@@ -0,0 +1,48 @@
+use serde::{Deserialize, Serialize};
+
+/// `POST /api/diagnostics/crash` body. Sent by a client whose user opted in to
+/// crash reporting; carries a stack trace plus build/device metadata and no
+/// other user data. The server clamps every string and stamps `seq`/`receivedAt`
+/// itself, so a client cannot forge them or grow the store without bound.
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CrashReportBody {
+    pub message: String,
+    #[serde(default)]
+    pub stack: String,
+    pub platform: String,
+    pub captured_at: i64,
+    pub build: CrashBuild,
+    #[serde(default)]
+    pub device: Option<CrashDevice>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CrashBuild {
+    pub version: String,
+    #[serde(default)]
+    pub commit: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CrashDevice {
+    pub model: String,
+    pub os: String,
+}
+
+/// A crash report as stored and returned to admins: the clamped client fields
+/// plus the server-stamped monotonic `seq` and `receivedAt`.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CrashRecord {
+    pub seq: u64,
+    pub received_at: i64,
+    pub message: String,
+    pub stack: String,
+    pub platform: String,
+    pub captured_at: i64,
+    pub build: CrashBuild,
+    pub device: Option<CrashDevice>,
+}