@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-domain/src/notifications/param.rs

@@ -0,0 +1,90 @@
+//! One interpolation variable on a notification.
+
+use serde::{Deserialize, Serialize};
+
+/// One interpolation variable on a notification. Producers tag which kind they
+/// mean, so user-controlled text that collides with a catalog key is never
+/// silently translated.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(tag = "kind", content = "value", rename_all = "lowercase")]
+pub enum ParamValue {
+    Text(String),
+    Key(String),
+    // A bare string from a row written before params were typed, where a key
+    // and a literal were the same thing on the wire. It stays ambiguous on
+    // purpose: resolved only when it names a REAL catalog entry, and only for
+    // these old rows. See `services::notify::render`.
+    Legacy(String),
+}
+
+impl ParamValue {
+    /// `translate` answers `None` for a string the catalogs do not know, which
+    /// lets [`ParamValue::Legacy`] fall back to its own literal text while
+    /// [`ParamValue::Key`] keeps the key visible rather than rendering blank.
+    pub fn resolve(&self, translate: impl FnOnce(&str) -> Option<String>) -> String {
+        match self {
+            ParamValue::Text(text) => text.clone(),
+            ParamValue::Key(key) => translate(key).unwrap_or_else(|| key.clone()),
+            ParamValue::Legacy(text) => translate(text).unwrap_or_else(|| text.clone()),
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for ParamValue {
+    // Accepts the tagged form AND a bare string: without the latter an existing
+    // row's whole `params` map fails to parse and renders unsubstituted.
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        #[derive(Deserialize)]
+        #[serde(untagged)]
+        enum Raw {
+            Tagged { kind: String, value: String },
+            Legacy(String),
+        }
+        Ok(match Raw::deserialize(deserializer)? {
+            Raw::Tagged { kind, value } if kind == "key" => ParamValue::Key(value),
+            Raw::Tagged { value, .. } => ParamValue::Text(value),
+            Raw::Legacy(text) => ParamValue::Legacy(text),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::BTreeMap;
+
+    use super::*;
+
+    #[test]
+    fn a_param_round_trips_and_still_reads_the_legacy_bare_string() {
+        let typed = serde_json::to_string(&ParamValue::Key("jobs.x.name".into())).unwrap();
+        assert_eq!(typed, r#"{"kind":"key","value":"jobs.x.name"}"#);
+        assert_eq!(
+            serde_json::from_str::<ParamValue>(&typed).unwrap(),
+            ParamValue::Key("jobs.x.name".into())
+        );
+
+        // Bare strings predate typed params and read back as `Legacy`.
+        assert_eq!(
+            serde_json::from_str::<ParamValue>(r#""Dune""#).unwrap(),
+            ParamValue::Legacy("Dune".into())
+        );
+        let legacy: BTreeMap<String, ParamValue> =
+            serde_json::from_str(r#"{"title":"Dune","job":"jobs.library.scan.name"}"#).unwrap();
+        assert_eq!(
+            legacy.get("title"),
+            Some(&ParamValue::Legacy("Dune".into()))
+        );
+        assert_eq!(
+            legacy.get("job"),
+            Some(&ParamValue::Legacy("jobs.library.scan.name".into()))
+        );
+
+        assert_eq!(
+            serde_json::from_str::<ParamValue>(
+                r#"{"kind":"text","value":"jobs.library.scan.name"}"#
+            )
+            .unwrap(),
+            ParamValue::Text("jobs.library.scan.name".into())
+        );
+    }
+}

package/rust/kroma-domain/src/notifications/spec.rs

@@ -0,0 +1,178 @@
+//! What a producer hands to the notify service: keys, not text.
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::push::PushCategory;
+
+use super::action::ActionSpec;
+use super::event::{NotificationCategory, NotificationEvent};
+use super::param::ParamValue;
+
+/// What a producer hands to `services::notify::emit`: keys, not text. Also the
+/// payload a module posts to the host's callback API.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotificationSpec {
+    pub event: NotificationEvent,
+    pub title_key: String,
+    pub body_key: String,
+    #[serde(default)]
+    pub params: BTreeMap<String, ParamValue>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub link: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub image_url: Option<String>,
+    #[serde(default)]
+    pub actions: Vec<ActionSpec>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub push_category: Option<PushCategory>,
+    // Only a `NotificationEvent::Custom` may set this; a core event's category
+    // is not the producer's to override.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub category: Option<NotificationCategory>,
+}
+
+impl NotificationSpec {
+    pub fn new(event: NotificationEvent, title_key: &str, body_key: &str) -> Self {
+        Self {
+            event,
+            title_key: title_key.to_string(),
+            body_key: body_key.to_string(),
+            params: BTreeMap::new(),
+            link: None,
+            image_url: None,
+            actions: Vec::new(),
+            push_category: None,
+            category: None,
+        }
+    }
+
+    /// Text a module supplies itself, rather than a key the core can translate.
+    /// The server-side renderer does not load module catalogs, so the module's
+    /// wording rides in as params through a passthrough key.
+    pub fn custom(
+        category: NotificationCategory,
+        title: impl Into<String>,
+        body: impl Into<String>,
+    ) -> Self {
+        Self::new(
+            NotificationEvent::Custom,
+            "notifications.custom.title",
+            "notifications.custom.body",
+        )
+        .param("title", title)
+        .param("body", body)
+        .in_category(category)
+    }
+
+    /// A literal interpolation var. Never translated, however much it may look
+    /// like a catalog key.
+    pub fn param(mut self, key: &str, value: impl Into<String>) -> Self {
+        self.params
+            .insert(key.to_string(), ParamValue::Text(value.into()));
+        self
+    }
+
+    /// An interpolation var that is itself an i18n key, resolved in the reader's
+    /// locale (a job's `jobs.{key}.name`).
+    pub fn param_key(mut self, key: &str, message_key: impl Into<String>) -> Self {
+        self.params
+            .insert(key.to_string(), ParamValue::Key(message_key.into()));
+        self
+    }
+
+    pub fn link(mut self, href: impl Into<String>) -> Self {
+        self.link = Some(href.into());
+        self
+    }
+
+    pub fn image(mut self, url: Option<String>) -> Self {
+        self.image_url = url;
+        self
+    }
+
+    pub fn action(mut self, action: ActionSpec) -> Self {
+        self.actions.push(action);
+        self
+    }
+
+    pub fn push_category(mut self, category: PushCategory) -> Self {
+        self.push_category = Some(category);
+        self
+    }
+
+    /// State the preference bucket for a [`NotificationEvent::Custom`].
+    /// Deliberately ignored for the core's own events.
+    pub fn in_category(mut self, category: NotificationCategory) -> Self {
+        self.category = Some(category);
+        self
+    }
+
+    pub fn category(&self) -> NotificationCategory {
+        match self.event {
+            NotificationEvent::Custom => self.category.unwrap_or(NotificationCategory::System),
+            core => core.category(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::notifications::{ActionKind, ActionStyle};
+
+    #[test]
+    fn param_marks_text_and_param_key_marks_a_key() {
+        let spec = NotificationSpec::new(
+            NotificationEvent::SystemJobFailed,
+            "notifications.system.job.failed.title",
+            "notifications.system.job.failed.body",
+        )
+        .param("who", "library.scan")
+        .param_key("job", "jobs.library.scan.name");
+
+        assert_eq!(
+            spec.params.get("who"),
+            Some(&ParamValue::Text("library.scan".into()))
+        );
+        assert_eq!(
+            spec.params.get("job"),
+            Some(&ParamValue::Key("jobs.library.scan.name".into()))
+        );
+    }
+    #[test]
+    fn spec_builders_accumulate_without_clobbering() {
+        let spec = NotificationSpec::new(
+            NotificationEvent::RequestAvailable,
+            "notifications.request.available.title",
+            "notifications.request.available.body",
+        )
+        .param("title", "Dune")
+        .param("year", "2021")
+        .link("/movie/ab12")
+        .image(Some("https://img/x.jpg".into()))
+        .push_category(PushCategory::MediaAvailable)
+        .action(ActionSpec {
+            id: "watch".into(),
+            label_key: "notifications.action.watch".into(),
+            kind: ActionKind::Link,
+            href: "/watch/ab12".into(),
+            method: None,
+            style: ActionStyle::Primary,
+        });
+
+        assert_eq!(
+            spec.params.get("title"),
+            Some(&ParamValue::Text("Dune".into()))
+        );
+        assert_eq!(
+            spec.params.get("year"),
+            Some(&ParamValue::Text("2021".into()))
+        );
+        assert_eq!(spec.category(), NotificationCategory::Requests);
+        assert_eq!(spec.actions.len(), 1);
+        assert_eq!(spec.push_category, Some(PushCategory::MediaAvailable));
+    }
+}

package/rust/kroma-domain/src/notifications/view.rs

@@ -0,0 +1,55 @@
+//! One notification as a client sees it, plus the per-category delivery matrix.
+
+use serde::{Deserialize, Serialize};
+
+use crate::push::PushCategory;
+
+use super::action::NotificationAction;
+use super::event::{NotificationCategory, NotificationEvent};
+
+/// One notification as a client sees it: fully rendered in the reader's locale.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Notification {
+    pub id: String,
+    pub category: NotificationCategory,
+    pub event: NotificationEvent,
+    pub title: String,
+    pub body: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub link: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub image_url: Option<String>,
+    pub actions: Vec<NotificationAction>,
+    // APNs and Android can only show buttons from a set the app registered at
+    // launch, so this names one. Ignored by the web client, which uses `actions`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub push_category: Option<PushCategory>,
+    pub read: bool,
+    pub created_at: i64,
+}
+
+/// `GET /api/notifications`.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotificationsView {
+    pub notifications: Vec<Notification>,
+    pub unread: u32,
+}
+
+/// One row of the per-category delivery matrix. A missing DB row means "on", so
+/// a new category starts enabled without a migration touching every user.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CategoryPref {
+    pub category: NotificationCategory,
+    pub in_app: bool,
+    pub push: bool,
+}
+
+/// `GET`/`PUT /api/notifications/prefs`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotificationPrefs {
+    pub categories: Vec<CategoryPref>,
+}

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

@@ -0,0 +1,286 @@
+use std::cmp::Reverse;
+use std::collections::{BTreeMap, BTreeSet};
+
+use crate::slug::{slug_eq, slugify};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum CreditedTitle {
+    Movie(String),
+    Show(String),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Credit {
+    pub name: String,
+    // None on every credit stored before the id was kept: those fold by name.
+    pub tmdb_id: Option<u64>,
+    pub title: CreditedTitle,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct PersonMatch {
+    pub name: String,
+    pub tmdb_id: Option<u64>,
+    pub movie_ids: Vec<String>,
+    pub show_ids: Vec<String>,
+    pub namesakes: Vec<String>,
+}
+
+/// Resolve `lookup`, a provider person id, a URL slug, or a display name in any
+/// casing, against the credits a library holds. `None` when nothing is credited
+/// under it.
+///
+/// An id answers exactly, whatever the credits spell the person: it is the only
+/// thing that tells two people credited under one name apart. Credits stored
+/// before the id was kept have none, so a lookup that matches no id falls back
+/// to folding the name, and there several SPELLINGS can share one slug. The one
+/// credited on more titles then wins, alphabetically first on a tie, and the
+/// rest come back as `namesakes`.
+pub fn resolve_person(
+    credits: impl IntoIterator<Item = Credit>,
+    lookup: &str,
+) -> Option<PersonMatch> {
+    let credits: Vec<Credit> = credits.into_iter().collect();
+    lookup
+        .parse::<u64>()
+        .ok()
+        .and_then(|id| by_provider_id(&credits, id))
+        .or_else(|| by_folded_name(&credits, lookup))
+}
+
+fn by_provider_id(credits: &[Credit], id: u64) -> Option<PersonMatch> {
+    let spellings = group_by_spelling(credits.iter().filter(|c| c.tmdb_id == Some(id)));
+    let name = most_credited_then_alphabetical(&spellings)?.clone();
+    let mut all = Titles::default();
+    for titles in spellings.into_values() {
+        all.absorb(titles);
+    }
+    Some(all.into_match(name, Some(id), Vec::new()))
+}
+
+fn by_folded_name(credits: &[Credit], lookup: &str) -> Option<PersonMatch> {
+    let want = slugify(lookup);
+    if want.is_empty() {
+        return None;
+    }
+    let mut spellings = group_by_spelling(credits.iter().filter(|c| slug_eq(&c.name, &want)));
+    let name = most_credited_then_alphabetical(&spellings)?.clone();
+    let titles = spellings.remove(&name).unwrap_or_default();
+    let id = titles.lone_id();
+    Some(titles.into_match(name, id, spellings.into_keys().collect()))
+}
+
+fn group_by_spelling<'a>(credits: impl Iterator<Item = &'a Credit>) -> BTreeMap<String, Titles> {
+    let mut spellings: BTreeMap<String, Titles> = BTreeMap::new();
+    for credit in credits {
+        spellings
+            .entry(credit.name.clone())
+            .or_default()
+            .add(credit);
+    }
+    spellings
+}
+
+// A BTreeMap iterates in name order and `min_by_key` keeps the first of equal
+// keys, which is together what makes the alphabetical tie-break deterministic.
+fn most_credited_then_alphabetical(spellings: &BTreeMap<String, Titles>) -> Option<&String> {
+    spellings
+        .iter()
+        .min_by_key(|(_, titles)| Reverse(titles.count()))
+        .map(|(name, _)| name)
+}
+
+#[derive(Default)]
+struct Titles {
+    movies: BTreeSet<String>,
+    shows: BTreeSet<String>,
+    ids: BTreeSet<u64>,
+}
+
+impl Titles {
+    fn add(&mut self, credit: &Credit) {
+        match &credit.title {
+            CreditedTitle::Movie(id) => self.movies.insert(id.clone()),
+            CreditedTitle::Show(id) => self.shows.insert(id.clone()),
+        };
+        if let Some(id) = credit.tmdb_id {
+            self.ids.insert(id);
+        }
+    }
+
+    fn absorb(&mut self, other: Titles) {
+        self.movies.extend(other.movies);
+        self.shows.extend(other.shows);
+        self.ids.extend(other.ids);
+    }
+
+    fn count(&self) -> usize {
+        self.movies.len() + self.shows.len()
+    }
+
+    // Two ids under one spelling are two people the fold cannot separate, so the
+    // answer carries neither.
+    fn lone_id(&self) -> Option<u64> {
+        match self.ids.len() {
+            1 => self.ids.iter().next().copied(),
+            _ => None,
+        }
+    }
+
+    fn into_match(self, name: String, tmdb_id: Option<u64>, namesakes: Vec<String>) -> PersonMatch {
+        PersonMatch {
+            name,
+            tmdb_id,
+            movie_ids: self.movies.into_iter().collect(),
+            show_ids: self.shows.into_iter().collect(),
+            namesakes,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn movie(name: &str, id: &str) -> Credit {
+        Credit {
+            name: name.to_string(),
+            tmdb_id: None,
+            title: CreditedTitle::Movie(id.to_string()),
+        }
+    }
+
+    fn show(name: &str, id: &str) -> Credit {
+        Credit {
+            name: name.to_string(),
+            tmdb_id: None,
+            title: CreditedTitle::Show(id.to_string()),
+        }
+    }
+
+    fn credited(person: u64, credit: Credit) -> Credit {
+        Credit {
+            tmdb_id: Some(person),
+            ..credit
+        }
+    }
+
+    #[test]
+    fn a_slug_resolves_to_the_spelling_the_library_holds() {
+        let credits = vec![movie("Conan O'Brien", "m1"), show("Conan O'Brien", "s1")];
+
+        let found = resolve_person(credits, "conan-o-brien").expect("a match");
+
+        assert_eq!(found.name, "Conan O'Brien");
+        assert_eq!(found.movie_ids, ["m1"]);
+        assert_eq!(found.show_ids, ["s1"]);
+        assert!(found.namesakes.is_empty());
+    }
+
+    #[test]
+    fn a_display_name_resolves_however_it_is_cased_or_spaced() {
+        let credits = vec![movie("Timothée Chalamet", "m1")];
+
+        let found = resolve_person(credits.clone(), "  timothée   CHALAMET ");
+
+        assert_eq!(found, resolve_person(credits, "Timothée Chalamet"));
+        assert_eq!(found.expect("a match").movie_ids, ["m1"]);
+    }
+
+    #[test]
+    fn a_title_crediting_someone_twice_counts_it_once() {
+        let credits = vec![movie("Ben Stiller", "m1"), movie("Ben Stiller", "m1")];
+
+        let found = resolve_person(credits, "ben-stiller").expect("a match");
+
+        assert_eq!(found.movie_ids, ["m1"]);
+    }
+
+    #[test]
+    fn the_better_credited_of_two_spellings_sharing_a_slug_wins_and_names_the_other() {
+        let credits = vec![
+            movie("Anne Marie", "m1"),
+            movie("Anne-Marie", "m2"),
+            show("Anne-Marie", "s1"),
+        ];
+
+        let found = resolve_person(credits, "anne-marie").expect("a match");
+
+        assert_eq!(found.name, "Anne-Marie");
+        assert_eq!(found.movie_ids, ["m2"]);
+        assert_eq!(found.show_ids, ["s1"]);
+        assert_eq!(found.namesakes, ["Anne Marie"]);
+    }
+
+    #[test]
+    fn an_evenly_credited_slug_goes_to_the_alphabetically_first_spelling() {
+        let credits = vec![movie("Zoe Bell", "m2"), movie("Zoé Bell", "m1")];
+
+        let found = resolve_person(credits, "zoe-bell").expect("a match");
+
+        assert_eq!(found.name, "Zoe Bell");
+        assert_eq!(found.namesakes, ["Zoé Bell"]);
+    }
+
+    #[test]
+    fn a_lookup_nothing_is_credited_under_resolves_to_nobody() {
+        let credits = vec![movie("Emily Blunt", "m1")];
+
+        assert_eq!(resolve_person(credits.clone(), "nobody"), None);
+        assert_eq!(resolve_person(credits.clone(), "   "), None);
+        assert_eq!(resolve_person(credits, "-"), None);
+    }
+
+    #[test]
+    fn an_id_answers_with_every_title_however_the_credits_spell_the_person() {
+        let credits = vec![
+            credited(1234, movie("Zoë Kravitz", "m1")),
+            credited(1234, show("Zoe Kravitz", "s1")),
+            credited(9999, movie("Zoe Kravitz", "m2")),
+        ];
+
+        let found = resolve_person(credits, "1234").expect("a match");
+
+        assert_eq!(found.tmdb_id, Some(1234));
+        assert_eq!(found.movie_ids, ["m1"]);
+        assert_eq!(found.show_ids, ["s1"]);
+        assert!(found.namesakes.is_empty());
+    }
+
+    #[test]
+    fn an_id_separates_two_people_credited_under_one_name() {
+        let credits = vec![
+            credited(1, movie("John Williams", "m1")),
+            credited(2, movie("John Williams", "m2")),
+        ];
+
+        let one = resolve_person(credits.clone(), "1").expect("a match");
+        let two = resolve_person(credits.clone(), "2").expect("a match");
+        let folded = resolve_person(credits, "john-williams").expect("a match");
+
+        assert_eq!(one.movie_ids, ["m1"]);
+        assert_eq!(two.movie_ids, ["m2"]);
+        assert_eq!(folded.movie_ids, ["m1", "m2"]);
+        assert_eq!(folded.tmdb_id, None);
+    }
+
+    #[test]
+    fn a_folded_name_still_reports_the_id_its_credits_agree_on() {
+        let credits = vec![
+            credited(1234, movie("Greta Gerwig", "m1")),
+            movie("Greta Gerwig", "m2"),
+        ];
+
+        let found = resolve_person(credits, "greta-gerwig").expect("a match");
+
+        assert_eq!(found.tmdb_id, Some(1234));
+        assert_eq!(found.movie_ids, ["m1", "m2"]);
+    }
+
+    #[test]
+    fn an_id_no_credit_carries_falls_back_to_folding_it_as_a_name() {
+        let credits = vec![credited(1234, movie("Greta Gerwig", "m1"))];
+
+        assert_eq!(resolve_person(credits, "9999"), None);
+    }
+}