kryten-webqueue 0.40.4__tar.gz → 0.41.0__tar.gz

{kryten_webqueue-0.40.4 → kryten_webqueue-0.41.0}/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## [Unreleased]
 
+## [0.41.0] - 2026-08-24
+
+### Fixed
+
+- **Reserved (immutable / promo-pool) items were leaking into the public
+  catalog.** The browse/search/`get_item`/`is_restricted`/tag filters excluded
+  reserved items by comparing `catalog.friendly_token` against
+  `saved_playlist_items.media_id` — but `media_id` stores the CyTube **manifest
+  URL** (e.g. `.../api/v1/media/cytube/<token>.json?format=json`), never the bare
+  token, so the `NOT IN` never matched and **every** item in Friday Night /
+  Saturday / promo pools stayed visible and pay-queueable. All six filter sites
+  now resolve `media_id` (manifest URL *or* legacy bare token) back to a
+  friendly_token via the catalog before excluding. This restores the intended
+  "reserved items are hidden from browse/search and rejected by pay-to-play"
+  behaviour.
+
+### Added
+
+- **Weekend blackout window (hides upcoming-weekend items until they've aired).**
+  Items scheduled on an upcoming weekend sheet must not appear in the catalog —
+  but only the *next* weekend is ever materialised as an immutable playlist, so
+  films on later weekends (or added directly to column F) had nothing hiding
+  them. A new `catalog_blackouts` table (migration v26) hides a rehosted item
+  from regular users until the end of the **following** weekend, keeping replays
+  hidden through that week. Keyed on the bare `friendly_token`.
+  - New standalone **`catalog_blackout`** maintenance job scans the workbook's
+    current/future weekend sheets (columns **E** and **F**) for dropsugar URLs,
+    resolves them to friendly_tokens, and blacks each out. It downloads nothing;
+    it reuses the fetchurls SharePoint/local workbook source. Runnable from the
+    admin Jobs tab and schedulable via cron.
+  - Blacked-out items are hidden from browse, search, `get_item`, pay-to-play,
+    and the item detail page for regular users. **Admins** still see them (with
+    "Show hidden items" on), visually **dimmed** with a `BLACKOUT` badge, and can
+    queue them manually (`/admin/queue/add` bypasses the visibility filters).
+
 ## [0.40.4] - 2026-08-21
 
 ### Added

{kryten_webqueue-0.40.4 → kryten_webqueue-0.41.0}/PKG-INFO

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

{kryten_webqueue-0.40.4 → kryten_webqueue-0.41.0}/kryten_webqueue/app.py

@@ -99,6 +99,7 @@ async def lifespan(app: FastAPI):
     # with a clear message rather than crashing startup.
     from .jobs.tasks import (
         catalog_enrich_job,
+        catalog_blackout_job,
         fetch_job,
         fetch_queue_add_job,
         fetch_queue_drain_job,
@@ -107,6 +108,7 @@ async def lifespan(app: FastAPI):
         tmdb_index_refresh_job,
         tmdb_coverage_report_job,
         CATALOG_ENRICH_SCHEMA,
+        CATALOG_BLACKOUT_SCHEMA,
         FETCH_SCHEMA,
         FETCH_QUEUE_ADD_SCHEMA,
         FETCH_QUEUE_DRAIN_SCHEMA,
@@ -143,6 +145,12 @@ async def lifespan(app: FastAPI):
         label="Fetch URLs (weekend workbook)",
         schema=FETCHURLS_SCHEMA,
     )
+    job_manager.register(
+        "catalog_blackout",
+        catalog_blackout_job,
+        label="Catalog Blackout (hide upcoming-weekend items)",
+        schema=CATALOG_BLACKOUT_SCHEMA,
+    )
     job_manager.register(
         "motd_posters",
         motd_posters_job,

{kryten_webqueue-0.40.4 → kryten_webqueue-0.41.0}/kryten_webqueue/catalog/db/__init__.py

@@ -12,6 +12,7 @@ from ._watchlist import _WatchlistMixin
 from ._people import _PeopleMixin
 from ._enrichment import _EnrichmentMixin
 from ._fetch_queue import _FetchQueueMixin
+from ._blackouts import _BlackoutMixin
 
 
 class Database(
@@ -23,6 +24,7 @@ class Database(
     _PeopleMixin,
     _EnrichmentMixin,
     _FetchQueueMixin,
+    _BlackoutMixin,
     _DBBase,
 ):
     """Async SQLite database wrapper."""
@@ -34,11 +36,3 @@ __all__ = [
     "HIDDEN_CATEGORY_NAMES",
     "HIDDEN_TAG_NAMES",
 ]
-
-
-__all__ = [
-    "Database",
-    "HIDDEN_ITEM_TAG",
-    "HIDDEN_CATEGORY_NAMES",
-    "HIDDEN_TAG_NAMES",
-]

kryten_webqueue-0.41.0/kryten_webqueue/catalog/db/_blackouts.py

@@ -0,0 +1,55 @@
+class _BlackoutMixin:
+    """Weekend blackout window CRUD (see migration v26).
+
+    A blackout hides a rehosted catalog item from regular users until
+    ``expires_at`` (the end of the *following* weekend). Keyed on the bare
+    friendly_token. Populated by the standalone ``catalog_blackout`` job; the
+    catalog browse/search filters consult it via ``_blackout_exclusion``.
+    """
+
+    async def upsert_blackout(
+        self, friendly_token: str, *, reason: str, expires_at: str
+    ) -> None:
+        """Insert or extend a blackout. Keeps the latest (max) expiry on conflict."""
+        await self._db.execute(
+            """
+            INSERT INTO catalog_blackouts (friendly_token, reason, expires_at)
+            VALUES (?, ?, ?)
+            ON CONFLICT(friendly_token) DO UPDATE SET
+                reason = excluded.reason,
+                expires_at = MAX(catalog_blackouts.expires_at, excluded.expires_at)
+            """,
+            [friendly_token, reason, expires_at],
+        )
+        await self._db.commit()
+
+    async def prune_expired_blackouts(self) -> int:
+        """Delete blackout rows whose window has fully elapsed. Returns count removed."""
+        cursor = await self._db.execute(
+            "DELETE FROM catalog_blackouts WHERE expires_at <= datetime('now')"
+        )
+        await self._db.commit()
+        return cursor.rowcount or 0
+
+    async def is_blackout(self, friendly_token: str) -> bool:
+        """True when the token is under an active (unexpired) blackout."""
+        row = await self._fetch_one(
+            "SELECT 1 FROM catalog_blackouts "
+            "WHERE friendly_token = ? AND expires_at > datetime('now') LIMIT 1",
+            [friendly_token],
+        )
+        return row is not None
+
+    async def count_active_blackouts(self) -> int:
+        row = await self._fetch_one(
+            "SELECT COUNT(*) AS cnt FROM catalog_blackouts "
+            "WHERE expires_at > datetime('now')"
+        )
+        return row["cnt"] if row else 0
+
+    async def list_active_blackouts(self) -> list[dict]:
+        return await self._fetch_all(
+            "SELECT friendly_token, reason, expires_at, created_at "
+            "FROM catalog_blackouts WHERE expires_at > datetime('now') "
+            "ORDER BY expires_at"
+        )

{kryten_webqueue-0.40.4 → kryten_webqueue-0.41.0}/kryten_webqueue/catalog/db/_catalog.py

@@ -115,6 +115,57 @@ def _hidden_exclusion(alias: str = "c") -> tuple[str, list]:
     return sql, [*HIDDEN_CATEGORY_NAMES, *HIDDEN_TAG_NAMES]
 
 
+# Saved-playlist items usually store ``media_id`` as the CyTube *manifest URL*
+# (e.g. ``.../api/v1/media/cytube/<token>.json?format=json``), though some
+# legacy/admin-added rows carry the bare friendly_token. A naive
+# ``friendly_token = media_id`` compare misses the URL form, so resolve either
+# shape back to a friendly_token via the catalog to exclude reserved
+# (immutable / promo-pool) items from public results.
+def _reserved_exclusion(alias: str = "c") -> tuple[str, list]:
+    """SQL AND-fragment (+ params) excluding reserved (immutable/promo) items.
+
+    Prefixed with ``AND`` so it can be appended to an existing WHERE clause that
+    references the catalog row under ``alias``.
+    """
+    sql = f"""
+            AND {alias}.friendly_token NOT IN (
+                SELECT c2.friendly_token FROM saved_playlist_items spi
+                JOIN saved_playlists sp ON spi.playlist_id = sp.id
+                JOIN catalog c2
+                  ON c2.manifest_url = spi.media_id
+                  OR c2.friendly_token = spi.media_id
+                WHERE (sp.is_immutable = 1 OR sp.promo_type IS NOT NULL)
+                  AND spi.media_type = 'cm'
+            )
+    """
+    return sql, []
+
+
+def _blackout_exclusion(alias: str = "c") -> tuple[str, list]:
+    """SQL AND-fragment (+ params) hiding items under an active weekend blackout.
+
+    Keyed on the bare friendly_token; ``expires_at`` is compared against
+    ``datetime('now')`` (UTC). Prefixed with ``AND`` for appending to a WHERE.
+    """
+    sql = f"""
+            AND {alias}.friendly_token NOT IN (
+                SELECT friendly_token FROM catalog_blackouts
+                WHERE expires_at > datetime('now')
+            )
+    """
+    return sql, []
+
+
+# Computed SELECT column: 1 when the catalog row (alias ``c``) is under an active
+# weekend blackout. Regular users never receive these rows; it lets admin views
+# dim blacked-out items to show "a normal user would not see this".
+_BLACKOUT_ACTIVE_COL = (
+    "EXISTS (SELECT 1 FROM catalog_blackouts b "
+    "WHERE b.friendly_token = c.friendly_token "
+    "AND b.expires_at > datetime('now')) AS blackout_active"
+)
+
+
 def _promo_hidden_media_subquery() -> tuple[str, list]:
     """Subquery (+ params) yielding media_ids that are promos/bumpers.
 
@@ -262,19 +313,24 @@ class _CatalogMixin:
     ) -> list[dict]:
         query = """
             SELECT c.friendly_token, c.title, c.duration_sec, c.cover_art_path, c.cover_art_source, c.thumbnail_url, c.manifest_url,
-                   (SELECT MAX(pc.completed_at) FROM play_completions pc WHERE pc.media_id = c.friendly_token AND pc.media_type = 'cm') AS played_at
+                   (SELECT MAX(pc.completed_at) FROM play_completions pc WHERE pc.media_id = c.friendly_token AND pc.media_type = 'cm') AS played_at,
+                   {blackout_col}
             FROM catalog c
-            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 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
-            )
-        """
+            WHERE 1=1
+        """.format(
+            blackout_col=_BLACKOUT_ACTIVE_COL
+        )
         params: list = []
+        resv_sql, resv_params = _reserved_exclusion("c")
+        query += resv_sql
+        params.extend(resv_params)
         if not show_hidden:
             excl_sql, excl_params = _hidden_exclusion("c")
             query += excl_sql
             params.extend(excl_params)
+            bo_sql, bo_params = _blackout_exclusion("c")
+            query += bo_sql
+            params.extend(bo_params)
         if recently_played_days > 0:
             rp_sql, rp_params = _recently_played_exclusion("c", recently_played_days)
             query += rp_sql
@@ -352,17 +408,19 @@ class _CatalogMixin:
     ) -> int:
         query = """
             SELECT COUNT(*) as cnt FROM catalog c
-            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 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
-            )
+            WHERE 1=1
         """
         params: list = []
+        resv_sql, resv_params = _reserved_exclusion("c")
+        query += resv_sql
+        params.extend(resv_params)
         if not show_hidden:
             excl_sql, excl_params = _hidden_exclusion("c")
             query += excl_sql
             params.extend(excl_params)
+            bo_sql, bo_params = _blackout_exclusion("c")
+            query += bo_sql
+            params.extend(bo_params)
         if recently_played_days > 0:
             rp_sql, rp_params = _recently_played_exclusion("c", recently_played_days)
             query += rp_sql
@@ -434,21 +492,25 @@ class _CatalogMixin:
         sql = """
             SELECT c.friendly_token, c.title, c.duration_sec, c.cover_art_path, c.cover_art_source, c.thumbnail_url, c.manifest_url,
                    (SELECT MAX(pc.completed_at) FROM play_completions pc WHERE pc.media_id = c.friendly_token AND pc.media_type = 'cm') AS played_at,
-                   rank AS relevance
+                   rank AS relevance,
+                   {blackout_col}
             FROM catalog_fts fts
             JOIN catalog c ON c.rowid = fts.rowid
             WHERE catalog_fts MATCH ?
-              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 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
-              )
-        """
+        """.format(
+            blackout_col=_BLACKOUT_ACTIVE_COL
+        )
         params: list = [sanitized]
+        resv_sql, resv_params = _reserved_exclusion("c")
+        sql += resv_sql
+        params.extend(resv_params)
         if not show_hidden:
             excl_sql, excl_params = _hidden_exclusion("c")
             sql += excl_sql
             params.extend(excl_params)
+            bo_sql, bo_params = _blackout_exclusion("c")
+            sql += bo_sql
+            params.extend(bo_params)
         if recently_played_days > 0:
             rp_sql, rp_params = _recently_played_exclusion("c", recently_played_days)
             sql += rp_sql
@@ -495,17 +557,18 @@ class _CatalogMixin:
             FROM catalog_fts fts
             JOIN catalog c ON c.rowid = fts.rowid
             WHERE catalog_fts MATCH ?
-              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 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
-              )
         """
         params: list = [sanitized]
+        resv_sql, resv_params = _reserved_exclusion("c")
+        sql += resv_sql
+        params.extend(resv_params)
         if not show_hidden:
             excl_sql, excl_params = _hidden_exclusion("c")
             sql += excl_sql
             params.extend(excl_params)
+            bo_sql, bo_params = _blackout_exclusion("c")
+            sql += bo_sql
+            params.extend(bo_params)
         if recently_played_days > 0:
             rp_sql, rp_params = _recently_played_exclusion("c", recently_played_days)
             sql += rp_sql
@@ -523,16 +586,10 @@ class _CatalogMixin:
         return row["cnt"] if row else 0
 
     async def get_item(self, friendly_token: str) -> dict | None:
-        sql = """
-            SELECT * FROM catalog
-            WHERE friendly_token = ?
-              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 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
-              )
-        """
-        return await self._fetch_one(sql, [friendly_token])
+        resv_sql, resv_params = _reserved_exclusion("catalog")
+        bo_sql, bo_params = _blackout_exclusion("catalog")
+        sql = "SELECT * FROM catalog WHERE friendly_token = ?" + resv_sql + bo_sql
+        return await self._fetch_one(sql, [friendly_token, *resv_params, *bo_params])
 
     async def get_item_admin(self, friendly_token: str) -> dict | None:
         return await self._fetch_one(
@@ -726,12 +783,18 @@ class _CatalogMixin:
         }
 
     async def is_restricted(self, friendly_token: str) -> bool:
+        # media_id holds the manifest URL (or, for legacy rows, the bare token),
+        # so resolve either shape back to a friendly_token via the catalog
+        # rather than comparing the token to a URL directly.
         sql = """
             SELECT 1 FROM saved_playlist_items spi
             JOIN saved_playlists sp ON spi.playlist_id = sp.id
+            JOIN catalog c2
+              ON c2.manifest_url = spi.media_id
+              OR c2.friendly_token = spi.media_id
             WHERE (sp.is_immutable = 1 OR sp.promo_type IS NOT NULL)
               AND spi.media_type = 'cm'
-              AND spi.media_id = ?
+              AND c2.friendly_token = ?
             LIMIT 1
         """
         row = await self._fetch_one(sql, [friendly_token])
@@ -772,14 +835,16 @@ class _CatalogMixin:
             FROM tags t
             JOIN catalog_tags ct ON ct.tag_id = t.id
             JOIN catalog c ON ct.friendly_token = c.friendly_token
-            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 OR sp.promo_type IS NOT NULL) AND spi.media_type = 'cm'
-            )
+            WHERE 1=1
         """
         params: list = []
+        resv_sql, resv_params = _reserved_exclusion("c")
+        sql += resv_sql
+        params.extend(resv_params)
         if not show_hidden:
+            bo_sql, bo_params = _blackout_exclusion("c")
+            sql += bo_sql
+            params.extend(bo_params)
             ph = ",".join("?" * len(HIDDEN_TAG_NAMES))
             sql += f" AND t.name NOT IN ({ph})"
             params.extend(HIDDEN_TAG_NAMES)

{kryten_webqueue-0.40.4 → kryten_webqueue-0.41.0}/kryten_webqueue/catalog/db/_connection.py

@@ -457,6 +457,23 @@ MIGRATIONS = [
     """
     ALTER TABLE catalog ADD COLUMN override_artwork_tt_id TEXT;
     """,
+    # v26: Weekend blackout window. Items that appear in an upcoming weekend
+    # sheet (column E/F dropsugar URLs) are hidden from regular users until
+    # ``expires_at`` — set to the end of the *following* weekend so replays stay
+    # hidden through that week. Keyed on the bare friendly_token (which also
+    # sidesteps the manifest_url stored in saved_playlist_items.media_id).
+    # Populated by the standalone ``catalog_blackout`` maintenance job; admins
+    # bypass the filter but see a blackout indicator. Compared against
+    # ``datetime('now')`` (UTC); the multi-day window makes the tz offset moot.
+    """
+    CREATE TABLE IF NOT EXISTS catalog_blackouts (
+        friendly_token TEXT PRIMARY KEY,
+        reason         TEXT,
+        expires_at     TIMESTAMP NOT NULL,
+        created_at     TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE INDEX IF NOT EXISTS idx_catalog_blackouts_expires ON catalog_blackouts(expires_at);
+    """,
 ]
 
 

kryten_webqueue-0.41.0/kryten_webqueue/integrations/cmsutils/blackout_scan.py

@@ -0,0 +1,181 @@
+"""Scan the Channel Z workbook for upcoming-weekend dropsugar URLs to black out.
+
+A *blackout* hides a rehosted catalog item from regular users until the end of
+the weekend **following** the one it is scheduled for, so replays stay hidden
+through that week. This module only *reads* the workbook (SharePoint or a local
+``.xlsx``) and resolves dropsugar URLs in columns **E** and **F** to MediaCMS
+friendly_tokens; it downloads nothing. The async job wrapper
+(:func:`kryten_webqueue.jobs.tasks.catalog_blackout_job`) persists the result.
+
+Follows the vendored-tool contract: ``run(params, *, config, progress=None)``.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import io
+import logging
+from typing import Optional
+
+from ...playlists.importer import extract_dropsugar_token
+from .fetchurls import (
+    _SHEET_DATE_RE,
+    acquire_graph_token_silent,
+    download_sharepoint_xlsx,
+    is_dropsugar,
+)
+
+logger = logging.getLogger(__name__)
+
+# Column indices (0-based): E = source URLs, F = resolved dropsugar URLs.
+_COL_E = 4
+_COL_F = 5
+
+# Days from the sheet's Friday to the blackout expiry. The item airs that
+# weekend (Fri..Sun = Friday+2); it stays hidden through the *following* weekend
+# (Sun = Friday+9), lifting the Monday after (Friday+10, 00:00).
+_BLACKOUT_DAYS = 10
+
+
+def _sheet_weekend_dates(
+    name: str, today: _dt.date
+) -> Optional[tuple[_dt.date, _dt.date]]:
+    """Return (friday, sunday) for a ``M.D-M.D`` sheet name, or None.
+
+    The sheet name carries no year, so the year is inferred as the nearest
+    occurrence to ``today`` (handles year-boundary sheets like ``12.26-12.27``).
+    """
+    m = _SHEET_DATE_RE.match(name.strip())
+    if not m:
+        return None
+    month, day = int(m.group(1)), int(m.group(2))
+    best: Optional[_dt.date] = None
+    for year in (today.year - 1, today.year, today.year + 1):
+        try:
+            cand = _dt.date(year, month, day)
+        except ValueError:
+            continue
+        if best is None or abs((cand - today).days) < abs((best - today).days):
+            best = cand
+    if best is None:
+        return None
+    return best, best + _dt.timedelta(days=2)
+
+
+def _expiry_for_friday(friday: _dt.date) -> str:
+    """Blackout expiry (SQLite-comparable ``YYYY-MM-DD HH:MM:SS``) for a weekend."""
+    monday = friday + _dt.timedelta(days=_BLACKOUT_DAYS)
+    return _dt.datetime.combine(monday, _dt.time.min).isoformat(sep=" ")
+
+
+def scan_workbook_blackouts(wb_bytes: bytes, today: _dt.date) -> tuple[list[dict], int]:
+    """Return (blackouts, sheets_scanned) for current/future weekend sheets.
+
+    ``blackouts`` is a list of ``{"token", "reason", "expires_at"}``; a token
+    seen across multiple sheets keeps the latest expiry.
+    """
+    import openpyxl
+
+    wb = openpyxl.load_workbook(io.BytesIO(wb_bytes), read_only=True, data_only=True)
+    try:
+        found: dict[str, dict] = {}
+        sheets_scanned = 0
+        for name in wb.sheetnames:
+            dates = _sheet_weekend_dates(name, today)
+            if not dates:
+                continue
+            friday, sunday = dates
+            if sunday < today:  # weekend already fully past
+                continue
+            sheets_scanned += 1
+            expires_at = _expiry_for_friday(friday)
+            reason = f"weekend:{name.strip()}"
+            ws = wb[name]
+            for row in ws.iter_rows(values_only=True):
+                for idx in (_COL_E, _COL_F):
+                    if len(row) <= idx or row[idx] is None:
+                        continue
+                    val = str(row[idx]).strip()
+                    if not val or not is_dropsugar(val):
+                        continue
+                    token = extract_dropsugar_token(val)
+                    if not token:
+                        continue
+                    prev = found.get(token)
+                    if prev is None or expires_at > prev["expires_at"]:
+                        found[token] = {
+                            "token": token,
+                            "reason": reason,
+                            "expires_at": expires_at,
+                        }
+        return list(found.values()), sheets_scanned
+    finally:
+        wb.close()
+
+
+def run(params: dict, *, config, progress=None) -> dict:
+    """Resolve upcoming-weekend dropsugar URLs into blackout entries.
+
+    Source precedence mirrors :func:`fetchurls.run`:
+      1. ``params['workbook_path']`` (local override)
+      2. SharePoint via Graph when ``config.fetchurls.sharepoint_*`` are set
+      3. ``config.fetchurls.workbook_path`` (local fallback)
+
+    Returns ``{"source", "sheets_scanned", "blackouts": [...]}``. Never writes
+    the workbook or downloads media.
+    """
+    from pathlib import Path
+
+    def _emit(detail: dict) -> None:
+        if progress:
+            progress(detail)
+
+    cfg = getattr(config, "fetchurls", None)
+    local_override = params.get("workbook_path") or ""
+    sp_tenant = getattr(cfg, "sharepoint_tenant_id", "") if cfg else ""
+    sp_client = getattr(cfg, "sharepoint_client_id", "") if cfg else ""
+    sp_share = getattr(cfg, "sharepoint_sharing_url", "") if cfg else ""
+    sp_cache = getattr(cfg, "token_cache_path", "") if cfg else ""
+    cfg_local = getattr(cfg, "workbook_path", "") if cfg else ""
+
+    use_sharepoint = bool(sp_tenant and sp_client and sp_share) and not local_override
+
+    if use_sharepoint:
+        _emit({"phase": "auth", "source": "sharepoint"})
+        token = acquire_graph_token_silent(sp_tenant, sp_client, sp_cache)
+        if not token:
+            raise RuntimeError(
+                "SharePoint authentication unavailable: no valid token in the MSAL "
+                "cache. Run a one-time sign-in on the server: "
+                "python -m kryten_webqueue.jobs.fetchurls_auth"
+            )
+        _emit({"phase": "download", "source": "sharepoint"})
+        wb_bytes, _drive_id, _item_id = download_sharepoint_xlsx(token, sp_share)
+        source = "sharepoint"
+    else:
+        workbook_path = local_override or cfg_local
+        if not workbook_path:
+            raise RuntimeError(
+                "catalog_blackout needs a workbook source: configure "
+                "fetchurls.sharepoint_* (recommended) or fetchurls.workbook_path."
+            )
+        wb_file = Path(workbook_path)
+        if not wb_file.exists():
+            raise RuntimeError(f"Workbook not found: {wb_file}")
+        wb_bytes = wb_file.read_bytes()
+        source = "local"
+
+    _emit({"phase": "scanning"})
+    blackouts, sheets_scanned = scan_workbook_blackouts(wb_bytes, _dt.date.today())
+    _emit(
+        {
+            "phase": "done",
+            "sheets_scanned": sheets_scanned,
+            "blackouts": len(blackouts),
+        }
+    )
+    return {
+        "source": source,
+        "sheets_scanned": sheets_scanned,
+        "blackouts": blackouts,
+    }

{kryten_webqueue-0.40.4 → kryten_webqueue-0.41.0}/kryten_webqueue/jobs/tasks.py

@@ -668,6 +668,76 @@ async def motd_posters_job(params: dict, ctx):
     )
 
 
+# ── Catalog blackout (weekend visibility) job ──────────────────────────────────
+
+
+CATALOG_BLACKOUT_SCHEMA = [
+    {
+        "name": "dry_run",
+        "type": "bool",
+        "default": False,
+        "label": "Dry run (report only, no DB writes)",
+    },
+    {
+        "name": "workbook_path",
+        "type": "string",
+        "default": None,
+        "label": "Local workbook path (override SharePoint)",
+    },
+]
+
+
+async def catalog_blackout_job(params: dict, ctx) -> dict:
+    """Hide upcoming-weekend dropsugar items from regular users (blackout window).
+
+    Scans the workbook's current/future weekend sheets (columns E & F) for
+    dropsugar URLs, resolves them to friendly_tokens, and blacks each out until
+    the end of the *following* weekend so replays stay hidden through that week.
+    Downloads nothing — a pure catalog-visibility maintenance chore. Admins
+    still see (dimmed) blacked-out items and can queue them manually.
+    """
+    result = await _run_vendored(
+        "kryten_webqueue.integrations.cmsutils.blackout_scan",
+        params,
+        ctx,
+        deps=["openpyxl", "requests"],
+    )
+    blackouts = result.get("blackouts") or []
+    dry_run = str(params.get("dry_run", "")).lower() in ("1", "true") or (
+        params.get("dry_run") is True
+    )
+
+    applied = 0
+    if not dry_run:
+        for b in blackouts:
+            await ctx.db.upsert_blackout(
+                b["token"], reason=b["reason"], expires_at=b["expires_at"]
+            )
+            applied += 1
+    pruned = 0 if dry_run else await ctx.db.prune_expired_blackouts()
+    active = await ctx.db.count_active_blackouts()
+
+    logger.info(
+        "catalog_blackout: scanned %d sheet(s), %d token(s) found, "
+        "%d applied, %d pruned, %d active",
+        result.get("sheets_scanned", 0),
+        len(blackouts),
+        applied,
+        pruned,
+        active,
+    )
+    return {
+        "source": result.get("source"),
+        "sheets_scanned": result.get("sheets_scanned", 0),
+        "found": len(blackouts),
+        "applied": applied,
+        "pruned": pruned,
+        "active": active,
+        "dry_run": dry_run,
+        "sample": blackouts[:25],
+    }
+
+
 # ── Fetch queue jobs ───────────────────────────────────────────────────────────