kryten-webqueue 0.4.5__tar.gz → 0.5.0__tar.gz

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 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).
 
+## [0.5.0] - 2026-06-04
+
+### Added
+
+- **Queue as Admin** — Admin users (rank ≥ 3) now see a "Queue as Admin" button on catalog cards. It queues the item at zero cost in the first available non-pay slot (top of the free section, below any paid items), treating it exactly like a non-paid item and skipping all economy interaction. New route `POST /admin/queue/add` and `insert_admin_queue()` ordering helper
+- **Channel announcement on successful queue** — After an item is successfully queued and positioned, the channel chat receives `"<title> has been queued in position <N> by <user>"`, where position counts from the currently-playing item (position 0), so position 1 is the next item to play. Added `ApiGateClient.send_chat()`
+
+### Fixed
+
+- **Wrong manifest URL stored during catalog sync** — `_build_manifest_url()` was producing the MediaCMS watch/detail page URL (`/view?m=TOKEN`, which returns HTTP 302) instead of the real CyTube manifest (`/api/v1/media/cytube/TOKEN.json?format=json`). CyTube rejected the 302 with "Expected HTTP 200 OK, not 302 Found", causing every queue attempt to fail. Existing rows are corrected on the next startup sync
+- **queueFail now surfaced from the command response** — Instead of relying on a timeout, the Robot's `addvideo` command response now carries the CyTube `queueFail` reason. The api-gate returns it as HTTP 422 and webqueue refunds the spend and reports the actual reason. webqueue no longer needs to subscribe to the `kryten.events.cytube.channel-z.queuefail` events channel
+- **Refund when an item cannot be positioned** — If `playlist_move` fails after a successful add, the spend is now refunded and the mis-placed item is removed, rather than leaving a paid item in the wrong slot
+
+[0.5.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.5.0
+
+## [0.4.6] - 2026-06-04
+
+### Fixed
+
+- **Wrong media ID sent to CyTube** — `/queue/add` and `/queue/playnext` were passing `friendly_token` (the MediaCMS slug, e.g. `"my-movie-2024"`) as the `id` field for CyTube custom media type `"cm"`. CyTube requires the manifest URL as the ID; the slug was silently rejected, the `queue` confirmation event never fired, the Robot waited 8 seconds, and kryten-py's matching 8-second timeout fired first giving a 504. Fixed by passing `item["manifest_url"]` as `media_id` to CyTube and threading `friendly_token` separately through `insert_pay_queue` / `insert_pay_playnext` for spend/history records
+
+[0.4.6]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.4.6
+
 ## [0.4.5] - 2026-06-04
 
 ### Fixed

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/PKG-INFO

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

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/deploy/nginx-queue.conf

@@ -6,7 +6,7 @@ server {
     ssl_certificate     /etc/letsencrypt/live/queue.dropsugar.co/fullchain.pem;
     ssl_certificate_key /etc/letsencrypt/live/queue.dropsugar.co/privkey.pem;
     ssl_protocols       TLSv1.2 TLSv1.3;
-    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
+    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128it-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
     ssl_prefer_server_ciphers off;
     ssl_session_cache   shared:SSL:10m;
     ssl_session_timeout 1d;

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/kryten_webqueue/api_gate/client.py

@@ -73,6 +73,9 @@ class ApiGateClient:
 
     # --- Chat ---
 
+    async def send_chat(self, message: str) -> dict:
+        return await self.post("/chat/send", json={"message": message})
+
     async def send_pm(self, username: str, message: str) -> dict:
         return await self.post("/chat/pm", json={"username": username, "message": message})
 

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/kryten_webqueue/catalog/sync.py

@@ -138,6 +138,12 @@ class CatalogSync:
             await asyncio.sleep(0.25)
 
     def _build_manifest_url(self, media: dict) -> str:
-        # Use the MediaCMS watch page URL (e.g. https://www.dropsugar.co/view?m=TOKEN)
+        # CyTube custom media ("cm") requires the manifest JSON URL, NOT the
+        # human watch page (/view?m=TOKEN). MediaCMS exposes a CyTube manifest at
+        # /api/v1/media/cytube/<token>.json?format=json
+        token = media.get("friendly_token")
+        if token:
+            return f"{self._url}/api/v1/media/cytube/{token}.json?format=json"
+        # Fallback: derive token from the watch URL if friendly_token is missing
         url = media.get("url", "")
         return url if url.startswith("http") else f"{self._url}{url}"

kryten_webqueue-0.5.0/kryten_webqueue/queue/ordering.py

@@ -0,0 +1,364 @@
+import asyncio
+import uuid
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Module-level lock for queue ordering
+_queue_lock = asyncio.Lock()
+
+
+def _add_failure_reason(add_result: dict | None, exc: httpx.HTTPStatusError | None) -> str:
+    """Extract a human-readable reason from a failed playlist add."""
+    if exc is not None:
+        try:
+            detail = exc.response.json().get("detail")
+            if detail:
+                return str(detail)
+        except Exception:
+            pass
+        return f"playlist add failed ({exc.response.status_code})"
+    if add_result is not None:
+        return str(add_result.get("error", "Failed to add to playlist"))
+    return "Failed to add to playlist"
+
+
+def _announcement_position(shadow, uid: int) -> int | None:
+    """Position of the item for chat announcement.
+
+    Counting starts at the currently-playing item (position 0), so the next
+    item to play is position 1. The shadow mirrors the full CyTube playlist
+    (including the active item at index 0), so the item's shadow index is the
+    announcement number.
+    """
+    for it in shadow.items:
+        if it.get("uid") == uid:
+            return it.get("position")
+    return None
+
+
+async def _announce_queued(api_gate, shadow, *, uid: int, title: str, username: str) -> None:
+    """Announce a successful queue placement to the channel chat."""
+    pos = _announcement_position(shadow, uid)
+    if pos is None:
+        return
+    try:
+        await api_gate.send_chat(f"{title} has been queued in position {pos} by {username}")
+    except Exception:
+        logger.warning("Failed to send queue announcement", exc_info=True)
+
+
+async def insert_pay_queue(
+    *,
+    api_gate,
+    shadow,
+    db,
+    username: str,
+    media_type: str,
+    media_id: str,
+    friendly_token: str | None = None,
+    title: str,
+    duration_sec: int,
+    tier: str,
+    z_cost: int,
+) -> dict:
+    """Insert a paid item at the end of the pay-queue section (FIFO)."""
+    async with _queue_lock:
+        request_id = str(uuid.uuid4())
+
+        # Spend currency (api-gate _unwrap strips the success envelope;
+        # raise_for_status propagates failures as httpx.HTTPStatusError)
+        try:
+            await api_gate.queue_spend(
+                username=username,
+                duration_sec=duration_sec,
+                tier=tier,
+                request_id=request_id,
+            )
+        except httpx.HTTPStatusError as exc:
+            return {"success": False, "error": f"Spend failed: {exc.response.status_code}"}
+
+        # Find position: after last pay item, or prepend if none
+        last_pay_uid = await db.get_last_pay_uid()
+        position = "end" if not last_pay_uid else str(last_pay_uid)
+
+        # Add to CyTube playlist
+        try:
+            add_result = await api_gate.playlist_add(
+                media_type=media_type,
+                media_id=media_id,
+                position=position,
+            )
+        except httpx.HTTPStatusError as exc:
+            try:
+                await api_gate.queue_refund(username=username, request_id=request_id, reason="playlist_add_failed")
+            except Exception:
+                pass
+            return {"success": False, "error": _add_failure_reason(None, exc)}
+        if not add_result.get("success"):
+            # Refund on failure
+            try:
+                await api_gate.queue_refund(username=username, request_id=request_id, reason="add_failed")
+            except Exception:
+                pass
+            return {"success": False, "error": _add_failure_reason(add_result, None)}
+
+        uid = add_result["uid"]
+
+        # Move after last pay UID if needed; refund + remove if positioning fails
+        if last_pay_uid:
+            try:
+                await api_gate.playlist_move(uid, last_pay_uid)
+            except httpx.HTTPStatusError:
+                try:
+                    await api_gate.queue_refund(username=username, request_id=request_id, reason="move_failed")
+                except Exception:
+                    pass
+                try:
+                    await api_gate.playlist_delete(uid)
+                except Exception:
+                    pass
+                return {"success": False, "error": "Failed to position item in queue"}
+
+        # Record spend
+        _ft = friendly_token if friendly_token is not None else (media_id if media_type == "cm" else None)
+        await db.save_spend_request(
+            request_id, username=username, uid=uid,
+            friendly_token=_ft,
+            tier=tier, z_cost=z_cost,
+        )
+
+        # Update local shadow
+        item = {
+            "uid": uid,
+            "title": title,
+            "media_type": media_type,
+            "media_id": media_id,
+            "duration_sec": duration_sec,
+            "is_pay": True,
+            "paid_by": username,
+            "tier": tier,
+            "z_cost": z_cost,
+            "schedule_id": None,
+        }
+        # Position after last pay
+        if last_pay_uid:
+            pos = await db.get_shadow_position_after(last_pay_uid)
+        else:
+            pos = len(shadow.items)
+        await shadow.insert_at(item, pos)
+
+        # Queue history
+        await db.add_queue_history(
+            username=username, friendly_token=_ft,
+            title=title, tier=tier, z_cost=z_cost,
+        )
+
+        # Announce placement to the channel
+        await _announce_queued(api_gate, shadow, uid=uid, title=title, username=username)
+
+        return {"success": True, "uid": uid, "request_id": request_id}
+
+
+async def insert_pay_playnext(
+    *,
+    api_gate,
+    shadow,
+    db,
+    username: str,
+    media_type: str,
+    media_id: str,
+    friendly_token: str | None = None,
+    title: str,
+    duration_sec: int,
+    tier: str,
+    z_cost: int,
+) -> dict:
+    """Insert a paid item at position 0 (play next)."""
+    async with _queue_lock:
+        request_id = str(uuid.uuid4())
+
+        # Spend currency (api-gate _unwrap strips the success envelope;
+        # raise_for_status propagates failures as httpx.HTTPStatusError)
+        try:
+            await api_gate.queue_spend(
+                username=username,
+                duration_sec=duration_sec,
+                tier=tier,
+                request_id=request_id,
+            )
+        except httpx.HTTPStatusError as exc:
+            return {"success": False, "error": f"Spend failed: {exc.response.status_code}"}
+
+        # Add to CyTube playlist at prepend position
+        try:
+            add_result = await api_gate.playlist_add(
+                media_type=media_type,
+                media_id=media_id,
+                position="end",
+            )
+        except httpx.HTTPStatusError as exc:
+            try:
+                await api_gate.queue_refund(username=username, request_id=request_id, reason="playlist_add_failed")
+            except Exception:
+                pass
+            return {"success": False, "error": _add_failure_reason(None, exc)}
+        if not add_result.get("success"):
+            try:
+                await api_gate.queue_refund(username=username, request_id=request_id, reason="add_failed")
+            except Exception:
+                pass
+            return {"success": False, "error": _add_failure_reason(add_result, None)}
+
+        uid = add_result["uid"]
+
+        # Move to front; refund + remove if positioning fails
+        try:
+            await api_gate.playlist_move(uid, "prepend")
+        except httpx.HTTPStatusError:
+            try:
+                await api_gate.queue_refund(username=username, request_id=request_id, reason="move_failed")
+            except Exception:
+                pass
+            try:
+                await api_gate.playlist_delete(uid)
+            except Exception:
+                pass
+            return {"success": False, "error": "Failed to position item in queue"}
+
+        # Record spend
+        _ft = friendly_token if friendly_token is not None else (media_id if media_type == "cm" else None)
+        await db.save_spend_request(
+            request_id, username=username, uid=uid,
+            friendly_token=_ft,
+            tier=tier, z_cost=z_cost,
+        )
+
+        # Update local shadow at position 0
+        item = {
+            "uid": uid,
+            "title": title,
+            "media_type": media_type,
+            "media_id": media_id,
+            "duration_sec": duration_sec,
+            "is_pay": True,
+            "paid_by": username,
+            "tier": tier,
+            "z_cost": z_cost,
+            "schedule_id": None,
+        }
+        await shadow.insert_at(item, 0)
+
+        await db.add_queue_history(
+            username=username, friendly_token=_ft,
+            title=title, tier=tier, z_cost=z_cost,
+        )
+
+        # Announce placement to the channel
+        await _announce_queued(api_gate, shadow, uid=uid, title=title, username=username)
+
+        return {"success": True, "uid": uid, "request_id": request_id}
+
+
+async def insert_admin_queue(
+    *,
+    api_gate,
+    shadow,
+    db,
+    username: str,
+    media_type: str,
+    media_id: str,
+    friendly_token: str | None = None,
+    title: str,
+    duration_sec: int,
+) -> dict:
+    """Insert a zero-cost admin item in the first available non-pay slot.
+
+    Treated exactly like a non-paid item (no economy interaction). It is placed
+    immediately after the last paid item, i.e. at the top of the free section.
+    """
+    async with _queue_lock:
+        # First available non-pay slot is right after the last pay item.
+        last_pay_uid = await db.get_last_pay_uid()
+        position = "end" if not last_pay_uid else str(last_pay_uid)
+
+        # Add to CyTube playlist
+        try:
+            add_result = await api_gate.playlist_add(
+                media_type=media_type,
+                media_id=media_id,
+                position=position,
+            )
+        except httpx.HTTPStatusError as exc:
+            return {"success": False, "error": _add_failure_reason(None, exc)}
+        if not add_result.get("success"):
+            return {"success": False, "error": _add_failure_reason(add_result, None)}
+
+        uid = add_result["uid"]
+
+        # Move to the top of the free section if there are pay items above
+        if last_pay_uid:
+            try:
+                await api_gate.playlist_move(uid, last_pay_uid)
+            except httpx.HTTPStatusError:
+                try:
+                    await api_gate.playlist_delete(uid)
+                except Exception:
+                    pass
+                return {"success": False, "error": "Failed to position item in queue"}
+
+        _ft = friendly_token if friendly_token is not None else (media_id if media_type == "cm" else None)
+
+        # Update local shadow as a non-paid item
+        item = {
+            "uid": uid,
+            "title": title,
+            "media_type": media_type,
+            "media_id": media_id,
+            "duration_sec": duration_sec,
+            "is_pay": False,
+            "paid_by": None,
+            "tier": None,
+            "z_cost": None,
+            "schedule_id": None,
+        }
+        if last_pay_uid:
+            pos = await db.get_shadow_position_after(last_pay_uid)
+        else:
+            pos = len(shadow.items)
+        await shadow.insert_at(item, pos)
+
+        # Queue history (zero cost, admin tier)
+        await db.add_queue_history(
+            username=username, friendly_token=_ft,
+            title=title, tier="admin", z_cost=0,
+        )
+
+        # Announce placement to the channel
+        await _announce_queued(api_gate, shadow, uid=uid, title=title, username=username)
+
+        return {"success": True, "uid": uid}
+
+
+async def refund_item(*, api_gate, db, uid: int, reason: str) -> bool:
+    """Refund a paid queue item."""
+    request_id = await db.get_request_id_for_uid(uid)
+    if not request_id:
+        return False
+
+    # Look up the spend to find username
+    row = await db._fetch_one("SELECT username FROM spend_requests WHERE request_id=?", [request_id])
+    if not row:
+        return False
+
+    result = await api_gate.queue_refund(
+        username=row["username"],
+        request_id=request_id,
+        reason=reason,
+    )
+    if result.get("success"):
+        await db.mark_spend_refunded(request_id)
+        return True
+    return False

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/kryten_webqueue/routes/admin_queue.py

@@ -1,11 +1,48 @@
 from fastapi import APIRouter, Request, Depends, HTTPException
 
 from ..auth.session import require_admin
-from ..queue.ordering import refund_item
+from ..queue.ordering import refund_item, insert_admin_queue
 
 router = APIRouter(prefix="/admin/queue", tags=["admin"])
 
 
+@router.post("/add")
+async def admin_add(request: Request, user: dict = Depends(require_admin)):
+    """Queue an item as admin: zero cost, first available non-pay slot."""
+    body = await request.json()
+    friendly_token = body.get("friendly_token")
+    if not friendly_token:
+        raise HTTPException(400, "friendly_token required")
+
+    db = request.app.state.db
+    api_gate = request.app.state.api_gate
+    shadow = request.app.state.shadow
+
+    # Check pre-fire lock
+    if await db.is_pre_fire_lock_active():
+        raise HTTPException(423, "Queue is locked: scheduled playlist firing soon")
+
+    item = await db.get_item(friendly_token)
+    if not item:
+        raise HTTPException(404, "Item not found in catalog")
+
+    result = await insert_admin_queue(
+        api_gate=api_gate,
+        shadow=shadow,
+        db=db,
+        username=user["username"],
+        media_type="cm",
+        media_id=item["manifest_url"],
+        friendly_token=friendly_token,
+        title=item["title"],
+        duration_sec=item["duration_sec"],
+    )
+
+    if not result["success"]:
+        raise HTTPException(400, result.get("error", "Admin queue add failed"))
+    return result
+
+
 @router.post("/clear")
 async def clear_queue(request: Request, user: dict = Depends(require_admin)):
     """Clear the CyTube playlist (refunds all pay items)."""

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/kryten_webqueue/routes/queue.py

@@ -56,7 +56,8 @@ async def add_to_queue(request: Request, user: dict = Depends(get_current_user))
         db=db,
         username=user["username"],
         media_type="cm",
-        media_id=friendly_token,
+        media_id=item["manifest_url"],
+        friendly_token=friendly_token,
         title=item["title"],
         duration_sec=item["duration_sec"],
         tier=tier,
@@ -111,7 +112,8 @@ async def play_next(request: Request, user: dict = Depends(get_current_user)):
         db=db,
         username=user["username"],
         media_type="cm",
-        media_id=friendly_token,
+        media_id=item["manifest_url"],
+        friendly_token=friendly_token,
         title=item["title"],
         duration_sec=item["duration_sec"],
         tier=tier,

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/kryten_webqueue/templates/catalog/browse.html

@@ -48,6 +48,9 @@
         <div class="card-actions">
             <button class="btn btn-sm btn-queue" onclick="queueItem('{{ item.friendly_token }}')">Queue</button>
             <button class="btn btn-sm btn-playnext" onclick="playNext('{{ item.friendly_token }}')">Play Next</button>
+            {% if user.rank >= 3 %}
+            <button class="btn btn-sm btn-admin" onclick="queueAsAdmin('{{ item.friendly_token }}')">Queue as Admin</button>
+            {% endif %}
         </div>
     </div>
     {% endfor %}
@@ -126,5 +129,24 @@ async function playNext(token) {
         showToast(`Network error: ${e.message}`, 'error');
     }
 }
+
+async function queueAsAdmin(token) {
+    try {
+        const resp = await fetch('/admin/queue/add', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            credentials: 'same-origin',
+            body: JSON.stringify({friendly_token: token})
+        });
+        const data = await resp.json();
+        if (resp.ok) {
+            showToast('Queued as admin!');
+        } else {
+            showToast(data.detail || `Failed (${resp.status})`, 'error');
+        }
+    } catch (e) {
+        showToast(`Network error: ${e.message}`, 'error');
+    }
+}
 </script>
 {% endblock %}

{kryten_webqueue-0.4.5 → kryten_webqueue-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kryten-webqueue"
-version = "0.4.5"
+version = "0.5.0"
 description = "Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube"
 readme = "README.md"
 license = "MIT"

kryten_webqueue-0.4.5/kryten_webqueue/queue/ordering.py

@@ -1,212 +0,0 @@
-import asyncio
-import uuid
-import logging
-
-import httpx
-
-logger = logging.getLogger(__name__)
-
-# Module-level lock for queue ordering
-_queue_lock = asyncio.Lock()
-
-
-async def insert_pay_queue(
-    *,
-    api_gate,
-    shadow,
-    db,
-    username: str,
-    media_type: str,
-    media_id: str,
-    title: str,
-    duration_sec: int,
-    tier: str,
-    z_cost: int,
-) -> dict:
-    """Insert a paid item at the end of the pay-queue section (FIFO)."""
-    async with _queue_lock:
-        request_id = str(uuid.uuid4())
-
-        # Spend currency (api-gate _unwrap strips the success envelope;
-        # raise_for_status propagates failures as httpx.HTTPStatusError)
-        try:
-            await api_gate.queue_spend(
-                username=username,
-                duration_sec=duration_sec,
-                tier=tier,
-                request_id=request_id,
-            )
-        except httpx.HTTPStatusError as exc:
-            return {"success": False, "error": f"Spend failed: {exc.response.status_code}"}
-
-        # Find position: after last pay item, or prepend if none
-        last_pay_uid = await db.get_last_pay_uid()
-        position = "end" if not last_pay_uid else str(last_pay_uid)
-
-        # Add to CyTube playlist
-        try:
-            add_result = await api_gate.playlist_add(
-                media_type=media_type,
-                media_id=media_id,
-                position=position,
-            )
-        except httpx.HTTPStatusError:
-            try:
-                await api_gate.queue_refund(username=username, request_id=request_id, reason="playlist_add_failed")
-            except Exception:
-                pass
-            return {"success": False, "error": "Failed to add to playlist"}
-        if not add_result.get("success"):
-            # Refund on failure
-            try:
-                await api_gate.queue_refund(username=username, request_id=request_id, reason="add_failed")
-            except Exception:
-                pass
-            return {"success": False, "error": "Failed to add to playlist"}
-
-        uid = add_result["uid"]
-
-        # Move after last pay UID if needed
-        if last_pay_uid:
-            await api_gate.playlist_move(uid, last_pay_uid)
-
-        # Record spend
-        await db.save_spend_request(
-            request_id, username=username, uid=uid,
-            friendly_token=media_id if media_type == "cm" else None,
-            tier=tier, z_cost=z_cost,
-        )
-
-        # Update local shadow
-        item = {
-            "uid": uid,
-            "title": title,
-            "media_type": media_type,
-            "media_id": media_id,
-            "duration_sec": duration_sec,
-            "is_pay": True,
-            "paid_by": username,
-            "tier": tier,
-            "z_cost": z_cost,
-            "schedule_id": None,
-        }
-        # Position after last pay
-        if last_pay_uid:
-            pos = await db.get_shadow_position_after(last_pay_uid)
-        else:
-            pos = len(shadow.items)
-        await shadow.insert_at(item, pos)
-
-        # Queue history
-        await db.add_queue_history(
-            username=username, friendly_token=media_id if media_type == "cm" else None,
-            title=title, tier=tier, z_cost=z_cost,
-        )
-
-        return {"success": True, "uid": uid, "request_id": request_id}
-
-
-async def insert_pay_playnext(
-    *,
-    api_gate,
-    shadow,
-    db,
-    username: str,
-    media_type: str,
-    media_id: str,
-    title: str,
-    duration_sec: int,
-    tier: str,
-    z_cost: int,
-) -> dict:
-    """Insert a paid item at position 0 (play next)."""
-    async with _queue_lock:
-        request_id = str(uuid.uuid4())
-
-        # Spend currency (api-gate _unwrap strips the success envelope;
-        # raise_for_status propagates failures as httpx.HTTPStatusError)
-        try:
-            await api_gate.queue_spend(
-                username=username,
-                duration_sec=duration_sec,
-                tier=tier,
-                request_id=request_id,
-            )
-        except httpx.HTTPStatusError as exc:
-            return {"success": False, "error": f"Spend failed: {exc.response.status_code}"}
-
-        # Add to CyTube playlist at prepend position
-        try:
-            add_result = await api_gate.playlist_add(
-                media_type=media_type,
-                media_id=media_id,
-                position="end",
-            )
-        except httpx.HTTPStatusError:
-            try:
-                await api_gate.queue_refund(username=username, request_id=request_id, reason="playlist_add_failed")
-            except Exception:
-                pass
-            return {"success": False, "error": "Failed to add to playlist"}
-        if not add_result.get("success"):
-            try:
-                await api_gate.queue_refund(username=username, request_id=request_id, reason="add_failed")
-            except Exception:
-                pass
-            return {"success": False, "error": "Failed to add to playlist"}
-
-        uid = add_result["uid"]
-
-        # Move to front
-        await api_gate.playlist_move(uid, "prepend")
-
-        # Record spend
-        await db.save_spend_request(
-            request_id, username=username, uid=uid,
-            friendly_token=media_id if media_type == "cm" else None,
-            tier=tier, z_cost=z_cost,
-        )
-
-        # Update local shadow at position 0
-        item = {
-            "uid": uid,
-            "title": title,
-            "media_type": media_type,
-            "media_id": media_id,
-            "duration_sec": duration_sec,
-            "is_pay": True,
-            "paid_by": username,
-            "tier": tier,
-            "z_cost": z_cost,
-            "schedule_id": None,
-        }
-        await shadow.insert_at(item, 0)
-
-        await db.add_queue_history(
-            username=username, friendly_token=media_id if media_type == "cm" else None,
-            title=title, tier=tier, z_cost=z_cost,
-        )
-
-        return {"success": True, "uid": uid, "request_id": request_id}
-
-
-async def refund_item(*, api_gate, db, uid: int, reason: str) -> bool:
-    """Refund a paid queue item."""
-    request_id = await db.get_request_id_for_uid(uid)
-    if not request_id:
-        return False
-
-    # Look up the spend to find username
-    row = await db._fetch_one("SELECT username FROM spend_requests WHERE request_id=?", [request_id])
-    if not row:
-        return False
-
-    result = await api_gate.queue_refund(
-        username=row["username"],
-        request_id=request_id,
-        reason=reason,
-    )
-    if result.get("success"):
-        await db.mark_spend_refunded(request_id)
-        return True
-    return False