Reduce free credits from 2 to 1 per grant (#592)

## Summary

- Welcome credits: 2 → 1 (granted on first email verification)
- Feedback credits: 2 → 1 (granted for submitting product feedback)
- Total possible free credits per account: 4 → 2

## Changes

**Backend:** `NEW_USER_FREE_CREDITS` constant, feedback credit grant, AI
evaluation prompt, model defaults
**Frontend:** Landing page, dashboard banner, feedback dialog, auth
dropdown menu text
**Tests:** Updated all assertions and mock values (115 backend + 712
frontend tests pass)
**Docs:** AI-CREDIT-GATING.md, API.md, README.md,
PRODUCT-COMMUNICATION-GUIDE.md

## Test plan

- [x] Backend tests pass (115 passed)
- [x] Frontend Jest tests pass (712 passed)
- [ ] CI pipeline passes
- [ ] Verify landing page shows "1 Free Credit" after deploy
- [ ] Verify new user signup grants 1 credit (not 2)

@coderabbitai ignore

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

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 4.6 authored and GitHub committed 2026-03-24 21:30:38 -04:00
1 parent a7e41a09d6
commit 6577babfea
19 files changed
+38 -38

No files matched your search

+4 -4
View File
@@ -1126,7 +1126,7 @@ async def check_feedback_eligibility(
eligible=eligible,
has_submitted=user.has_submitted_feedback,
jobs_completed=user.total_jobs_completed,
credits_reward=2,
credits_reward=1,
)
@@ -1137,7 +1137,7 @@ async def submit_user_feedback(
user_service: UserService = Depends(get_user_service),
):
"""
Submit product feedback to earn 2 free credits.
Submit product feedback to earn 1 free credit.
Requires authentication. Users must have completed 2+ jobs and
not have already submitted feedback. At least one text field
@@ -1266,8 +1266,8 @@ async def submit_user_feedback(
credits_granted=0,
)
# Grant 2 credits (passed evaluation)
credits_granted = 2
# Grant 1 credit (passed evaluation)
credits_granted = 1
user_service.add_credits(
email=user.email,
amount=credits_granted,
+2 -2
View File
@@ -229,7 +229,7 @@ class UserFeedback(BaseModel):
Feedback from any user (not just beta testers).
Stored in Firestore 'user_feedback' collection.
Users earn 2 free credits for submitting detailed feedback.
Users earn 1 free credit for submitting detailed feedback.
"""
id: str
user_email: str
@@ -284,4 +284,4 @@ class FeedbackEligibilityResponse(BaseModel):
eligible: bool
has_submitted: bool
jobs_completed: int
credits_reward: int = 2
credits_reward: int = 1
@@ -30,7 +30,7 @@ class CreditEvaluation:
SYSTEM_PROMPT = """You are an anti-abuse evaluator for Nomad Karaoke, a web service that creates professional karaoke videos. Each job costs the service real money in API credits and cloud compute.
New users get 2 free welcome credits to try the service. Users who complete 2 jobs and submit feedback get 2 more credits. Some users abuse this by creating multiple accounts to get unlimited free karaoke generation.
New users get 1 free welcome credit to try the service. Users who complete 2 jobs and submit feedback get 1 more credit. Some users abuse this by creating multiple accounts to get unlimited free karaoke generation.
Your job: Given the signals below, decide whether to GRANT or DENY free credits to this user.
+1 -1
View File
@@ -48,7 +48,7 @@ class UserService:
"""Service for user management and authentication."""
# Number of free credits granted to new users
NEW_USER_FREE_CREDITS = 2
NEW_USER_FREE_CREDITS = 1
def __init__(self):
"""Initialize user service with Firestore client."""
+2 -2
View File
@@ -299,7 +299,7 @@ class TestSubmitFeedbackEmailIntegration:
would_use_again=False,
)
assert result.credits_granted == 2
assert result.credits_granted == 1
@patch("backend.services.email_service.get_email_service")
@patch("backend.services.auth_service.get_auth_service")
@@ -344,7 +344,7 @@ class TestSubmitFeedbackEmailIntegration:
# User still gets credits even though email failed
assert result.status == "success"
assert result.credits_granted == 2
assert result.credits_granted == 1
class TestFeedbackEmailNotification:
+4 -4
View File
@@ -127,7 +127,7 @@ class TestGrantWelcomeCredits:
# Verify update was called with credits and flag
mock_db.collection.return_value.document.return_value.update.assert_called_once()
update_args = mock_db.collection.return_value.document.return_value.update.call_args[0][0]
assert update_args['credits'] == 2
assert update_args['credits'] == 1
assert update_args['welcome_credits_granted'] is True
@patch('backend.services.user_service.get_settings')
@@ -379,7 +379,7 @@ def mock_user_svc():
email="test@example.com",
expires_at=datetime.utcnow() + timedelta(minutes=15),
)
svc.NEW_USER_FREE_CREDITS = 2
svc.NEW_USER_FREE_CREDITS = 1
return svc
@@ -530,7 +530,7 @@ class TestVerifyGrantsCredits:
mock_user_svc.grant_welcome_credits_if_eligible.return_value = (credits_eligible, "granted" if credits_eligible else "already_granted")
mock_user_svc.get_user.return_value = user
mock_user_svc.create_session.return_value = MagicMock(token="session-token")
mock_user_svc.NEW_USER_FREE_CREDITS = 2
mock_user_svc.NEW_USER_FREE_CREDITS = 1
# Mock magic link doc for first-login check
mock_ml_doc = MagicMock()
@@ -559,7 +559,7 @@ class TestVerifyGrantsCredits:
assert response.status_code == 200
data = response.json()
assert data["credits_granted"] == 2
assert data["credits_granted"] == 1
mock_user_svc.grant_welcome_credits_if_eligible.assert_called_once()
finally:
from backend.main import app
@@ -276,7 +276,7 @@ class TestFindRelatedAccounts:
@pytest.fixture
def mock_user_svc():
svc = MagicMock()
svc.NEW_USER_FREE_CREDITS = 2
svc.NEW_USER_FREE_CREDITS = 1
return svc
+3 -3
View File
@@ -405,10 +405,10 @@ class TestCreditRefundOnJobDeletion:
class TestWelcomeCredits:
"""Test new user welcome credits."""
def test_new_user_gets_2_welcome_credits(self):
"""Verify NEW_USER_FREE_CREDITS is set to 2."""
def test_new_user_gets_1_welcome_credit(self):
"""Verify NEW_USER_FREE_CREDITS is set to 1."""
from backend.services.user_service import UserService
assert UserService.NEW_USER_FREE_CREDITS == 2
assert UserService.NEW_USER_FREE_CREDITS == 1
class TestInsufficientCreditsError:
+2 -2
View File
@@ -34,7 +34,7 @@ Gemini decision:
| Scenario | Credits | User Experience | Admin Notification |
|----------|---------|-----------------|-------------------|
| Clean user (no correlations) | Granted | "2 free credits!" interstitial | None |
| Clean user (no correlations) | Granted | "1 free credit!" interstitial | None |
| AI approves | Granted | Same | None |
| AI denies (abuse detected) | Not granted | "Couldn't grant free credits" + buy CTA | CC on rejection email to user |
| AI error / uncertain | Not granted | "Team will review shortly" + buy CTA | Review email with admin page link |
@@ -109,7 +109,7 @@ When you receive a "Credit review needed" email:
1. Click the "Review User" link to go to their admin page
2. Check their abuse signals: fingerprint matches, IP matches, job history
3. If legitimate: Use the admin credits endpoint to grant 2 credits manually
3. If legitimate: Use the admin credits endpoint to grant 1 credit manually
4. If abusive: No action needed — they already have 0 credits
Note: For `pending_review` cases, the `welcome_credits_granted` flag is NOT set, so the system won't interfere if you grant credits manually later.
+4 -4
View File
@@ -944,7 +944,7 @@ Credits are checked and deducted at job creation time. The flow:
3. **Deduct** - `user_service.deduct_credit()` atomically deducts 1 credit (with job_id for audit trail)
4. **Refund on failure** - If the job fails, 1 credit is automatically refunded
Admin users bypass credit checks entirely. New users receive 2 welcome credits. Users can earn 2 additional free credits by submitting product feedback after completing 2+ jobs (see [User Feedback for Credits](#user-feedback-for-credits)).
Admin users bypass credit checks entirely. New users receive 1 welcome credit. Users can earn 1 additional free credit by submitting product feedback after completing 2+ jobs (see [User Feedback for Credits](#user-feedback-for-credits)).
#### 402 Response
@@ -969,7 +969,7 @@ Handles `checkout.session.completed` events.
### User Feedback for Credits
Users who have completed 2+ jobs can submit feedback to earn 2 free credits.
Users who have completed 2+ jobs can submit feedback to earn 1 free credit.
#### Check Eligibility
@@ -984,7 +984,7 @@ Response:
"eligible": true,
"has_submitted": false,
"jobs_completed": 3,
"credits_reward": 2
"credits_reward": 1
}
```
@@ -1013,7 +1013,7 @@ Requirements:
- At least one text field must have >50 characters
- User can only submit once (duplicate prevention)
Grants 2 credits on success. Feedback stored in `user_feedback` Firestore collection.
Grants 1 credit on success. Feedback stored in `user_feedback` Firestore collection.
The `/api/users/me` response includes `feedback_eligible: bool` so the frontend can show/hide feedback prompts without an extra API call.
+1 -1
View File
@@ -61,7 +61,7 @@ Guidelines for how to communicate about Nomad Karaoke to users, in marketing mat
## Free Credits
- All new accounts receive 2 free credits to try the service
- All new accounts receive 1 free credit to try the service
- No payment required to get started
- Credits never expire
- Additional credits available for purchase ($5/credit, bulk discounts available)
+3 -3
View File
@@ -24,7 +24,7 @@
| Token-based auth | Working |
| Magic link auth | Working |
| Payment flow (Stripe) | Working |
| Feedback-for-credits | Working (2+ jobs → 2 free credits) |
| Feedback-for-credits | Working (2+ jobs → 1 free credit) |
| Admin dashboard | Working |
| Abuse prevention & YouTube quota | Working (blocklists, IP/fingerprint rate limiting, credits on verification, quota-aware YouTube uploads) |
| CI/CD self-hosted runner | Working (GCP) |
@@ -74,9 +74,9 @@
- **Song Lookup Autocomplete & Community Version Detection** (2026-03-03): Added song catalog integration to the job creation flow. Two features: (1) **Track autocomplete** on the title field provides canonical artist/title names from MusicBrainz + Spotify data via the karaoke-decide catalog API, improving text consistency for YouTube releases. Autocomplete activates when the artist field has a value; selecting a suggestion overwrites both artist and title with canonical names. (2) **Community version detection** checks karaokenerds.com for existing high-quality karaoke versions — if found, a dismissible green banner suggests the user check those versions first before spending credits. New backend: 3 endpoints (`/api/catalog/artists`, `/api/catalog/tracks`, `/api/catalog/community-check`) with per-user rate limiting (20 req/min) and in-memory TTL caching. New services: `catalog_proxy_service.py` (proxies to karaoke-decide), `karaokenerds_service.py` (scrapes karaokenerds.com). New frontend components: `AutocompleteInput` (reusable), `CommunityVersionBanner`. See [API.md](API.md#catalog-song-lookup).
- **Feedback-for-Credits** (2026-03-01): Added a feedback-for-credits mechanism available to all users (replaces the old beta-only feedback flow). Users who complete 2+ karaoke videos can submit product feedback (star ratings + text) to earn 2 free credits (total possible free credits: 4 — 2 welcome + 2 feedback). New endpoints: `GET /api/users/feedback/eligibility`, `POST /api/users/feedback`. The `/api/users/me` response includes `feedback_eligible: bool` so the frontend can show/hide prompts without an extra API call. Frontend shows a dismissible banner on the dashboard and a "Earn 2 Free Credits" menu item in the user dropdown when eligible. Feedback stored in `user_feedback` Firestore collection with duplicate prevention via `has_submitted_feedback` flag on user model. Welcome email updated with credit-focused messaging and feedback teaser. See [API.md](API.md#user-feedback-for-credits).
- **Feedback-for-Credits** (2026-03-01): Added a feedback-for-credits mechanism available to all users (replaces the old beta-only feedback flow). Users who complete 2+ karaoke videos can submit product feedback (star ratings + text) to earn 1 free credit (total possible free credits: 2 — 1 welcome + 1 feedback). New endpoints: `GET /api/users/feedback/eligibility`, `POST /api/users/feedback`. The `/api/users/me` response includes `feedback_eligible: bool` so the frontend can show/hide prompts without an extra API call. Frontend shows a dismissible banner on the dashboard and a "Earn 1 Free Credit" menu item in the user dropdown when eligible. Feedback stored in `user_feedback` Firestore collection with duplicate prevention via `has_submitted_feedback` flag on user model. Welcome email updated with credit-focused messaging and feedback teaser. See [API.md](API.md#user-feedback-for-credits).
- **Remove Beta Program from Homepage** (2026-03-01): Removed beta enrollment from landing page and replaced with prominent "2 Free Credits" messaging. Beta enrollment endpoint preserved for backward compatibility but no longer actively promoted. See PR #430.
- **Remove Beta Program from Homepage** (2026-03-01): Removed beta enrollment from landing page and replaced with prominent "1 Free Credit" messaging. Beta enrollment endpoint preserved for backward compatibility but no longer actively promoted. See PR #430.
- **Fix Event Loop Blocking in Audio Search Endpoints** (2026-02-28): Fixed `/api/audio-search/{job_id}/select` taking 20-36s to respond (should be <1s) and `/api/audio-search/search` sometimes taking 25-47s. **Root cause**: Async endpoints called sync methods that create new event loops via `loop.run_until_complete()`, blocking the FastAPI event loop — response body was queued but never flushed. **Fix**: RED/OPS and Spotify download paths now call `FlacfetchClient` async methods directly (matching `YouTubeDownloadService` pattern), generic downloads use `asyncio.to_thread()`, search endpoint uses `search_async()`. Also fixed `InsufficientCreditsError` occasionally returning 500 instead of 402 by using `isinstance()` check. Added 14 new tests. See [LESSONS-LEARNED.md](LESSONS-LEARNED.md#never-call-sync-over-async-from-fastapi-async-routes-feb-2026).
+1 -1
View File
@@ -335,7 +335,7 @@ function AppPageContent() {
<div className="flex items-center gap-3 min-w-0">
<Gift className="w-5 h-5 text-green-500 shrink-0" />
<p className="text-sm" style={{ color: 'var(--text)' }}>
<strong>Earn 2 free credits!</strong>{' '}
<strong>Earn 1 free credit!</strong>{' '}
<span style={{ color: 'var(--text-muted)' }}>
Share your feedback on the karaoke creation experience.
</span>
+3 -3
View File
@@ -262,7 +262,7 @@ function ConsumerLandingPage() {
Create It Yourself
<span className="ml-1 px-2 py-0.5 bg-white/20 rounded-full text-sm">$5</span>
</button>
<span className="text-green-400 text-sm">2 free credits included - no payment required</span>
<span className="text-green-400 text-sm">1 free credit included - no payment required</span>
</div>
<div className="flex flex-col items-center gap-2">
<a
@@ -451,12 +451,12 @@ function ConsumerLandingPage() {
<div className="max-w-4xl mx-auto">
<h2 className="text-3xl font-bold text-center mb-4">Simple Pricing</h2>
<p className="text-dark-400 text-center mb-4 max-w-xl mx-auto">
Start with 2 free credits, then buy more to save more.
Start with 1 free credit, then buy more to save more.
</p>
<div className="bg-green-500/10 border border-green-500/30 rounded-2xl p-6 text-center mb-10 max-w-sm mx-auto">
<div className="text-sm text-green-400 font-medium mb-1">Every new account includes</div>
<div className="text-4xl font-bold text-green-400 mb-1">2 Free Credits</div>
<div className="text-4xl font-bold text-green-400 mb-1">1 Free Credit</div>
<div className="text-sm text-dark-400 mb-4">No payment required</div>
<button
onClick={() => setShowAuthDialog(true)}
+1 -1
View File
@@ -114,7 +114,7 @@ export function AuthStatus({ onAuthChange }: AuthStatusProps) {
className="text-green-500 focus:text-green-400 focus:bg-secondary"
>
<Gift className="w-4 h-4 mr-2" />
<span>Earn 2 Free Credits</span>
<span>Earn 1 Free Credit</span>
</DropdownMenuItem>
)}
{(user.role === "admin" || user.email?.endsWith("@nomadkaraoke.com")) && (
@@ -156,7 +156,7 @@ export function FeedbackDialog({ open, onClose }: FeedbackDialogProps) {
<DialogHeader>
<DialogTitle className="text-foreground flex items-center gap-2">
<Gift className="w-5 h-5 text-green-500" />
Share Your Feedback — Earn 2 Free Credits
Share Your Feedback — Earn 1 Free Credit
</DialogTitle>
<DialogDescription className="text-muted-foreground">
Tell us about your experience creating karaoke videos. Your feedback directly shapes what we build next.
@@ -268,7 +268,7 @@ export function FeedbackDialog({ open, onClose }: FeedbackDialogProps) {
Submitting...
</>
) : (
'Submit Feedback & Earn 2 Credits'
'Submit Feedback & Earn 1 Credit'
)}
</Button>
</div>
+1 -1
View File
@@ -115,7 +115,7 @@ test.describe('Landing Page', () => {
await page.goto('/');
await page.waitForLoadState('networkidle');
await expect(page.getByText('2 Free Credits', { exact: true })).toBeVisible();
await expect(page.getByText('1 Free Credit', { exact: true })).toBeVisible();
await expect(page.getByRole('button', { name: /sign up free/i })).toBeVisible();
});
+1 -1
View File
@@ -49,7 +49,7 @@ test.describe('Smoke Tests', () => {
await page.goto('/');
await page.waitForLoadState('networkidle');
await expect(page.getByText('2 Free Credits', { exact: true })).toBeVisible();
await expect(page.getByText('1 Free Credit', { exact: true })).toBeVisible();
await expect(page.getByRole('button', { name: /sign up free/i })).toBeVisible();
});
});
+1 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.150.3"
version = "0.150.4"
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"