diff --git a/backend/api/routes/admin.py b/backend/api/routes/admin.py index a7c679a5..d686503f 100644 --- a/backend/api/routes/admin.py +++ b/backend/api/routes/admin.py @@ -2995,6 +2995,16 @@ def override_audio_source( "audio_search_count", "remote_search_id", "audio_selection", + # A pending duration confirm / duration estimate belongs to the OLD source. + "duration_confirmed", + "duration_confirm_reason", + "pending_additional_credits", + "duration_estimate_seconds", + "duration_estimate_source", + "duration_actual_seconds", + # Re-arm the /select delta charge for the new source. credits_charged is + # KEPT, so /select charges only target - credits_charged (no double charge). + "select_charge_applied", ] update_payload = {} @@ -3049,8 +3059,11 @@ def override_audio_source( # Transition to awaiting_audio_selection with results new_status = "awaiting_audio_selection" + # Dotted paths MERGE: replacing the whole map would wipe billing state + # (credits_charged / payment_bypassed) — the keys_to_clear list above is + # the intended reset. job_ref.update({ - "state_data": state_data_update, + **{f"state_data.{k}": v for k, v in state_data_update.items()}, "status": new_status, "message": f"Found {search_results_count} audio sources - select one", "progress": 10, diff --git a/backend/api/routes/audio_search.py b/backend/api/routes/audio_search.py index 0b851702..0d5ba93e 100644 --- a/backend/api/routes/audio_search.py +++ b/backend/api/routes/audio_search.py @@ -942,16 +942,16 @@ async def search_audio( # Store results in job state_data, including remote_search_id if available results_dicts = [r.to_dict() for r in search_results] + # Dotted paths MERGE into state_data (keeps create_job's credits_charged / + # payment_bypassed — never replace the whole map after create_job). state_data_update = { - 'audio_search_results': results_dicts, - 'audio_search_count': len(results_dicts), + 'state_data.audio_search_results': results_dicts, + 'state_data.audio_search_count': len(results_dicts), } # Store remote_search_id for use during download (important for concurrent requests) if audio_search_service.last_remote_search_id: - state_data_update['remote_search_id'] = audio_search_service.last_remote_search_id - job_manager.update_job(job_id, { - 'state_data': state_data_update - }) + state_data_update['state_data.remote_search_id'] = audio_search_service.last_remote_search_id + job_manager.update_job(job_id, state_data_update) # If auto_download, select best and start processing if body.auto_download: @@ -1602,9 +1602,14 @@ async def select_audio_source( # Compute how many credits this job should total after selecting this result. # If duration is unknown, keep target_total == credits_charged so owed = 0. - credits_charged = int((job.state_data or {}).get('credits_charged', 1)) + from backend.services.job_credits import get_credits_charged, is_payment_bypassed + credits_charged = get_credits_charged(job) target_total = duration_to_credits(duration) if duration is not None else credits_charged - owed = max(0, target_total - credits_charged) + # Admin / made-for-you / tenant / no-email jobs are never billed consumer + # credits: owe nothing, and keep credits_charged at 0 so no later refund + # pays out credits that were never debited. + payment_bypassed = is_payment_bypassed(job) + owed = 0 if payment_bypassed else max(0, target_total - credits_charged) # Anti-mismatch guard: if the client sent an expected total, verify it still matches. if body.acknowledged_credits is not None and body.acknowledged_credits != target_total: @@ -1628,9 +1633,12 @@ async def select_audio_source( # Persist updated credit total, duration estimate, and idempotency flag. state_update: dict = { - "state_data.credits_charged": target_total, + "state_data.credits_charged": 0 if payment_bypassed else target_total, "state_data.select_charge_applied": True, } + if payment_bypassed: + # Make legacy (flag-wiped) bypassed jobs explicit from here on. + state_update["state_data.payment_bypassed"] = True if duration is not None: state_update["state_data.duration_estimate_seconds"] = duration state_update["state_data.duration_estimate_source"] = "search_metadata" diff --git a/backend/api/routes/internal.py b/backend/api/routes/internal.py index 46f44fbf..cf8bca6c 100644 --- a/backend/api/routes/internal.py +++ b/backend/api/routes/internal.py @@ -564,8 +564,10 @@ async def check_idle_reminder( if success: # Mark reminder as sent (prevents duplicate sends) + # Dotted path: a read-modify-write of the whole map could clobber a + # concurrent billing update (e.g. confirm-duration's credits_charged). job_manager.firestore.update_job(job_id, { - 'state_data': {**state_data, 'reminder_sent': True} + 'state_data.reminder_sent': True, }) logger.info(f"[job:{job_id}] Sent {action_type} reminder email to {job.user_email}") add_span_event("reminder_sent", {"action_type": action_type}) diff --git a/backend/api/routes/jobs.py b/backend/api/routes/jobs.py index 935d8ee2..80c6c40e 100644 --- a/backend/api/routes/jobs.py +++ b/backend/api/routes/jobs.py @@ -232,9 +232,37 @@ def get_job( if job.status == JobStatus.COMPLETE: job.download_urls = job_manager.get_output_urls(job_id) + _resolve_credits_charged_in_response(job) return job +def _resolve_credits_charged_in_response(job: Job) -> Job: + """Fill state_data.credits_charged in a response for legacy jobs (never persisted).""" + from backend.services.job_credits import with_resolved_credits_charged + + if (job.state_data or {}).get("credits_charged") is None: + job.state_data = with_resolved_credits_charged( + job.state_data, user_email=job.user_email, + tenant_id=job.tenant_id, creation_params=job.creation_params, + ) + return job + + +def _resolve_credits_charged_in_summary(data: Dict[str, Any]) -> Dict[str, Any]: + """Summary-dict variant; drops the projection-only inputs it needed.""" + from backend.services.job_credits import with_resolved_credits_charged + + tenant_id = data.pop("tenant_id", None) + creation_params = data.pop("creation_params", None) + sd = data.get("state_data") + if not isinstance(sd, dict) or sd.get("credits_charged") is None: + data["state_data"] = with_resolved_credits_charged( + sd if isinstance(sd, dict) else {}, user_email=data.get("user_email"), + tenant_id=tenant_id, creation_params=creation_params, + ) + return data + + def _check_job_ownership(job: Job, auth_result: AuthResult) -> bool: """ Check if the authenticated user owns the job or has admin access. @@ -553,6 +581,7 @@ _SUMMARY_STATE_DATA_KEYS = { 'render_pending_capacity', 'cloud_run_retry_pending', 'credits_charged', + 'payment_bypassed', 'pending_additional_credits', 'duration_actual_seconds', 'duration_confirm_reason', @@ -760,6 +789,7 @@ def list_jobs( # Safety-net pruning (in case Firestore returned extra nested keys) jobs_dicts = [_prune_file_urls(_prune_state_data(j)) for j in jobs_dicts] + jobs_dicts = [_resolve_credits_charged_in_summary(j) for j in jobs_dicts] logger.debug(f"Listed {len(jobs_dicts)} summary jobs for user={auth_result.user_email}") return jobs_dicts @@ -786,6 +816,8 @@ def list_jobs( or (own_email and (j.user_email or "").lower() == own_email) ] + for j in jobs: + _resolve_credits_charged_in_response(j) logger.debug(f"Listed {len(jobs)} jobs for user={auth_result.user_email}, admin={auth_result.is_admin}") return jobs except HTTPException: @@ -2343,10 +2375,14 @@ async def retry_job( logger.info(f"Job {job_id}: Has input audio in GCS, restarting from beginning") # Clear error state and any partial progress + # Clear parallel worker progress, but keep billing state: wiping + # credits_charged would make a re-run reconcile re-charge (or a later + # refund under-refund) a job that was already paid for. + from backend.services.job_credits import preserve_billing_state job_manager.update_job(job_id, { 'error_message': None, 'error_details': None, - 'state_data': {}, # Clear parallel worker progress + 'state_data': preserve_billing_state(job.state_data), }) # Reset to DOWNLOADING and trigger audio worker @@ -2989,16 +3025,19 @@ def _create_job_from_search_sync( logger.warning(f"Failed to prepare theme '{effective_theme_id}' for job {job_id}: {e}") # Store search results and remote_search_id in job state_data - # (required by _download_audio_and_trigger_workers) + # (required by _download_audio_and_trigger_workers). + # Dotted paths MERGE into state_data — never write the whole map here: + # create_job already recorded credits_charged / payment_bypassed, and + # wiping them made reconcile and confirm-duration disagree on the charge. state_data_update: Dict[str, Any] = { - 'audio_search_results': search_results, - 'audio_search_count': len(search_results), + 'state_data.audio_search_results': search_results, + 'state_data.audio_search_count': len(search_results), } if session.get('remote_search_id'): - state_data_update['remote_search_id'] = session['remote_search_id'] + state_data_update['state_data.remote_search_id'] = session['remote_search_id'] if body.requires_audio_edit: - state_data_update['requires_audio_edit'] = True - job_manager.update_job(job_id, {'state_data': state_data_update}) + state_data_update['state_data.requires_audio_edit'] = True + job_manager.update_job(job_id, state_data_update) # Transition to DOWNLOADING_AUDIO (skips AWAITING_AUDIO_SELECTION entirely) _validate_and_prepare_selection( @@ -3287,7 +3326,8 @@ async def confirm_duration( # confirm_duration never needs to call duration_to_credits. state_data = job.state_data or {} reason = state_data.get("duration_confirm_reason", "reconcile") - credits_charged = int(state_data.get("credits_charged", 0)) + from backend.services.job_credits import get_credits_charged + credits_charged = get_credits_charged(job) # same default as reconcile/refunds owed = int(state_data.get("pending_additional_credits", 0)) expected_total = credits_charged + owed @@ -3332,10 +3372,12 @@ async def confirm_duration( }, ) else: - # owed == 0: nothing to charge, just mark confirmed. + # owed == 0: nothing to charge, just mark confirmed (and persist the + # resolved charge so legacy jobs carry the explicit field from now on). job_manager.update_job( job_id, { + "state_data.credits_charged": credits_charged, "state_data.duration_confirmed": True, "state_data.pending_additional_credits": 0, }, diff --git a/backend/api/routes/users.py b/backend/api/routes/users.py index cf5094e3..6c9c6cc6 100644 --- a/backend/api/routes/users.py +++ b/backend/api/routes/users.py @@ -1453,13 +1453,15 @@ async def _handle_made_for_you_order( if search_results: # Store search results in state_data for admin to review results_dicts = [r.to_dict() for r in search_results] + # Dotted paths MERGE into state_data (keeps create_job's + # payment_bypassed flag so reconcile never bills an MFY job). state_data_update = { - 'audio_search_results': results_dicts, - 'audio_search_count': len(results_dicts), + 'state_data.audio_search_results': results_dicts, + 'state_data.audio_search_count': len(results_dicts), } if audio_search_service.last_remote_search_id: - state_data_update['remote_search_id'] = audio_search_service.last_remote_search_id - job_manager.update_job(job_id, {'state_data': state_data_update}) + state_data_update['state_data.remote_search_id'] = audio_search_service.last_remote_search_id + job_manager.update_job(job_id, state_data_update) # Transition to AWAITING_AUDIO_SELECTION for admin to choose # Do NOT auto-select or download - admin must review and select diff --git a/backend/services/duration_reconciliation.py b/backend/services/duration_reconciliation.py index 056226d6..a2c4ff97 100644 --- a/backend/services/duration_reconciliation.py +++ b/backend/services/duration_reconciliation.py @@ -12,6 +12,7 @@ from typing import Callable, Optional import logging from backend.services.pricing import duration_to_credits, is_blocked +from backend.services.job_credits import get_credits_charged, is_payment_bypassed from backend.models.job import JobStatus logger = logging.getLogger(__name__) @@ -34,12 +35,14 @@ def reconcile_duration( job = job_manager.get_job(job_id) actual = probe_duration(job) state = dict(job.state_data or {}) - credits_charged = int(state.get("credits_charged", 1)) + # One helper for every reader (legacy jobs lacking the field included) so + # reconcile, confirm-duration and the refund paths agree on the charge. + credits_charged = get_credits_charged(job) # Short-circuit for admin / payment-bypassed jobs: measure duration for # observability but do NOT pause, charge, refund, or cancel regardless of # how long the audio turns out to be. - if state.get("payment_bypassed"): + if is_payment_bypassed(job): if actual is not None: job_manager.update_job(job_id, {"state_data.duration_actual_seconds": actual}) logger.info("Job %s: payment_bypassed=True, skipping reconcile (actual=%s s)", job_id, actual) @@ -56,7 +59,9 @@ def reconcile_duration( user_service.add_credits(job.user_email, amount=credits_charged, reason="duration_over_limit_refund", job_id=job_id) job_manager.update_job(job_id, {"credit_refunded": True}) # suppress cancel_job's built-in 1-credit refund (we already refunded the full charge) - job_manager.cancel_job(job_id, reason="Input audio exceeds the 60-minute limit") + # refund=False: the full charge was refunded above (skip cancel's own refund). + job_manager.cancel_job(job_id, reason="Input audio exceeds the 60-minute limit", + refund=credits_charged == 0) if email_service: email_service.send_duration_confirm_expired( to_email=job.user_email, @@ -80,8 +85,12 @@ def reconcile_duration( return ReconcileResult(action="proceed", actual_seconds=actual) # delta > 0 : owe more credits — pause for explicit re-confirmation. + # Persist credits_charged alongside the delta so every client (web hook, + # mobile) sees the explicit figure and acknowledges the same total that + # confirm-duration expects, even for legacy jobs that lacked the field. job_manager.update_job(job_id, { "state_data.duration_confirm_reason": "reconcile", + "state_data.credits_charged": credits_charged, "state_data.pending_additional_credits": delta, }) job_manager.transition_to_state( diff --git a/backend/services/firestore_service.py b/backend/services/firestore_service.py index b123b385..3f3b7024 100644 --- a/backend/services/firestore_service.py +++ b/backend/services/firestore_service.py @@ -269,7 +269,11 @@ class FirestoreService: 'state_data.render_pending_capacity', 'state_data.cloud_run_retry_pending', 'state_data.credits_charged', + 'state_data.payment_bypassed', 'state_data.pending_additional_credits', + # Inputs for resolving a missing credits_charged (job_credits); the list + # route strips tenant_id/creation_params from the response again. + 'tenant_id', 'creation_params.is_admin', 'state_data.duration_actual_seconds', 'state_data.duration_confirm_reason', 'state_data.batch_id', diff --git a/backend/services/job_credits.py b/backend/services/job_credits.py new file mode 100644 index 00000000..4f467f18 --- /dev/null +++ b/backend/services/job_credits.py @@ -0,0 +1,109 @@ +"""Single source of truth for how many consumer credits a job has been charged. + +``JobManager.create_job`` records ``state_data.credits_charged`` (and +``payment_bypassed=True`` with ``credits_charged=0`` for admin / tenant / +no-email jobs). Duration reconciliation, audio selection, confirm-duration and +the refund paths then keep that running total up to date. + +Every reader MUST go through :func:`get_credits_charged` / +:func:`is_payment_bypassed` so they all agree on the value — in particular for +jobs that lack the field. Before v0.278.2 several create paths (create-from-search, +the audio-search create endpoint, made-for-you orders) replaced the whole +``state_data`` map right after ``create_job`` and so wiped ``credits_charged`` +and ``payment_bypassed``. Readers disagreed about the missing value (reconcile +assumed 1, confirm-duration assumed 0, the stale-review refund assumed 0), so a +paused 15-minute job asked the client to acknowledge 1 credit for a 2-credit job +and 409'd when it acknowledged the true total. + +Legacy default (field missing): we infer what ``create_job`` actually debited, +using the same signals it used to decide whether to charge: + +* ``payment_bypassed`` flag present → 0 +* no ``user_email`` → 0 (create_job never charges) +* ``creation_params.is_admin`` / admin email → 0 (admin & made-for-you jobs) +* ``tenant_id`` set → 0 (tenant-billed; a spoofed, + non-allowlisted tenant header was charged 1, but we deliberately bias toward + NOT refunding credits that may never have been debited) +* otherwise → 1 (every wiping path charged the + default ``JobCreate.credits == 1``; jobs that charged more — URL jobs with a + known duration — always kept the field) +""" +from __future__ import annotations + +from typing import Any, Dict, Mapping, Optional + +# state_data keys that carry billing state. Anything that resets/clears +# state_data (retry-from-scratch, admin source override) must carry these over, +# or a later reconcile/refund would re-derive the charge from scratch. +BILLING_STATE_KEYS = ("credits_charged", "payment_bypassed", "select_charge_applied") + + +def _legacy_unbilled(job: Any) -> bool: + """True if a job lacking ``credits_charged`` was never charged by create_job.""" + user_email = getattr(job, "user_email", None) + if not user_email: + return True + creation_params = getattr(job, "creation_params", None) or {} + if isinstance(creation_params, Mapping) and creation_params.get("is_admin"): + return True + tenant_id = getattr(job, "tenant_id", None) + if isinstance(tenant_id, str) and tenant_id: + return True + try: + from backend.services.auth_service import is_admin_email + + if isinstance(user_email, str) and is_admin_email(user_email): + return True + except Exception: # pragma: no cover - defensive; never block billing reads + pass + return False + + +def get_credits_charged(job: Any) -> int: + """Total consumer credits debited for this job so far (see module docstring).""" + state = getattr(job, "state_data", None) or {} + value = state.get("credits_charged") + if value is not None: + return int(value) + if state.get("payment_bypassed"): + return 0 + return 0 if _legacy_unbilled(job) else 1 + + +def is_payment_bypassed(job: Any) -> bool: + """True if this job is not billed in consumer credits (admin/tenant/no-email). + + Uses the explicit flag, falling back to the legacy inference for jobs whose + ``payment_bypassed`` flag was wiped along with ``credits_charged``. + """ + state = getattr(job, "state_data", None) or {} + if state.get("payment_bypassed"): + return True + if state.get("credits_charged") is None: + return _legacy_unbilled(job) + return False + + +def preserve_billing_state(state_data: Optional[Dict[str, Any]]) -> Dict[str, Any]: + """Subset of ``state_data`` that must survive a state_data reset.""" + state = state_data or {} + return {k: state[k] for k in BILLING_STATE_KEYS if k in state} + + +def with_resolved_credits_charged(state_data: Optional[Dict[str, Any]], *, user_email=None, + tenant_id=None, creation_params=None) -> Dict[str, Any]: + """Copy of ``state_data`` whose ``credits_charged`` is always present (response-only). + + Used by the job read endpoints so web and mobile clients display/acknowledge + exactly the figure the server will use, even for legacy jobs lacking the field. + Never persist the result. + """ + from types import SimpleNamespace + + resolved = dict(state_data or {}) + if resolved.get("credits_charged") is None: + resolved["credits_charged"] = get_credits_charged(SimpleNamespace( + state_data=resolved, user_email=user_email, + tenant_id=tenant_id, creation_params=creation_params, + )) + return resolved diff --git a/backend/services/job_manager.py b/backend/services/job_manager.py index e6bebe9e..df45fce3 100644 --- a/backend/services/job_manager.py +++ b/backend/services/job_manager.py @@ -790,16 +790,15 @@ class JobManager: else: action_type = "instrumental" - # Update state_data with blocking state info (handle None state_data) - existing_state_data = job.state_data or {} - state_data_update = { - 'blocking_state_entered_at': blocking_entered_at, - 'blocking_action_type': action_type, - 'reminder_sent': False, # Will be set to True after reminder is sent - } - + # Update state_data with blocking state info. Dotted paths merge + # server-side — a read-modify-write of the whole map would clobber + # fields written since `job` was read (e.g. reconcile's + # pending_additional_credits / credits_charged just before this + # transition). self.firestore.update_job(job.job_id, { - 'state_data': {**existing_state_data, **state_data_update} + 'state_data.blocking_state_entered_at': blocking_entered_at, + 'state_data.blocking_action_type': action_type, + 'state_data.reminder_sent': False, # Set True after reminder is sent }) # Schedule the idle reminder check via worker service. @@ -1045,8 +1044,8 @@ class JobManager: """ Refund all credits charged for a job if eligible. - Reads ``state_data.credits_charged`` (defaulting to 1 for legacy jobs - that pre-date the field) and refunds that many credits in a single + Reads the charge via ``job_credits.get_credits_charged`` (legacy jobs + lacking the field: 1 if create_job charged them, else 0) and refunds that many credits in a single ``add_credits`` call. Skips refund if: already refunded, no user email, admin-owned job, or credits_charged == 0 (payment_bypassed). Never raises — refund failure must not block the calling operation. @@ -1069,10 +1068,10 @@ class JobManager: return False # Determine how many credits to refund. ``credits_charged`` is set - # at job creation (and updated on duration-confirm). Legacy jobs - # that pre-date the field are guaranteed to be 1-credit jobs, so we - # default to 1. payment_bypassed admin/no-email jobs have - # credits_charged=0 and must not be refunded. + # at job creation (and updated on duration-confirm). Jobs lacking + # the field resolve via job_credits.get_credits_charged (1 if + # create_job charged them, 0 for admin/tenant/no-email). + # payment_bypassed jobs have credits_charged=0 and are not refunded. state_data = job.state_data or {} # A re-run of an already-delivered track (storage-retention # regenerate, admin/theme re-render) was paid for when it first @@ -1086,7 +1085,8 @@ class JobManager: if job.edit_count: logger.info(f"Job {job_id}: edited track was already delivered, skipping refund") return False - credits_charged = int(state_data.get("credits_charged", 1)) + from backend.services.job_credits import get_credits_charged, is_payment_bypassed + credits_charged = 0 if is_payment_bypassed(job) else get_credits_charged(job) if credits_charged == 0: # Admin / payment-bypassed job — nothing to refund. @@ -1360,17 +1360,22 @@ class JobManager: # per-tick cap (which would delay other stalled jobs), and lets it retry. return await get_worker_service().trigger_screens_worker(job_id) - def cancel_job(self, job_id: str, reason: Optional[str] = None) -> bool: + def cancel_job(self, job_id: str, reason: Optional[str] = None, refund: bool = True) -> bool: """ Cancel a job. Only jobs in non-terminal states can be cancelled. Serialized per job within this instance so a double-clicked Cancel can't refund twice. + + ``refund=False`` skips the built-in refund — for callers that have + already refunded the full charge themselves (duration over-limit, + duration-confirm expiry), so a failed ``credit_refunded`` write can't + lead to a second refund here. """ with job_lock(job_id): - return self._cancel_job_unlocked(job_id, reason) + return self._cancel_job_unlocked(job_id, reason, refund=refund) - def _cancel_job_unlocked(self, job_id: str, reason: Optional[str]) -> bool: + def _cancel_job_unlocked(self, job_id: str, reason: Optional[str], refund: bool = True) -> bool: job = self.get_job(job_id) if not job: return False @@ -1391,7 +1396,8 @@ class JobManager: logger.info(f"Job {job_id} cancelled") # Refund credit for cancelled job - self._refund_credit_for_job(job_id, job, reason="job_cancelled") + if refund: + self._refund_credit_for_job(job_id, job, reason="job_cancelled") return True diff --git a/backend/tests/api/test_audio_search_select_pricing.py b/backend/tests/api/test_audio_search_select_pricing.py index e5f2db0e..de3331ca 100644 --- a/backend/tests/api/test_audio_search_select_pricing.py +++ b/backend/tests/api/test_audio_search_select_pricing.py @@ -571,3 +571,132 @@ class TestSelectPricingIdempotencyGuard: assert all_payloads.get("state_data.select_charge_applied") is True, ( f"Expected select_charge_applied=True in update_job payload; got: {all_payloads}" ) + + +class TestSelectNeverChargesBypassedJobs: + """Admin / made-for-you / tenant jobs are never billed consumer credits. + + Now that create paths no longer wipe state_data, credits_charged=0 survives on + bypassed jobs — /select must not read that as "owes the full duration cost". + """ + + _LONG = [{ + "title": "Long Song", "artist": "Artist", "provider": "RED", "quality": "FLAC", + "source_id": "abc999", "target_file": "long.flac", "url": "", "duration": 1500, + }] + + def _assert_no_charge(self, client, jm, us, job): + jm.get_job.return_value = job + resp = _post_select(client) + assert resp.status_code == 200, resp.text + us.deduct_credits.assert_not_called() + update = next(c.args[1] for c in jm.update_job.call_args_list + if "state_data.select_charge_applied" in c.args[1]) + assert update["state_data.credits_charged"] == 0 # nothing to refund later + assert update["state_data.payment_bypassed"] is True + assert update["state_data.duration_estimate_seconds"] == 1500 + + def test_explicit_bypassed_job(self, patched_app): + client, jm, us, ws = patched_app + job = _awaiting_selection_job(search_results=self._LONG) + job.state_data.update({"credits_charged": 0, "payment_bypassed": True}) + self._assert_no_charge(client, jm, us, job) + + def test_legacy_tenant_job_missing_fields(self, patched_app): + client, jm, us, ws = patched_app + job = _awaiting_selection_job(search_results=self._LONG) + del job.state_data["credits_charged"] + job.tenant_id = "acme" + self._assert_no_charge(client, jm, us, job) + + def test_legacy_admin_owned_made_for_you_job(self, patched_app): + from backend.api.dependencies import require_auth + from backend.main import app + + async def admin_auth(): + return AuthResult(is_valid=True, user_type=UserType.ADMIN, remaining_uses=999, + message="admin", is_admin=True, user_email="admin@nomadkaraoke.com") + + app.dependency_overrides[require_auth] = admin_auth + client, jm, us, ws = patched_app + job = _awaiting_selection_job(search_results=self._LONG, user_email="admin@nomadkaraoke.com") + del job.state_data["credits_charged"] + job.made_for_you = True + self._assert_no_charge(client, jm, us, job) + + +class TestAdminOverrideThenSelect: + """Admin audio-source override clears the old source's duration/selection + markers but keeps credits_charged, so the next /select charges only the + difference for the new (longer) source.""" + + def _override(self, job: Job) -> None: + from google.cloud.firestore_v1 import DELETE_FIELD + from backend.api.routes import admin as admin_routes + from backend.api.routes.admin import OverrideAudioSourceRequest + + payloads = [] + jm = MagicMock() + jm.get_job.return_value = job + jm.firestore.db.collection.return_value.document.return_value.update.side_effect = payloads.append + result = MagicMock() + result.to_dict.return_value = { + "title": "Long Song", "artist": "Artist", "provider": "RED", "quality": "FLAC", + "source_id": "new1", "target_file": "long.flac", "url": "", "duration": 1500, + } + ass = MagicMock() + ass.search.return_value = [result] + ass.last_remote_search_id = None + admin = AuthResult(is_valid=True, user_type=UserType.ADMIN, remaining_uses=999, + message="a", is_admin=True, user_email="admin@nomadkaraoke.com") + with patch.object(admin_routes, "JobManager", return_value=jm), \ + patch.object(admin_routes, "get_audio_search_service", return_value=ass): + admin_routes.override_audio_source( + job.job_id, OverrideAudioSourceRequest(source_type="audio_search"), auth_data=admin) + + # Apply the Firestore payloads to the job (dotted merge / DELETE_FIELD). + for payload in payloads: + for key, value in payload.items(): + if key.startswith("state_data."): + field = key.split(".", 1)[1] + if value is DELETE_FIELD: + job.state_data.pop(field, None) + else: + job.state_data[field] = value + elif key == "status": + job.status = JobStatus(value) + + def test_override_clears_markers_keeps_charge(self): + job = _awaiting_selection_job(credits_charged=2) + job.status = JobStatus.FAILED + job.state_data.update({ + "select_charge_applied": True, "duration_estimate_seconds": 900, + "duration_estimate_source": "search_metadata", "duration_actual_seconds": 905.0, + "pending_additional_credits": 1, "duration_confirm_reason": "reconcile", + "duration_confirmed": True, + }) + self._override(job) + for k in ("select_charge_applied", "duration_estimate_seconds", "duration_estimate_source", + "duration_actual_seconds", "pending_additional_credits", + "duration_confirm_reason", "duration_confirmed"): + assert k not in job.state_data, k + assert job.state_data["credits_charged"] == 2 + assert job.status == JobStatus.AWAITING_AUDIO_SELECTION + + def test_select_after_override_charges_only_the_difference(self, patched_app): + client, jm, us, ws = patched_app + # Previously selected a 15-min source: charged 2 in total. + job = _awaiting_selection_job(credits_charged=2) + job.status = JobStatus.FAILED + job.state_data.update({"select_charge_applied": True, "duration_estimate_seconds": 900}) + self._override(job) + + jm.get_job.return_value = job + resp = _post_select(client) # new source is 25 min -> 3 credits total + + assert resp.status_code == 200, resp.text + us.deduct_credits.assert_called_once() + assert us.deduct_credits.call_args.kwargs["amount"] == 1 # 3 - 2, not 3 + update = next(c.args[1] for c in jm.update_job.call_args_list + if "state_data.select_charge_applied" in c.args[1]) + assert update["state_data.credits_charged"] == 3 diff --git a/backend/tests/api/test_internal_idle_reminder.py b/backend/tests/api/test_internal_idle_reminder.py index 01436c77..cd9e1389 100644 --- a/backend/tests/api/test_internal_idle_reminder.py +++ b/backend/tests/api/test_internal_idle_reminder.py @@ -111,7 +111,7 @@ class TestCheckIdleReminderDurationConfirm: # reminder_sent flag was written back update_calls = mock_job_manager.firestore.update_job.call_args_list assert any( - call_args[0][1].get("state_data", {}).get("reminder_sent") is True + call_args[0][1].get("state_data.reminder_sent") is True for call_args in update_calls ) @@ -253,10 +253,11 @@ class TestScheduleIdleReminderDurationConfirm: update_call = manager.firestore.update_job.call_args assert update_call is not None updated_data = update_call[0][1] - state_data = updated_data.get("state_data", {}) - assert state_data.get("blocking_action_type") == "duration_confirm" - assert state_data.get("reminder_sent") is False - assert "blocking_state_entered_at" in state_data + # Dotted paths merge server-side (never replace the whole map). + assert "state_data" not in updated_data + assert updated_data.get("state_data.blocking_action_type") == "duration_confirm" + assert updated_data.get("state_data.reminder_sent") is False + assert "state_data.blocking_state_entered_at" in updated_data def test_schedules_900s_delay_not_default_delay(self): """ diff --git a/backend/tests/emulator/test_credits_charged_no_clobber.py b/backend/tests/emulator/test_credits_charged_no_clobber.py new file mode 100644 index 00000000..df9e4968 --- /dev/null +++ b/backend/tests/emulator/test_credits_charged_no_clobber.py @@ -0,0 +1,91 @@ +""" +credits_charged must survive the state_data writes that follow create_job. + +create-from-search (and sibling create paths) used to replace the whole +state_data map with the search results right after create_job, wiping +credits_charged / payment_bypassed. They now write dotted ``state_data.`` +fields. These run on the real Firestore emulator and assert that dotted updates +merge (keep the sibling billing keys) while a bare ``state_data`` write would not. + +Run with: scripts/run-emulator-tests.sh +""" + +import pytest +from datetime import datetime, UTC + +from backend.tests.emulator.conftest import emulators_running + +pytestmark = pytest.mark.skipif( + not emulators_running(), + reason="GCP emulators not running. Start with: scripts/start-emulators.sh" +) + +if emulators_running(): + from backend.models.job import Job, JobStatus + from backend.services.job_manager import JobManager + from backend.services.firestore_service import FirestoreService + from backend.services.job_credits import get_credits_charged + + +class TestCreditsChargedNoClobber: + @pytest.fixture + def job_manager(self): + return JobManager() + + @pytest.fixture + def firestore_service(self): + return FirestoreService() + + def _create_job(self, firestore_service, job_id, state_data): + firestore_service.create_job(Job( + job_id=job_id, + status=JobStatus.PENDING, + created_at=datetime.now(UTC), + updated_at=datetime.now(UTC), + artist="Test", + title="Test", + user_email="buyer@example.com", + state_data=state_data, + )) + + def test_dotted_search_results_write_keeps_credits_charged(self, job_manager, firestore_service): + job_id = f"cc-keep-{datetime.now(UTC).timestamp()}" + try: + self._create_job(firestore_service, job_id, {'credits_charged': 1}) + + # Exactly the shape create-from-search now writes. + job_manager.update_job(job_id, { + 'state_data.audio_search_results': [{'index': 0, 'title': 'Waterloo'}], + 'state_data.audio_search_count': 1, + 'state_data.remote_search_id': 'remote-1', + }) + + job = firestore_service.get_job(job_id) + assert job.state_data['credits_charged'] == 1 + assert job.state_data['audio_search_count'] == 1 + assert get_credits_charged(job) == 1 + finally: + firestore_service.delete_job(job_id) + + def test_dotted_write_keeps_payment_bypassed(self, job_manager, firestore_service): + job_id = f"cc-bypass-{datetime.now(UTC).timestamp()}" + try: + self._create_job(firestore_service, job_id, {'credits_charged': 0, 'payment_bypassed': True}) + job_manager.update_job(job_id, {'state_data.audio_search_count': 2}) + + sd = firestore_service.get_job(job_id).state_data + assert sd['credits_charged'] == 0 + assert sd['payment_bypassed'] is True + finally: + firestore_service.delete_job(job_id) + + def test_bare_state_data_write_would_wipe_it(self, job_manager, firestore_service): + """Documents why the old whole-map write was the bug.""" + job_id = f"cc-wipe-{datetime.now(UTC).timestamp()}" + try: + self._create_job(firestore_service, job_id, {'credits_charged': 1}) + job_manager.update_job(job_id, {'state_data': {'audio_search_count': 1}}) + + assert 'credits_charged' not in firestore_service.get_job(job_id).state_data + finally: + firestore_service.delete_job(job_id) diff --git a/backend/tests/test_bulk_search_worker.py b/backend/tests/test_bulk_search_worker.py index 83367b96..522568c4 100644 --- a/backend/tests/test_bulk_search_worker.py +++ b/backend/tests/test_bulk_search_worker.py @@ -176,3 +176,30 @@ async def test_auto_select_parks_when_delta_unaffordable(monkeypatch, patched): await worker.process_job("job1", jm, ass) assert JobStatus.AWAITING_AUDIO_SELECTION in transitions + + +@pytest.mark.asyncio +@pytest.mark.parametrize("state_extra", [ + {"credits_charged": 0, "payment_bypassed": True}, + {"credits_charged": None}, # legacy, field wiped — resolved below via admin owner +]) +async def test_auto_select_never_charges_bypassed_job(monkeypatch, patched, state_extra): + """Bypassed (admin/tenant) jobs: no deduction and credits_charged stays 0, so a + later cancel can't refund credits that were never debited.""" + jm, ass, transitions = patched + job = _make_job(auto=True, state_extra=state_extra) + if state_extra.get("credits_charged") is None: + del job.state_data["credits_charged"] + job.user_email = "admin@nomadkaraoke.com" + us = MagicMock() + monkeypatch.setattr(worker, "get_user_service", lambda: us, raising=False) + monkeypatch.setattr("backend.api.routes.audio_search._validate_and_prepare_selection", + lambda job_id, idx: {"ok": True}) + + ok = await worker._auto_select(job, 0, {"duration": 1500}, jm) + + assert ok is True + us.deduct_credits.assert_not_called() + update = jm.update_job.call_args_list[-1][0][1] + assert update["state_data.credits_charged"] == 0 + assert update["state_data.payment_bypassed"] is True diff --git a/backend/tests/test_credits_charged_consistency.py b/backend/tests/test_credits_charged_consistency.py new file mode 100644 index 00000000..e84b789d --- /dev/null +++ b/backend/tests/test_credits_charged_consistency.py @@ -0,0 +1,482 @@ +"""credits_charged must be recorded at creation and read the same way everywhere. + +Regression for the mobile local-stack E2E finding (2026-10-17): POST +/api/jobs/create-from-search charged 1 credit in create_job, then replaced the +whole ``state_data`` map with the search results — wiping ``credits_charged``. +Reconcile then read the missing field as 1 (pending=1 for a 15-min track, total 2) +while confirm-duration read it as 0 (expected acknowledged_credits == 1), so a +client acknowledging the true total (2) got 409, the web hook displayed "1 credit +in total", and a later cancel/expiry under-refunded. + +Fix: create paths merge into state_data (dotted paths), and every reader uses +backend.services.job_credits.get_credits_charged. +""" +from __future__ import annotations + +from datetime import UTC, datetime +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest +from fastapi.testclient import TestClient + +from backend.models.job import Job, JobStatus +from backend.services.auth_service import AuthResult, UserType +from backend.services.duration_reconciliation import reconcile_duration +from backend.services.job_credits import ( + get_credits_charged, + is_payment_bypassed, + preserve_billing_state, +) + +NOW = datetime.now(UTC) +FIFTEEN_MIN = 900.0 # duration_to_credits(900) == 2 + + +def _job(state_data=None, **kw) -> Job: + defaults = dict( + job_id="job-cc-1", + created_at=NOW, + updated_at=NOW, + user_email="owner@example.com", + status=JobStatus.DOWNLOADING, + state_data=state_data if state_data is not None else {}, + ) + defaults.update(kw) + return Job(**defaults) + + +def apply_firestore_update(job: Job, updates: dict) -> None: + """Mimic Firestore update(): dotted ``state_data.x`` merges, bare ``state_data`` replaces.""" + for key, value in updates.items(): + if key.startswith("state_data."): + job.state_data = {**(job.state_data or {}), key.split(".", 1)[1]: value} + elif key == "state_data": + job.state_data = dict(value) + elif hasattr(job, key): + setattr(job, key, value) + + +class FakeJobManager: + """Single-job store applying updates with Firestore semantics.""" + + def __init__(self, job: Job): + self.job = job + + def get_job(self, job_id): + return self.job + + def update_job(self, job_id, updates): + apply_firestore_update(self.job, updates) + + def transition_to_state(self, job_id, new_status, progress=None, message=None, **kw): + self.job.status = new_status + return True + + def cancel_job(self, job_id, reason=None, refund=True): + self.job.status = JobStatus.CANCELLED + return True + + +# --------------------------------------------------------------------------- +# Helper semantics +# --------------------------------------------------------------------------- + + +class TestGetCreditsCharged: + def test_explicit_value_wins(self): + assert get_credits_charged(_job({"credits_charged": 3})) == 3 + assert get_credits_charged(_job({"credits_charged": 0})) == 0 + + def test_legacy_standard_job_defaults_to_one(self): + assert get_credits_charged(_job({})) == 1 + assert get_credits_charged(_job(None)) == 1 + assert not is_payment_bypassed(_job({})) + + def test_bypass_flag_means_zero(self): + job = _job({"payment_bypassed": True}) + assert get_credits_charged(job) == 0 + assert is_payment_bypassed(job) + + @pytest.mark.parametrize( + "kw", + [ + {"user_email": None}, + {"tenant_id": "acme"}, + {"creation_params": {"is_admin": True}}, + {"user_email": "andrew@nomadkaraoke.com"}, + ], + ) + def test_legacy_unbilled_jobs_default_to_zero(self, kw): + job = _job({}, **kw) + assert get_credits_charged(job) == 0 + assert is_payment_bypassed(job) + + def test_explicit_charge_is_not_bypassed_even_for_tenant(self): + # Explicit field is authoritative; inference only applies when missing. + assert not is_payment_bypassed(_job({"credits_charged": 1}, tenant_id="acme")) + + def test_preserve_billing_state(self): + sd = {"credits_charged": 2, "select_charge_applied": True, "screens_progress": {"x": 1}} + assert preserve_billing_state(sd) == {"credits_charged": 2, "select_charge_applied": True} + assert preserve_billing_state(None) == {} + + +# --------------------------------------------------------------------------- +# create-from-search records credits_charged +# --------------------------------------------------------------------------- + + +def _search_session(): + now = datetime.utcnow() + from datetime import timedelta + + return { + "session_id": "sess-1", + "user_email": "test@example.com", + "tenant_id": None, + "artist": "ABBA", + "title": "Waterloo", + "results": [{"index": 0, "title": "Waterloo", "artist": "ABBA", + "provider": "YouTube", "url": "https://youtube.com/watch?v=abc"}], + "remote_search_id": "remote-9", + "created_at": now.isoformat(), + "ttl_expiry": now + timedelta(days=7), + } + + +class TestCreateFromSearchRecordsCreditsCharged: + def _run(self, auth_headers, created_state): + job = _job(dict(created_state), job_id="test-job-123", status=JobStatus.PENDING) + jm = MagicMock() + jm.create_job.return_value = job + jm.get_job.return_value = job + jm.update_job.side_effect = lambda job_id, updates: apply_firestore_update(job, updates) + + session = _search_session() + mock_firestore = MagicMock() + mock_firestore.get_search_session.return_value = session + mock_firestore.consume_search_session.return_value = session + theme = MagicMock() + theme.get_default_theme_id.return_value = None + worker = AsyncMock() + worker.trigger_audio_download_worker.return_value = True + creds = MagicMock() + creds.universe_domain = "googleapis.com" + + with patch("backend.api.routes.jobs.job_manager", jm), \ + patch("backend.api.routes.jobs.FirestoreService", return_value=mock_firestore), \ + patch("backend.api.routes.jobs.get_theme_service", return_value=theme), \ + patch("backend.api.routes.jobs.get_worker_service", return_value=worker), \ + patch("backend.api.routes.audio_search._validate_and_prepare_selection"), \ + patch("backend.api.routes.audio_search.extract_request_metadata", return_value={}), \ + patch("backend.services.firestore_service.firestore"), \ + patch("backend.services.storage_service.storage"), \ + patch("google.auth.default", return_value=(creds, "test-project")): + from backend.main import app + + resp = TestClient(app).post( + "/api/jobs/create-from-search", + json={"search_session_id": "sess-1", "selection_index": 0, + "artist": "ABBA", "title": "Waterloo", "requires_audio_edit": True}, + headers=auth_headers, + ) + assert resp.status_code == 200, resp.text + for c in jm.update_job.call_args_list: + assert "state_data" not in c.args[1], "must merge (dotted paths), never replace state_data" + return job + + def test_charged_job_keeps_credits_charged_1(self, auth_headers): + job = self._run(auth_headers, {"credits_charged": 1}) + assert job.state_data["credits_charged"] == 1 + assert get_credits_charged(job) == 1 + # search data still stored + assert job.state_data["audio_search_count"] == 1 + assert job.state_data["remote_search_id"] == "remote-9" + assert job.state_data["requires_audio_edit"] is True + + def test_bypassed_job_keeps_payment_bypassed(self, auth_headers): + job = self._run(auth_headers, {"credits_charged": 0, "payment_bypassed": True}) + assert job.state_data["payment_bypassed"] is True + assert job.state_data["credits_charged"] == 0 + + +class TestCreateJobRecordsCharge: + """create_job is the single place that debits at creation; it records the amount.""" + + def _jm(self): + from backend.services.job_manager import JobManager + + jm = JobManager.__new__(JobManager) + jm.firestore = MagicMock() + return jm + + def test_standard_job_records_credits_charged(self): + from backend.models.job import JobCreate + + jm = self._jm() + us = MagicMock() + us.check_credits.return_value = 5 + us.deduct_credits.return_value = (True, 4, "ok") + with patch("backend.services.user_service.get_user_service", return_value=us): + job = jm.create_job(JobCreate(artist="A", title="T", user_email="u@example.com", + theme_id="nomad")) + assert job.state_data == {"credits_charged": 1} + assert us.deduct_credits.call_args.kwargs["amount"] == 1 + + def test_admin_job_records_zero_and_bypass(self): + from backend.models.job import JobCreate + + jm = self._jm() + job = jm.create_job(JobCreate(artist="A", title="T", user_email="u@example.com", + theme_id="nomad"), is_admin=True) + assert job.state_data == {"credits_charged": 0, "payment_bypassed": True} + + +# --------------------------------------------------------------------------- +# reconcile → confirm-duration → cancel agree (new + legacy) +# --------------------------------------------------------------------------- + + +@pytest.fixture +def owner_auth(): + from backend.api.dependencies import require_auth + from backend.main import app + + async def _auth(): + return AuthResult(is_valid=True, user_type=UserType.ADMIN, remaining_uses=999, + message="t", is_admin=True, user_email="owner@example.com") + + app.dependency_overrides[require_auth] = _auth + yield + app.dependency_overrides.pop(require_auth, None) + + +def _reconcile_15min(job: Job): + fjm = FakeJobManager(job) + us = MagicMock() + us.add_credits.return_value = (True, 5, "ok") + result = reconcile_duration(job.job_id, fjm, us, lambda _j: FIFTEEN_MIN) + return fjm, us, result + + +def _confirm(job: Job, fjm: FakeJobManager, acknowledged: int): + from backend.main import app + + us = MagicMock() + us.deduct_credits.return_value = (True, 3, "ok") + ws = MagicMock() + ws.trigger_audio_worker = AsyncMock(return_value=True) + ws.trigger_lyrics_worker = AsyncMock(return_value=True) + with patch("backend.api.routes.jobs.job_manager", fjm), \ + patch("backend.api.routes.jobs.get_user_service", return_value=us), \ + patch("backend.api.routes.jobs.get_worker_service", return_value=ws): + resp = TestClient(app).post(f"/api/jobs/{job.job_id}/confirm-duration", + json={"acknowledged_credits": acknowledged}) + return resp, us + + +def _cancel_refund_amount(job: Job) -> int: + from backend.services.job_manager import JobManager + + jm = JobManager.__new__(JobManager) + jm.firestore = MagicMock() + us = MagicMock() + us.add_credits.return_value = (True, 9, "ok") + with patch("backend.services.user_service.get_user_service", return_value=us): + assert jm._refund_credit_for_job(job.job_id, job, reason="job_cancelled") is True + return us.add_credits.call_args.kwargs["amount"] + + +@pytest.mark.parametrize( + "initial_state", + [{"credits_charged": 1}, {}], + ids=["new-job-with-field", "legacy-job-missing-field"], +) +class TestReconcileConfirmCancelAgree: + def test_15min_track_total_two_confirm_and_cancel_refund_two(self, owner_auth, initial_state): + job = _job(dict(initial_state)) + fjm, _, result = _reconcile_15min(job) + + assert result.action == "pause" + assert result.pending_additional_credits == 1 + # Reconcile persists the resolved charge so every client sees it explicitly. + assert job.state_data["credits_charged"] == 1 + assert job.state_data["pending_additional_credits"] == 1 + + # The true total (what web + mobile display/acknowledge) is accepted. + resp, us = _confirm(job, fjm, acknowledged=2) + assert resp.status_code == 200, resp.text + assert us.deduct_credits.call_args.kwargs["amount"] == 1 + assert job.state_data["credits_charged"] == 2 + assert job.state_data["pending_additional_credits"] == 0 + + # Cancelling afterwards refunds everything the user paid. + assert _cancel_refund_amount(job) == 2 + + def test_stale_total_is_rejected(self, owner_auth, initial_state): + job = _job(dict(initial_state)) + fjm, _, _ = _reconcile_15min(job) + resp, us = _confirm(job, fjm, acknowledged=1) + assert resp.status_code == 409 + us.deduct_credits.assert_not_called() + + +class TestConfirmLegacyAlreadyPaused: + """Jobs paused BEFORE this fix lack credits_charged entirely (only pending set).""" + + def test_true_total_accepted_and_charge_recorded(self, owner_auth): + job = _job({"duration_confirm_reason": "reconcile", "pending_additional_credits": 1}, + status=JobStatus.AWAITING_DURATION_CONFIRM) + fjm = FakeJobManager(job) + resp, us = _confirm(job, fjm, acknowledged=2) # (credits_charged ?? 1) + pending + assert resp.status_code == 200, resp.text + assert us.deduct_credits.call_args.kwargs["amount"] == 1 + assert job.state_data["credits_charged"] == 2 + assert _cancel_refund_amount(job) == 2 + + def test_old_zero_based_total_now_rejected(self, owner_auth): + job = _job({"duration_confirm_reason": "reconcile", "pending_additional_credits": 1}, + status=JobStatus.AWAITING_DURATION_CONFIRM) + resp, us = _confirm(job, FakeJobManager(job), acknowledged=1) + assert resp.status_code == 409 + us.deduct_credits.assert_not_called() + + +class TestRefundAmountsUnchanged: + """Refund amounts for jobs that carry the field are unchanged by the helper.""" + + @pytest.mark.parametrize("charged", [1, 2, 3]) + def test_explicit_charge_refunded_in_full(self, charged): + assert _cancel_refund_amount(_job({"credits_charged": charged})) == charged + + def test_legacy_standard_job_still_refunds_one(self): + assert _cancel_refund_amount(_job({})) == 1 + + def test_bypassed_job_not_refunded(self): + from backend.services.job_manager import JobManager + + jm = JobManager.__new__(JobManager) + jm.firestore = MagicMock() + us = MagicMock() + with patch("backend.services.user_service.get_user_service", return_value=us): + assert jm._refund_credit_for_job("j", _job({"payment_bypassed": True}), "job_cancelled") is False + us.add_credits.assert_not_called() + + def test_reconcile_skips_legacy_bypassed_job(self): + # Made-for-you jobs (admin-owned) lost payment_bypassed the same way; they + # must never be paused/billed by reconcile. + job = _job({}, user_email="admin@nomadkaraoke.com") + _, us, result = _reconcile_15min(job) + assert result.action == "proceed" + us.add_credits.assert_not_called() + assert job.status == JobStatus.DOWNLOADING + + +class TestRetryKeepsBillingState: + def test_preserved_keys_survive_reset(self): + job = _job({"credits_charged": 3, "select_charge_applied": True, "screens_progress": {}}) + apply_firestore_update(job, {"state_data": preserve_billing_state(job.state_data)}) + assert job.state_data == {"credits_charged": 3, "select_charge_applied": True} + assert get_credits_charged(job) == 3 + + +# --------------------------------------------------------------------------- +# Job read endpoints expose the resolved figure (response-only, never persisted) +# --------------------------------------------------------------------------- + + +class TestResolvedCreditsChargedInResponses: + def _paused_legacy(self, **kw): + return _job({"duration_confirm_reason": "reconcile", "pending_additional_credits": 1}, + status=JobStatus.AWAITING_DURATION_CONFIRM, **kw) + + def _get(self, job): + from backend.main import app + + jm = MagicMock() + jm.get_job.return_value = job + with patch("backend.api.routes.jobs.job_manager", jm): + resp = TestClient(app).get(f"/api/jobs/{job.job_id}") + assert resp.status_code == 200, resp.text + jm.update_job.assert_not_called() # response-only + return resp.json()["state_data"] + + def test_get_job_fills_legacy_standard_job_with_1(self, owner_auth): + sd = self._get(self._paused_legacy()) + assert sd["credits_charged"] == 1 + # client acknowledges helper + pending == what confirm-duration expects + assert sd["credits_charged"] + sd["pending_additional_credits"] == 2 + + def test_get_job_fills_legacy_tenant_job_with_0(self, owner_auth): + assert self._get(self._paused_legacy(tenant_id="acme"))["credits_charged"] == 0 + + def test_get_job_keeps_explicit_value(self, owner_auth): + job = _job({"credits_charged": 3}) + assert self._get(job)["credits_charged"] == 3 + + def test_summary_list_fills_and_strips_inputs(self, owner_auth): + from backend.main import app + + rows = [ + {"job_id": "a", "status": "awaiting_duration_confirm", "user_email": "owner@example.com", + "tenant_id": "", "state_data": {"pending_additional_credits": 1}}, + {"job_id": "b", "status": "awaiting_duration_confirm", "user_email": "owner@example.com", + "tenant_id": "", "creation_params": {"is_admin": True}, + "state_data": {"pending_additional_credits": 1}}, + {"job_id": "c", "status": "pending", "user_email": "owner@example.com"}, + {"job_id": "d", "status": "pending", "user_email": "owner@example.com", + "state_data": {"credits_charged": 2}}, + ] + jm = MagicMock() + jm.list_jobs_summary.return_value = rows + with patch("backend.api.routes.jobs.job_manager", jm): + resp = TestClient(app).get("/api/jobs?fields=summary&exclude_test=false") + assert resp.status_code == 200, resp.text + by_id = {r["job_id"]: r for r in resp.json()} + assert by_id["a"]["state_data"]["credits_charged"] == 1 + assert by_id["b"]["state_data"]["credits_charged"] == 0 + assert by_id["c"]["state_data"]["credits_charged"] == 1 + assert by_id["d"]["state_data"]["credits_charged"] == 2 + assert all("tenant_id" not in r and "creation_params" not in r for r in by_id.values()) + + def test_full_list_fills(self, owner_auth): + from backend.main import app + + jm = MagicMock() + jm.list_jobs.return_value = [self._paused_legacy()] + with patch("backend.api.routes.jobs.job_manager", jm): + resp = TestClient(app).get("/api/jobs?exclude_test=false") + assert resp.status_code == 200, resp.text + assert resp.json()[0]["state_data"]["credits_charged"] == 1 + jm.update_job.assert_not_called() + + +# --------------------------------------------------------------------------- +# Callers that refund in full must suppress cancel_job's own refund +# --------------------------------------------------------------------------- + + +class TestNoSecondRefundOnCancel: + def test_cancel_job_refund_false_skips_refund(self): + from backend.services.job_manager import JobManager + + jm = JobManager.__new__(JobManager) + jm.firestore = MagicMock() + job = _job({"credits_charged": 2}) + jm.get_job = MagicMock(return_value=job) + jm.update_job_status = MagicMock() + jm._refund_credit_for_job = MagicMock() + assert jm.cancel_job(job.job_id, reason="x", refund=False) is True + jm._refund_credit_for_job.assert_not_called() + assert jm.cancel_job(job.job_id, reason="x") is True + jm._refund_credit_for_job.assert_called_once() + + def test_reconcile_over_limit_cancels_without_second_refund(self): + job = _job({"credits_charged": 2}) + fjm = MagicMock(wraps=FakeJobManager(job)) + us = MagicMock() + us.add_credits.return_value = (True, 5, "ok") + result = reconcile_duration(job.job_id, fjm, us, lambda _j: 4000.0) + assert result.action == "cancel" + assert us.add_credits.call_args.kwargs["amount"] == 2 + assert fjm.cancel_job.call_args.kwargs["refund"] is False diff --git a/backend/tests/test_job_manager_notifications.py b/backend/tests/test_job_manager_notifications.py index f8d7f772..8164b3dd 100644 --- a/backend/tests/test_job_manager_notifications.py +++ b/backend/tests/test_job_manager_notifications.py @@ -217,12 +217,13 @@ class TestScheduleIdleReminder: update_call = manager.firestore.update_job.call_args assert update_call is not None updated_data = update_call[0][1] # Second positional arg - state_data = updated_data.get('state_data', {}) - assert state_data.get('blocking_action_type') == 'lyrics' - assert state_data.get('reminder_sent') is False - assert 'blocking_state_entered_at' in state_data - assert state_data.get('existing_key') == 'value' # Preserved + assert updated_data.get('state_data.blocking_action_type') == 'lyrics' + assert updated_data.get('state_data.reminder_sent') is False + assert 'state_data.blocking_state_entered_at' in updated_data + # Other keys (existing_key, credits_charged…) are preserved because the + # update merges via dotted paths instead of replacing the whole map. + assert 'state_data' not in updated_data def test_updates_state_data_for_instrumental_selection(self): """Test that state_data is updated with blocking state info for instrumental.""" @@ -247,9 +248,8 @@ class TestScheduleIdleReminder: # Verify state_data was updated update_call = manager.firestore.update_job.call_args updated_data = update_call[0][1] - state_data = updated_data.get('state_data', {}) - assert state_data.get('blocking_action_type') == 'instrumental' + assert updated_data.get('state_data.blocking_action_type') == 'instrumental' def test_handles_none_state_data(self): """Test that None state_data is handled gracefully.""" diff --git a/backend/tests/test_stale_duration_confirm.py b/backend/tests/test_stale_duration_confirm.py index 7564c86d..f3c0f4fa 100644 --- a/backend/tests/test_stale_duration_confirm.py +++ b/backend/tests/test_stale_duration_confirm.py @@ -169,12 +169,80 @@ class TestStaleDurationConfirm: mock_job_manager.cancel_job.assert_called_once_with( job.job_id, reason="Duration confirmation not completed within 48 hours", + refund=False, # already refunded in full above — never refund twice ) # Must send the duration-confirm expired email (NOT review expired) mock_email_service.send_duration_confirm_expired.assert_called_once() mock_email_service.send_review_expired.assert_not_called() + async def test_48h_legacy_job_without_credits_charged_refunds_one( + self, mock_firestore, mock_job_manager, mock_email_service, mock_user_service + ): + """Legacy job lacking credits_charged (create-from-search used to wipe it) + was charged 1 credit at creation: expiry must refund 1 (same default as + reconcile / confirm-duration / _refund_credit_for_job), not 0.""" + job = _make_duration_confirm_job(hours_ago=50) + del job.state_data['credits_charged'] + mock_firestore.list_jobs.side_effect = [[], [], [job]] + + with self._patch_all(mock_firestore, mock_job_manager, mock_email_service, mock_user_service): + from backend.workers.stale_review_processor import process_stale_reviews + await process_stale_reviews() + + mock_user_service.add_credits.assert_called_once_with( + job.user_email, amount=1, reason="duration_confirm_expired", job_id=job.job_id, + ) + assert mock_email_service.send_duration_confirm_expired.call_args.kwargs["credits_refunded"] == 1 + + async def test_48h_flag_write_failure_still_no_second_refund( + self, mock_firestore, mock_job_manager, mock_email_service, mock_user_service + ): + """add_credits succeeded but writing credit_refunded=True failed: cancel_job + must still be told not to refund again.""" + job = _make_duration_confirm_job(hours_ago=50, credits_charged=2) + mock_firestore.list_jobs.side_effect = [[], [], [job]] + + def _update(job_id, updates): + if updates.get('credit_refunded'): + raise RuntimeError("firestore down") + mock_firestore.update_job.side_effect = _update + + with self._patch_all(mock_firestore, mock_job_manager, mock_email_service, mock_user_service): + from backend.workers.stale_review_processor import process_stale_reviews + await process_stale_reviews() + + mock_user_service.add_credits.assert_called_once() + assert mock_job_manager.cancel_job.call_args.kwargs.get("refund") is False + + async def test_48h_refund_failure_lets_cancel_refund( + self, mock_firestore, mock_job_manager, mock_email_service, mock_user_service + ): + """If our refund failed, cancel_job keeps its own refund as the fallback.""" + job = _make_duration_confirm_job(hours_ago=50, credits_charged=2) + mock_firestore.list_jobs.side_effect = [[], [], [job]] + mock_user_service.add_credits.return_value = (False, 0, "nope") + + with self._patch_all(mock_firestore, mock_job_manager, mock_email_service, mock_user_service): + from backend.workers.stale_review_processor import process_stale_reviews + await process_stale_reviews() + + assert "refund" not in mock_job_manager.cancel_job.call_args.kwargs + + async def test_48h_legacy_tenant_job_without_credits_charged_refunds_nothing( + self, mock_firestore, mock_job_manager, mock_email_service, mock_user_service + ): + """A tenant-billed job was never debited consumer credits: no refund.""" + job = _make_duration_confirm_job(hours_ago=50, tenant_id="acme") + del job.state_data['credits_charged'] + mock_firestore.list_jobs.side_effect = [[], [], [job]] + + with self._patch_all(mock_firestore, mock_job_manager, mock_email_service, mock_user_service): + from backend.workers.stale_review_processor import process_stale_reviews + await process_stale_reviews() + + mock_user_service.add_credits.assert_not_called() + async def test_48h_no_double_refund_from_cancel_job( self, mock_firestore, mock_job_manager, mock_email_service, mock_user_service ): diff --git a/backend/tests/test_standalone_search.py b/backend/tests/test_standalone_search.py index f4c3864b..54c7d41c 100644 --- a/backend/tests/test_standalone_search.py +++ b/backend/tests/test_standalone_search.py @@ -928,10 +928,11 @@ class TestCreateJobFromSearch: assert response.status_code == 200 # Check that update_job was called with state_data containing remote_search_id update_calls = mock_job_manager_cfs.update_job.call_args_list - state_data_call = [c for c in update_calls if 'state_data' in c[0][1]] + # Dotted-path merge: replacing state_data would wipe create_job's credits_charged + assert not any('state_data' in c[0][1] for c in update_calls) + state_data_call = [c for c in update_calls if 'state_data.remote_search_id' in c[0][1]] assert len(state_data_call) >= 1 - state_data = state_data_call[0][0][1]['state_data'] - assert state_data['remote_search_id'] == "torrent-search-42" + assert state_data_call[0][0][1]['state_data.remote_search_id'] == "torrent-search-42" def test_concurrent_consume_second_request_returns_404(self, mock_job_manager_cfs, auth_headers): """Second concurrent request to same session gets 404 (session already consumed).""" diff --git a/backend/workers/bulk_search_worker.py b/backend/workers/bulk_search_worker.py index 7880da16..fed818b4 100644 --- a/backend/workers/bulk_search_worker.py +++ b/backend/workers/bulk_search_worker.py @@ -79,10 +79,11 @@ async def _auto_select(job, selection_index: int, selected: dict, return False if not sd.get("select_charge_applied"): - credits_charged = int(sd.get("credits_charged", 1)) + from backend.services.job_credits import get_credits_charged, is_payment_bypassed + credits_charged = get_credits_charged(job) target_total = duration_to_credits(duration) if duration is not None else credits_charged owed = max(0, target_total - credits_charged) - bypass = bool(sd.get("payment_bypassed", False)) + bypass = is_payment_bypassed(job) if owed > 0 and not bypass: user_email = job.user_email if not user_email: @@ -106,10 +107,13 @@ async def _auto_select(job, selection_index: int, selected: dict, logger.info("[bulk] job %s lacks credits for duration delta; parking", job_id) return False update = { - "state_data.credits_charged": target_total, + # Bypassed jobs were never billed: keep 0 so no refund pays out. + "state_data.credits_charged": 0 if bypass else target_total, "state_data.select_charge_applied": True, "state_data.bulk_charge_pending": None, } + if bypass: + update["state_data.payment_bypassed"] = True if duration is not None: update["state_data.duration_estimate_seconds"] = duration update["state_data.duration_estimate_source"] = "search_metadata" diff --git a/backend/workers/stale_review_processor.py b/backend/workers/stale_review_processor.py index 0b57b397..c6af6709 100644 --- a/backend/workers/stale_review_processor.py +++ b/backend/workers/stale_review_processor.py @@ -155,7 +155,8 @@ def process_stale_reviews_sync() -> Dict[str, Any]: f"(>={REVIEW_EXPIRY_HOURS}h), auto-expiring with credits_charged refund" ) - credits_charged = state_data.get('credits_charged', 0) or 0 + from backend.services.job_credits import get_credits_charged + credits_charged = get_credits_charged(job) credits_refunded = 0 # Refund the full charged amount (not flat 1) BEFORE cancelling. @@ -174,16 +175,28 @@ def process_stale_reviews_sync() -> Dict[str, Any]: ) if ok: credits_refunded = credits_charged - # Prevent cancel_job's internal 1-credit refund - firestore.update_job(job.job_id, {'credit_refunded': True}) + # Prevent any other path's refund (cancel_job is also + # told refund=False below). + try: + firestore.update_job(job.job_id, {'credit_refunded': True}) + except Exception as flag_err: + logger.error( + f"Job {job.job_id}: refunded but failed to set credit_refunded: {flag_err}" + ) except Exception as refund_err: logger.error( f"Job {job.job_id}: failed to refund {credits_charged} credits: {refund_err}" ) + cancel_kwargs = {} + if credits_refunded > 0: + # Already refunded in full above — never let cancel_job + # refund again (even if the credit_refunded write failed). + cancel_kwargs["refund"] = False cancelled = job_manager.cancel_job( job.job_id, reason="Duration confirmation not completed within 48 hours", + **cancel_kwargs, ) if cancelled: jobs_expired += 1 diff --git a/docs/API.md b/docs/API.md index 1fa1b15a..25e70c7c 100644 --- a/docs/API.md +++ b/docs/API.md @@ -146,12 +146,16 @@ Content-Type: application/json {"acknowledged_credits": 3} ``` -Called when a job is paused in `AWAITING_DURATION_CONFIRM` state. Two scenarios: +Called when a job is paused in `AWAITING_DURATION_CONFIRM` state. The only pause reason is +**`reconcile`** (`state_data.duration_confirm_reason`): the measured audio costs more than was +already charged (URL, upload and search jobs alike). -- **`preflight`** — upload flow: duration measured after file lands in GCS; no charge applied yet. - `acknowledged_credits` must equal the full cost (`pending_additional_credits` in `state_data`). -- **`reconcile`** — post-download: actual duration costs more than was already charged. - `acknowledged_credits` must equal the new total (`credits_charged + pending_additional_credits`). +`acknowledged_credits` must equal the new total: `state_data.credits_charged + +state_data.pending_additional_credits`. Reconcile writes `credits_charged` alongside +`pending_additional_credits` when it pauses, and `GET /api/jobs/{id}` / `GET /api/jobs` always +return a resolved `state_data.credits_charged` (filled in the response for legacy jobs that lack +it, via `job_credits.get_credits_charged`), so clients should read it rather than defaulting. +On success `credits_charged` becomes the new total, which is what a later cancel/expiry refunds. On success, deducts the owed credits and resumes by triggering both audio and lyrics workers. Returns the updated job. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 56dbf1ec..96d0abb3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -197,6 +197,16 @@ If the actual duration exceeds 60 min all charged credits are refunded and the j If it costs less than charged an auto-refund is issued silently. Admin/made-for-you jobs bypass this state entirely. See `docs/archive/2026-06-04-long-duration-input-handling-design.md`. +**`state_data.credits_charged`** is the authoritative running total of consumer credits debited +for a job (written by `create_job`, updated by audio selection, reconcile and confirm-duration; +`0` + `payment_bypassed=True` for admin/tenant/no-email jobs). Every reader — reconcile, +confirm-duration, `/select`, bulk auto-select, `_refund_credit_for_job`, the 48h stale expiry — +must use `backend/services/job_credits.get_credits_charged()`. For legacy jobs missing the field it +returns what `create_job` actually debited: `0` for admin/tenant/no-email/bypassed jobs, else `1`. +Never replace the whole `state_data` map after `create_job` (use dotted `state_data.` updates; +resets must keep `preserve_billing_state()`): before v0.278.2 create-from-search did, wiping the +charge so reconcile (missing=1) and confirm-duration (missing=0) disagreed. + **State Machine Robustness (Feb 2026)**: State transitions are enforced by `STATE_TRANSITIONS` in `models/job.py`. Invalid transitions raise `InvalidStateTransitionError` by default. Use `scripts/generate_state_diagram.py` to generate a Mermaid diagram of valid transitions. The `/health/job-consistency` endpoint detects jobs stuck in invalid states. See `docs/archive/2026-02-02-state-machine-robustness-plan.md` for implementation details. ## GCS File Structure diff --git a/frontend/__tests__/DurationCostConfirm.test.tsx b/frontend/__tests__/DurationCostConfirm.test.tsx index 5be48a2f..a13c7d86 100644 --- a/frontend/__tests__/DurationCostConfirm.test.tsx +++ b/frontend/__tests__/DurationCostConfirm.test.tsx @@ -141,4 +141,20 @@ describe('DurationCostConfirm', () => { const buyBtn = screen.getByRole('button', { name: /buy credits/i }) expect(buyBtn).toBeDisabled() }) + + it('checks affordability against creditsDue, not the total (reconcile top-up)', () => { + // 15-min job: 1 credit already charged, 1 more owed, total 2. A balance of 1 + // covers it — the old total-based check showed "Buy credits" instead. + const onConfirm = jest.fn() + render() + expect(screen.getByText(/2 credits/)).toBeInTheDocument() + fireEvent.click(screen.getByRole('button', { name: /confirm & start/i })) + expect(onConfirm).toHaveBeenCalledTimes(1) + }) + + it('still asks to buy credits when the balance cannot cover creditsDue', () => { + render() + expect(screen.queryByRole('button', { name: /confirm & start/i })).not.toBeInTheDocument() + expect(screen.getByRole('button', { name: /buy credits/i })).toBeInTheDocument() + }) }) diff --git a/frontend/components/job/DurationCostConfirm.tsx b/frontend/components/job/DurationCostConfirm.tsx index 4bac7a33..a40a9538 100644 --- a/frontend/components/job/DurationCostConfirm.tsx +++ b/frontend/components/job/DurationCostConfirm.tsx @@ -8,7 +8,13 @@ import { formatDurationCost } from '@/lib/pricing' interface Props { open: boolean durationSeconds: number | null + /** Total credits the job will cost (shown to the user and acknowledged). */ credits: number + /** + * Credits still to be paid now (the total minus what was already charged). + * Affordability is checked against this, not the total. Defaults to `credits`. + */ + creditsDue?: number balance: number estimated?: boolean reconcile?: boolean @@ -21,6 +27,7 @@ export function DurationCostConfirm({ open, durationSeconds, credits, + creditsDue, balance, estimated = false, reconcile = false, @@ -31,7 +38,7 @@ export function DurationCostConfirm({ const t = useTranslations('pricing') const minutes = durationSeconds != null ? formatDurationCost(durationSeconds).minutes : null - const canAfford = balance >= credits + const canAfford = balance >= (creditsDue ?? credits) return ( { if (!o) onClose() }}> diff --git a/frontend/components/job/JobCard.tsx b/frontend/components/job/JobCard.tsx index e495a3c0..3fae7a09 100644 --- a/frontend/components/job/JobCard.tsx +++ b/frontend/components/job/JobCard.tsx @@ -313,6 +313,7 @@ export function JobCard({ job, onRefresh, showAdminControls }: JobCardProps) { open={true} durationSeconds={modalState.data.durationSeconds} credits={modalState.data.totalCredits} + creditsDue={modalState.data.additionalCredits} balance={user?.credits ?? 0} reconcile={modalState.data.reconcile} onConfirm={handleConfirm} diff --git a/frontend/hooks/__tests__/use-duration-confirm.test.ts b/frontend/hooks/__tests__/use-duration-confirm.test.ts index 2b1b6fea..39ad1183 100644 --- a/frontend/hooks/__tests__/use-duration-confirm.test.ts +++ b/frontend/hooks/__tests__/use-duration-confirm.test.ts @@ -119,13 +119,43 @@ describe("getDurationConfirmData", () => { expect(data!.reconcile).toBe(false) }) - it("handles missing state_data gracefully (zeros)", () => { + it("handles missing state_data gracefully (standard 1-credit charge, nothing pending)", () => { const job = makeJob({ state_data: undefined }) const data = getDurationConfirmData(job) expect(data).not.toBeNull() - expect(data!.totalCredits).toBe(0) + expect(data!.totalCredits).toBe(1) expect(data!.durationSeconds).toBeNull() }) + + it("legacy job lacking credits_charged: total = 1 (charged at creation) + pending", () => { + // create-from-search jobs used to lose credits_charged; a 15-min track pauses + // with pending=1 and really costs 2 in total (matches backend get_credits_charged). + const job = makeJob({ + state_data: { + pending_additional_credits: 1, + duration_actual_seconds: 900, + duration_confirm_reason: "reconcile", + }, + }) + const data = getDurationConfirmData(job) + expect(data!.totalCredits).toBe(2) + expect(data!.acknowledgedCredits).toBe(2) + expect(data!.additionalCredits).toBe(1) // what the balance must cover now + }) + + it("payment-bypassed job lacking credits_charged counts 0 already charged", () => { + const job = makeJob({ + state_data: { payment_bypassed: true, pending_additional_credits: 1 }, + }) + expect(getDurationConfirmData(job)!.totalCredits).toBe(1) + }) + + it("explicit credits_charged: 0 is respected", () => { + const job = makeJob({ + state_data: { credits_charged: 0, pending_additional_credits: 2 }, + }) + expect(getDurationConfirmData(job)!.totalCredits).toBe(2) + }) }) // --------------------------------------------------------------------------- diff --git a/frontend/hooks/use-duration-confirm.ts b/frontend/hooks/use-duration-confirm.ts index f84c1e4a..a88d14a1 100644 --- a/frontend/hooks/use-duration-confirm.ts +++ b/frontend/hooks/use-duration-confirm.ts @@ -11,6 +11,8 @@ import { api, type Job } from "@/lib/api" export interface DurationConfirmData { /** Total credits that will be on account after confirm (credits_charged + pending_additional_credits) */ totalCredits: number + /** Credits still owed now (pending_additional_credits) — what the balance must cover */ + additionalCredits: number /** The amount passed to api.confirmDuration (same as totalCredits; validated server-side) */ acknowledgedCredits: number /** Measured duration in seconds (may be null if not yet known) */ @@ -22,7 +24,12 @@ export interface DurationConfirmData { export function getDurationConfirmData(job: Job): DurationConfirmData | null { if (job.status !== "awaiting_duration_confirm") return null const sd = job.state_data ?? {} - const creditsCharged = typeof sd.credits_charged === "number" ? sd.credits_charged : 0 + // Mirrors the backend's job_credits.get_credits_charged default: a job lacking + // the field was charged the standard 1 credit at creation unless payment was + // bypassed. (Reconcile now persists credits_charged on pause, so this fallback + // only matters for jobs paused before that fix.) + const creditsCharged = + typeof sd.credits_charged === "number" ? sd.credits_charged : sd.payment_bypassed ? 0 : 1 const pendingAdditional = typeof sd.pending_additional_credits === "number" ? sd.pending_additional_credits : 0 const totalCredits = creditsCharged + pendingAdditional @@ -32,6 +39,7 @@ export function getDurationConfirmData(job: Job): DurationConfirmData | null { return { totalCredits, + additionalCredits: pendingAdditional, acknowledgedCredits: totalCredits, durationSeconds, reconcile, diff --git a/pyproject.toml b/pyproject.toml index 75ce5206..a55c8cbd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "karaoke-gen" -version = "0.278.1" +version = "0.278.2" description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens." authors = ["Andrew Beveridge "] license = "MIT"