fix(credits): keep credits_charged through job creation; one helper for confirm/refund/select (v0.278.2) (#1180)

## Summary
Fixes `credits_charged` being wiped from `state_data`, which made
duration confirm, refunds and the web cost dialog disagree. Mobile E2E
against the local stack found it: a 15-minute track showed "1 credit in
total (1 more)", and confirming the true total was rejected with 409.

**Root cause:** `create_job` debits the credit and records
`state_data.credits_charged`. But create-from-search, audio-search
create, made-for-you orders (which also lost `payment_bypassed`) and the
admin source override then replaced the whole `state_data` map, deleting
the field. Readers filled the gap with different defaults:
- reconcile: 1
- confirm-duration: 0
- 48h expiry: 0

**Fix**
- **Writers:** per-key `state_data.<key>` updates instead of whole-map
writes. Retry-from-scratch keeps the billing keys. Reconcile records
`credits_charged` when it pauses a job.
- **Readers:** one helper, `backend/services/job_credits.py`
(`get_credits_charged`, `is_payment_bypassed`). Every reader uses it:
reconcile, confirm-duration, `/select`, the bulk worker,
`_refund_credit_for_job` and the 48h expiry.
- For legacy jobs that lack the field, it returns what `create_job`
actually debited: 0 for bypassed, admin, tenant or no-email jobs,
otherwise 1.
- **`/select` and the bulk worker** never bill payment-bypassed jobs
(made-for-you, tenant, admin-created). This includes legacy ones whose
flag was wiped.
- **API responses:** `GET /api/jobs/{id}` and the job lists return the
resolved `credits_charged` when the stored field is missing. This is
response-only and never persisted, so the web and mobile clients
acknowledge exactly `credits_charged + pending`.
- **Confirm-duration** records the full total, so cancelling after a
confirm refunds it all. The 48h expiry refunds once:
`cancel_job(refund=False)` stops a second refund.
- **Admin source override** clears the old source's duration, selection
and confirm markers and keeps `credits_charged`. The next `/select` then
charges only the difference.
- **Web cost hook:** uses the server's resolved figure.
- Version 0.278.2.

## Testing
- New `test_credits_charged_consistency.py` covers:
- reconcile, then confirm with total 2, then cancel: 2 refunded, for new
and legacy jobs
  - 409 on the old total
  - refund amounts unchanged for jobs that have the field
  - `/select` and the bulk worker never deducting on bypassed jobs
  - the override followed by `/select` charging only the difference
- Stale-expiry legacy tests, and an emulator test for the dotted-path
merge (runs in CI).
- Backend unit tests: 6411 passed. Emulator integration tests run in CI;
locally they collided with a running local stack. Frontend jest: 1754
passed.
- An independent review found one Critical issue (`/select` billing
bypassed jobs) and one Important issue (web/server default mismatch).
Both are fixed and re-reviewed clean. Local CodeRabbit raised one minor,
which is fixed.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_011yLH4kWXMqjeKfZUG3ZiWZ

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 5.5 authored and GitHub committed 2026-10-17 08:38:35 -04:00
1 parent 1616bc997b
commit 2838d2dd1d
27 files changed
+1165 -78

No files matched your search

+14 -1
View File
@@ -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,
+17 -9
View File
@@ -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"
+3 -1
View File
@@ -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})
+51 -9
View File
@@ -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,
},
+6 -4
View File
@@ -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
+12 -3
View File
@@ -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(
+4
View File
@@ -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',
+109
View File
@@ -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
+26 -20
View File
@@ -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
@@ -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
@@ -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):
"""
@@ -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.<key>``
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)
+27
View File
@@ -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
@@ -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
@@ -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."""
@@ -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
):
+4 -3
View File
@@ -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)."""
+7 -3
View File
@@ -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"
+16 -3
View File
@@ -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
+9 -5
View File
@@ -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.
+10
View File
@@ -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.<key>` 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
@@ -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(<DurationCostConfirm {...baseProps} credits={2} creditsDue={1} balance={1} onConfirm={onConfirm} />)
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(<DurationCostConfirm {...baseProps} credits={3} creditsDue={2} balance={1} />)
expect(screen.queryByRole('button', { name: /confirm & start/i })).not.toBeInTheDocument()
expect(screen.getByRole('button', { name: /buy credits/i })).toBeInTheDocument()
})
})
@@ -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 (
<Dialog open={open} onOpenChange={(o) => { if (!o) onClose() }}>
+1
View File
@@ -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}
@@ -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)
})
})
// ---------------------------------------------------------------------------
+9 -1
View File
@@ -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,
+1 -1
View File
@@ -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 <andrew@beveridge.uk>"]
license = "MIT"