kryten-webqueue 0.10.0__tar.gz → 0.14.0__tar.gz

{kryten_webqueue-0.10.0 → kryten_webqueue-0.14.0}/CHANGELOG.md

@@ -6,6 +6,48 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
+## [0.14.0] — 2026-06-13
+
+### Added
+
+- **Inline promo settings editing (plan O2).** The **Promos** admin page settings panel is now editable: toggle the system enable, set the movie threshold, general cadence (`every_n_items` / `every_m_minutes` / `no_repeat`), and per-type `enabled` / `order` / `weight`, then **Save**. Changes are persisted to the service config file and hot-applied to the running `PromoDirector` — no restart required. Backend: `PUT /admin/promos/config` (admin-only) plus `Config.save()` (atomic write back to the loaded config file) and `PromoDirector.update_config()`.
+- **Cancel/refund notifications (plan O4).** When the presence monitor cancels & refunds a pending paid item, the owner now receives a PM explaining it ("… cancelled and refunded because you left the channel / you went AFK"). Controlled by `presence_refund.notify_user` (default on); best-effort so a failed PM never blocks the refund.
+
+### Changed
+
+- **`presence_refund.on_afk` now defaults on (plan O1).** AFK-based cancel/refund is enabled by default now that Kryten-Robot v1.10.0 (which tracks CyTube's `setAFK` event) is released. Set it off if running against an older Robot.
+
+### Tested
+
+- DB-level test asserting promo pool clips are hidden from browse/search and rejected by pay-to-play (`get_item`), and become visible again when the `promo_type` is cleared (plan §2.9 gap).
+- Config save round-trip + no-source-path guard; presence-cancel PM (sent / suppressed) coverage.
+
+
+### Added
+
+- **Promo admin UI.** A new **Promos** admin page (`/admin/promos`, linked from the admin panel):
+  - **Promo pool designation** — assign any saved playlist a promo type from a dropdown (or clear it), reusing the existing playlist editor for the clips. Immutable playlists are excluded (release them first). Promo pools are flagged with a badge on the Playlists page.
+  - **Promo settings panel** — read-only display of the live `promos` configuration (system enable, movie threshold, general cadence, and a per-type table of enabled/order/weight). Inline editing is a planned follow-up; values come from the config file.
+- **Live-queue promo badges.** Promo items in the public queue view now render distinctly, badged by promo type (Channel ID, Event, Mod Shoutout, Feature, Viewer's Choice) with a separate accent.
+- Backend: `GET /admin/promos/config` and `GET /admin/promos/pools` (admin-only).
+
+## [0.11.0] — 2026-06-13
+
+### Added
+
+- **Promo insertion system (`PromoDirector`).** Curated promo clips are now inserted between mutable content as playback advances, driven by the state poller:
+  - **General promos** (`channel_identity`, `event`, `mod_shoutout`) inserted on a cadence — every N content items or every M minutes, whichever comes first — with weighted type selection and per-type `random`/`sequential` clip ordering plus an optional `no_repeat` guard.
+  - **Feature Presentation** lead-in immediately before a mutable-playlist movie (`duration_sec >= movie_threshold_seconds`).
+  - **Viewer's Choice** lead-in immediately before any pay-to-play item (a paid movie gets Viewer's Choice, never Feature Presentation). Inserted synchronously at pay time so it is in place before a "play next" item can begin, and removed automatically if the paid item is later cancelled/refunded (including presence-based cancels).
+  - When both are due before the same item the order is `[general][lead-in][content]`. Promos are added as CyTube **temp** items (via the throttled add helper) so they auto-remove after playing and never accumulate across loops. The director is a no-op during an immutable scheduled event.
+- **Promo pools.** A saved playlist can be designated a promo pool by tagging it with a `promo_type` (via the playlist create/update API). Promo pools are hidden from public browse/search and excluded from pay-to-play, the same treatment as immutable playlists.
+- Config: `promos` block — global `enabled`, `movie_threshold_seconds`, a `general` cadence block (`every_n_items`, `every_m_minutes`, `no_repeat`), and per-type `enabled`/`order`/`weight` settings.
+- DB: migration v10 (`promo_type` on `saved_playlists` + index) and v11 (`is_promo`, `promo_type`, `lead_in_for_uid` on `queue_shadow`).
+
+### Note
+
+- Backend promo designation and the full insertion engine ship in this release. A dedicated admin promo-settings panel and live-queue promo badges are a planned follow-up; pools can be designated today via the playlist API and `promos` config is file-based.
+
 ## [0.10.0] — 2026-06-13
 
 ### Added

{kryten_webqueue-0.10.0 → kryten_webqueue-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kryten-webqueue
-Version: 0.10.0
+Version: 0.14.0
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

{kryten_webqueue-0.10.0 → kryten_webqueue-0.14.0}/config.example.json

@@ -26,9 +26,27 @@
   "presence_refund": {
     "enabled": true,
     "on_leave": true,
-    "on_afk": false,
+    "on_afk": true,
     "grace_seconds": 60.0,
-    "check_interval_seconds": 15.0
+    "check_interval_seconds": 15.0,
+    "notify_user": true
+  },
+
+  "promos": {
+    "enabled": true,
+    "movie_threshold_seconds": 3600.0,
+    "general": {
+      "every_n_items": 4,
+      "every_m_minutes": 20.0,
+      "no_repeat": true
+    },
+    "types": {
+      "channel_identity": { "enabled": true, "order": "random", "weight": 3 },
+      "event": { "enabled": true, "order": "random", "weight": 2 },
+      "mod_shoutout": { "enabled": true, "order": "sequential", "weight": 1 },
+      "feature_presentation": { "enabled": true, "order": "random", "weight": 1 },
+      "viewers_choice": { "enabled": true, "order": "random", "weight": 1 }
+    }
   },
 
   "db_path": "/var/lib/kryten-webqueue/webqueue.db",

{kryten_webqueue-0.10.0 → kryten_webqueue-0.14.0}/docs/PLAN_PRESENCE_AND_PROMOS.md

@@ -392,11 +392,33 @@ load-time. (FP and general promos stay purely poller-driven.)
   fields, skips redundant KV writes) and registers the event in `state_events`.
   Covered by `tests/test_state_manager_afk.py`. Once Robot v1.10.0 is deployed,
   `on_afk` can be safely defaulted **on** in webqueue's presence-refund config.
+
+  **DONE (webqueue v0.13.0):** `presence_refund.on_afk` now defaults **on** (the
+  `PresenceRefundConfig` default and `config.example.json` both flipped to
+  `true`). Set it back off only if running against a Robot older than v1.10.0.
 - **O2 — Config editability**: is runtime editing of `promos` config in-scope, or
   is file-config + restart acceptable for the first cut? (Plan assumes file
   config first, editable panel as a follow-up.)
+
+  **RESOLVED (v0.13.0):** the editable panel shipped. The Promos admin settings
+  panel now edits the `promos` config (system enable, movie threshold, general
+  cadence, per-type enable/order/weight) via `PUT /admin/promos/config`, which
+  validates against `PromoConfig`, persists with `Config.save()` (atomic write
+  back to the loaded config file), and hot-applies via
+  `PromoDirector.update_config()` — no restart required.
 - **O3 — Single vs multiple pools per type**: plan supports multiple playlists of
   the same `promo_type` (unioned). Confirm one-per-type is acceptable in the UI.
+
+  **RESOLVED (v0.13.0):** **multiple pools per type are intentionally allowed.**
+  Clips from every playlist sharing a `promo_type` are unioned into that type's
+  pool (`get_promo_pool_items`), and the admin UI permits tagging more than one
+  playlist with the same type. No enforcement was added — this is the accepted
+  product behaviour, not a bug.
 - **O4 — Notifications**: should a cancelled-on-disappear item post a chat/PM
   notice, or refund silently? (Plan: silent refund + WS state update; easy to add
   a notice.)
+
+  **RESOLVED (v0.13.0):** a PM is now sent. On a presence-based cancel the owner
+  receives a PM ("… cancelled and refunded because you left the channel / you
+  went AFK"), gated by `presence_refund.notify_user` (default on) and best-effort
+  so a failed PM never blocks the refund.

{kryten_webqueue-0.10.0 → kryten_webqueue-0.14.0}/kryten_webqueue/app.py

@@ -17,6 +17,7 @@ from .catalog.images import CoverArtResolver
 from .queue.shadow import QueueShadow
 from .queue.poller import StatePoller
 from .queue.presence import PresenceRefundMonitor
+from .promos.director import PromoDirector
 from .ws.manager import WebSocketManager
 from .playlists.scheduler import PlaylistScheduler
 from .auth.rate_limit import RateLimiter
@@ -30,6 +31,7 @@ from .routes.admin_schedules import router as admin_schedules_router
 from .routes.admin_queue import router as admin_queue_router
 from .routes.admin_jobs import router as admin_jobs_router
 from .routes.admin_catalog import router as admin_catalog_router
+from .routes.admin_promos import router as admin_promos_router
 from .routes.pages import router as pages_router
 from .ws.handler import router as ws_router
 
@@ -117,6 +119,14 @@ async def lifespan(app: FastAPI):
     await shadow.load_from_db()
     app.state.shadow = shadow
 
+    # Promo director (poller-driven; also used synchronously by the pay path)
+    promo_director = PromoDirector(
+        api_gate=api_gate, db=db, shadow=shadow, config=config.promos,
+        add_delay_sec=config.playlist_bulk_add_delay_sec,
+        add_max_retries=config.playlist_bulk_add_max_retries,
+    )
+    app.state.promo_director = promo_director
+
     # State poller
     poller = StatePoller(
         api_gate=api_gate,
@@ -124,6 +134,7 @@ async def lifespan(app: FastAPI):
         ws_manager=ws_manager,
         db=db,
         interval=config.state_poll_interval_sec,
+        promo_director=promo_director,
     )
     await poller.start()
     app.state.poller = poller
@@ -231,6 +242,7 @@ def create_app(config: Config) -> FastAPI:
     app.include_router(admin_queue_router)
     app.include_router(admin_jobs_router)
     app.include_router(admin_catalog_router)
+    app.include_router(admin_promos_router)
     app.include_router(ws_router)
 
     # Health check

{kryten_webqueue-0.10.0 → kryten_webqueue-0.14.0}/kryten_webqueue/catalog/db.py

@@ -290,6 +290,23 @@ MIGRATIONS = [
     """
     ALTER TABLE playlist_schedules ADD COLUMN fallback_playlist_id INTEGER REFERENCES saved_playlists(id) ON DELETE SET NULL;
     """,
+    # v10: Tag a saved playlist as a promo pool. A non-NULL promo_type marks the
+    # playlist as a reserved pool of promo clips for that type; such playlists
+    # are hidden from public browse/search and excluded from pay-to-play (same
+    # treatment as is_immutable). NULL = a normal playlist.
+    """
+    ALTER TABLE saved_playlists ADD COLUMN promo_type TEXT;
+    CREATE INDEX IF NOT EXISTS idx_saved_playlists_promo ON saved_playlists(promo_type);
+    """,
+    # v11: Annotate live promo items inserted into the queue shadow. is_promo
+    # marks a system-inserted promo clip; promo_type is its pool; lead_in_for_uid
+    # links a Feature-Presentation / Viewer's-Choice lead-in to the content uid
+    # it immediately precedes (NULL for general cadence promos).
+    """
+    ALTER TABLE queue_shadow ADD COLUMN is_promo BOOLEAN NOT NULL DEFAULT 0;
+    ALTER TABLE queue_shadow ADD COLUMN promo_type TEXT;
+    ALTER TABLE queue_shadow ADD COLUMN lead_in_for_uid INTEGER;
+    """,
 ]
 
 
@@ -351,7 +368,7 @@ class Database:
             WHERE c.friendly_token NOT IN (
                 SELECT spi.media_id FROM saved_playlist_items spi
                 JOIN saved_playlists sp ON spi.playlist_id = sp.id
-                WHERE sp.is_immutable = 1 AND spi.media_type = 'cm'
+                WHERE (sp.is_immutable = 1 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
             )
         """
         params: list = []
@@ -400,7 +417,7 @@ class Database:
             WHERE c.friendly_token NOT IN (
                 SELECT spi.media_id FROM saved_playlist_items spi
                 JOIN saved_playlists sp ON spi.playlist_id = sp.id
-                WHERE sp.is_immutable = 1 AND spi.media_type = 'cm'
+                WHERE (sp.is_immutable = 1 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
             )
         """
         params: list = []
@@ -439,7 +456,7 @@ class Database:
               AND c.friendly_token NOT IN (
                   SELECT spi.media_id FROM saved_playlist_items spi
                   JOIN saved_playlists sp ON spi.playlist_id = sp.id
-                  WHERE sp.is_immutable = 1 AND spi.media_type = 'cm'
+                  WHERE (sp.is_immutable = 1 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
               )
         """
         params: list = [query_text]
@@ -463,7 +480,7 @@ class Database:
               AND c.friendly_token NOT IN (
                   SELECT spi.media_id FROM saved_playlist_items spi
                   JOIN saved_playlists sp ON spi.playlist_id = sp.id
-                  WHERE sp.is_immutable = 1 AND spi.media_type = 'cm'
+                  WHERE (sp.is_immutable = 1 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
               )
         """
         params: list = [query_text]
@@ -481,7 +498,7 @@ class Database:
               AND friendly_token NOT IN (
                   SELECT spi.media_id FROM saved_playlist_items spi
                   JOIN saved_playlists sp ON spi.playlist_id = sp.id
-                  WHERE sp.is_immutable = 1 AND spi.media_type = 'cm'
+                  WHERE (sp.is_immutable = 1 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
               )
         """
         return await self._fetch_one(sql, [friendly_token])
@@ -545,7 +562,7 @@ class Database:
         sql = """
             SELECT 1 FROM saved_playlist_items spi
             JOIN saved_playlists sp ON spi.playlist_id = sp.id
-            WHERE sp.is_immutable = 1
+            WHERE (sp.is_immutable = 1 OR sp.promo_type IS NOT NULL)
               AND spi.media_type = 'cm'
               AND spi.media_id = ?
             LIMIT 1
@@ -803,13 +820,17 @@ class Database:
     async def upsert_shadow_item(self, item: dict):
         sql = """
             INSERT OR REPLACE INTO queue_shadow
-                (uid, position, title, media_type, media_id, duration_sec, is_pay, paid_by, tier, z_cost, schedule_id, added_at)
+                (uid, position, title, media_type, media_id, duration_sec, is_pay, paid_by, tier, z_cost, schedule_id,
+                 is_promo, promo_type, lead_in_for_uid, added_at)
             VALUES (:uid, :position, :title, :media_type, :media_id, :duration_sec, :is_pay,
-                    :paid_by, :tier, :z_cost, :schedule_id, :added_at)
+                    :paid_by, :tier, :z_cost, :schedule_id,
+                    :is_promo, :promo_type, :lead_in_for_uid, :added_at)
         """
         defaults = {"paid_by": None, "tier": None, "z_cost": None, "schedule_id": None,
-                    "friendly_token": None, "added_at": datetime.now(UTC).isoformat()}
+                    "friendly_token": None, "is_promo": 0, "promo_type": None,
+                    "lead_in_for_uid": None, "added_at": datetime.now(UTC).isoformat()}
         row = {**defaults, **item}
+        row["is_promo"] = int(bool(row.get("is_promo")))
         await self._db.execute(sql, row)
         await self._db.commit()
 
@@ -886,18 +907,39 @@ class Database:
     async def get_saved_playlist(self, playlist_id: int) -> dict | None:
         return await self._fetch_one("SELECT * FROM saved_playlists WHERE id=?", [playlist_id])
 
-    async def create_saved_playlist(self, *, name: str, description: str | None, is_immutable: bool, created_by: str) -> int:
+    async def create_saved_playlist(self, *, name: str, description: str | None, is_immutable: bool, created_by: str, promo_type: str | None = None) -> int:
         cursor = await self._db.execute(
-            "INSERT INTO saved_playlists (name, description, is_immutable, created_by) VALUES (?, ?, ?, ?)",
-            [name, description, int(is_immutable), created_by],
+            "INSERT INTO saved_playlists (name, description, is_immutable, created_by, promo_type) VALUES (?, ?, ?, ?, ?)",
+            [name, description, int(is_immutable), created_by, promo_type],
         )
         await self._db.commit()
         return cursor.lastrowid
 
-    async def update_saved_playlist(self, playlist_id: int, *, name: str, description: str | None, is_immutable: bool):
+    async def update_saved_playlist(self, playlist_id: int, *, name: str, description: str | None, is_immutable: bool, promo_type: str | None = None):
         await self._execute(
-            "UPDATE saved_playlists SET name=?, description=?, is_immutable=?, updated_at=datetime('now') WHERE id=?",
-            [name, description, int(is_immutable), playlist_id],
+            "UPDATE saved_playlists SET name=?, description=?, is_immutable=?, promo_type=?, updated_at=datetime('now') WHERE id=?",
+            [name, description, int(is_immutable), promo_type, playlist_id],
+        )
+
+    async def get_promo_pools(self) -> list[dict]:
+        """All saved playlists that are designated promo pools (promo_type set)."""
+        return await self._fetch_all(
+            "SELECT * FROM saved_playlists WHERE promo_type IS NOT NULL ORDER BY promo_type, name"
+        )
+
+    async def get_promo_pool_items(self, promo_type: str) -> list[dict]:
+        """Union of clips across every playlist tagged with ``promo_type``.
+
+        Returns the playlist items in a stable order (playlist id, then
+        position) so ``sequential`` selection is deterministic.
+        """
+        return await self._fetch_all(
+            "SELECT spi.media_type, spi.media_id, spi.title, spi.duration_sec "
+            "FROM saved_playlist_items spi "
+            "JOIN saved_playlists sp ON spi.playlist_id = sp.id "
+            "WHERE sp.promo_type = ? "
+            "ORDER BY sp.id, spi.position",
+            [promo_type],
         )
 
     async def delete_saved_playlist(self, playlist_id: int):

{kryten_webqueue-0.10.0 → kryten_webqueue-0.14.0}/kryten_webqueue/config.py

@@ -1,5 +1,5 @@
 from pathlib import Path
-from pydantic import BaseModel
+from pydantic import BaseModel, PrivateAttr
 import json
 
 
@@ -31,20 +31,71 @@ class PresenceRefundConfig(BaseModel):
     left alone.
 
     ``on_afk`` relies on the Robot tracking CyTube's ``setAFK`` event (shipped
-    in Kryten-Robot v1.10.0). It defaults off; enable it once that Robot
-    version is deployed to production.
+    in Kryten-Robot v1.10.0). It defaults on now that v1.10.0 is released; set it
+    off if running against an older Robot whose ``meta.afk`` goes stale.
+
+    ``notify_user`` PMs the owner when a pending paid item is cancelled & refunded
+    so the cancellation isn't silent.
     """
 
     enabled: bool = True
     on_leave: bool = True
-    on_afk: bool = False              # needs Kryten-Robot >= 1.10.0 deployed
+    on_afk: bool = True               # needs Kryten-Robot >= 1.10.0 deployed
     grace_seconds: float = 60.0       # wait before acting; re-check after grace
     check_interval_seconds: float = 15.0  # how often to evaluate owners
+    notify_user: bool = True          # PM the owner on cancel/refund
+
+
+class PromoTypeConfig(BaseModel):
+    """Per-type promo settings.
+
+    ``order`` is ``random`` (uniform over the pool) or ``sequential`` (rotate
+    through the pool in stored order, resuming where it left off). ``weight`` is
+    the relative frequency among the *general* types when a cadence slot fires
+    (ignored for the lead-in types).
+    """
+
+    enabled: bool = True
+    order: str = "random"   # "random" | "sequential"
+    weight: int = 1
+
+
+class GeneralPromoConfig(BaseModel):
+    """Cadence for the general (between-content) promos."""
+
+    every_n_items: int = 4       # insert a general promo every N content items
+    every_m_minutes: float = 20.0  # ...or roughly every M minutes, whichever first
+    no_repeat: bool = True       # don't play the same clip twice in a row
+
+
+class PromoConfig(BaseModel):
+    """Settings for the promo insertion system (see PromoDirector).
+
+    Promo clips live in saved playlists tagged with a ``promo_type``. General
+    promos (types 1-3) are inserted on a cadence between mutable content;
+    Feature-Presentation (movies) and Viewer's-Choice (pay items) lead-ins
+    (types 4-5) are attached immediately before a qualifying upcoming item.
+    """
+
+    enabled: bool = True
+    movie_threshold_seconds: float = 3600.0
+    general: GeneralPromoConfig = GeneralPromoConfig()
+    types: dict[str, PromoTypeConfig] = {
+        "channel_identity": PromoTypeConfig(order="random", weight=3),
+        "event": PromoTypeConfig(order="random", weight=2),
+        "mod_shoutout": PromoTypeConfig(order="sequential", weight=1),
+        "feature_presentation": PromoTypeConfig(order="random"),
+        "viewers_choice": PromoTypeConfig(order="random"),
+    }
 
 
 class Config(BaseModel):
     """Application configuration loaded from JSON file."""
 
+    # Path the config was loaded from; set by ``from_file`` so editable settings
+    # (e.g. the promo admin panel) can persist back to the same file.
+    _source_path: Path | None = PrivateAttr(default=None)
+
     # Server
     channel: str = "Q_A"
     host: str = "0.0.0.0"
@@ -71,6 +122,9 @@ class Config(BaseModel):
     # Presence-based cancel/refund of pending paid items
     presence_refund: PresenceRefundConfig = PresenceRefundConfig()
 
+    # Promo insertion system
+    promos: PromoConfig = PromoConfig()
+
     # Database
     db_path: str = "/var/lib/kryten-webqueue/webqueue.db"
 
@@ -95,5 +149,22 @@ class Config(BaseModel):
 
     @classmethod
     def from_file(cls, path: str | Path) -> "Config":
-        with open(path) as f:
-            return cls(**json.load(f))
+        with open(path, encoding="utf-8") as f:
+            cfg = cls(**json.load(f))
+        cfg._source_path = Path(path)
+        return cfg
+
+    def save(self) -> None:
+        """Persist the current config back to the file it was loaded from.
+
+        Writes atomically (temp file + replace) so a crash mid-write can't leave
+        a truncated config. Raises if the config has no known source path (e.g.
+        constructed in-memory by a test).
+        """
+        if self._source_path is None:
+            raise RuntimeError("Config has no source path; cannot persist changes")
+        tmp = self._source_path.with_name(self._source_path.name + ".tmp")
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(self.model_dump(), f, indent=2)
+            f.write("\n")
+        tmp.replace(self._source_path)

kryten_webqueue-0.14.0/kryten_webqueue/promos/__init__.py

@@ -0,0 +1,12 @@
+"""Promo insertion subsystem.
+
+Curated promo playlists (saved playlists tagged with a ``promo_type``) are
+inserted between mutable content by the :class:`PromoDirector`.
+"""
+
+# The five recognised promo types. Types 1-3 are "general" promos inserted on a
+# cadence between content; types 4-5 are "lead-ins" attached immediately before
+# a specific upcoming item (a mutable-playlist movie, or a pay-to-play item).
+GENERAL_PROMO_TYPES = ("channel_identity", "event", "mod_shoutout")
+LEAD_IN_PROMO_TYPES = ("feature_presentation", "viewers_choice")
+PROMO_TYPES = GENERAL_PROMO_TYPES + LEAD_IN_PROMO_TYPES