feat(billing): Polar.sh Pro subscription integration

- Webhook handler verifies HMAC-SHA256 sig and updates user role on
  subscription.created / subscription.updated / subscription.revoked
- Audio endpoint gated: free users limited to 3 chapters/day via Valkey
  counter; returns 402 {error:'pro_required'} when limit reached
- Translation proxy endpoint enforces 402 for non-pro users
- AudioPlayer.svelte surfaces 402 via onProRequired callback + upgrade banner
- Chapter page shows lock icon + upgrade prompts for gated translation langs
- Profile page: subscription section shows Pro badge + manage link (active)
  or monthly/annual checkout buttons (free); isPro resolved fresh from DB
- i18n: 13 new profile_subscription_* keys across all 5 locales

ui/src/routes/api/audio/[slug]/[n]/+server.ts

@@ -2,6 +2,34 @@ import { error } from '@sveltejs/kit';
 import type { RequestHandler } from './$types';
 import { log } from '$lib/server/logger';
 import { backendFetch } from '$lib/server/scraper';
+import * as cache from '$lib/server/cache';
+
+const FREE_DAILY_AUDIO_LIMIT = 3;
+
+/**
+ * Return the number of audio chapters a user/session has generated today,
+ * and increment the counter. Uses a Valkey key that expires at midnight UTC.
+ *
+ * Key: audio:daily:<userId|sessionId>:<YYYY-MM-DD>
+ */
+async function incrementDailyAudioCount(identifier: string): Promise<number> {
+	const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+	const key = `audio:daily:${identifier}:${today}`;
+	// Seconds until end of day UTC
+	const now = new Date();
+	const endOfDay = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
+	const ttl = Math.ceil((endOfDay.getTime() - now.getTime()) / 1000);
+	// Use raw get/set with increment so we can read + increment atomically
+	try {
+		const raw = await cache.get<number>(key);
+		const current = (raw ?? 0) + 1;
+		await cache.set(key, current, ttl);
+		return current;
+	} catch {
+		// On cache failure, fail open (don't block audio for cache errors)
+		return 0;
+	}
+}
 
 /**
  * POST /api/audio/[slug]/[n]
@@ -15,14 +43,39 @@ import { backendFetch } from '$lib/server/scraper';
  *       GET /api/presign/audio to obtain a direct MinIO presigned URL.
  *   202 { task_id: string, status: "pending"|"generating" }  — generation
  *       enqueued; poll GET /api/audio/status/[slug]/[n]?voice=... until done.
+ *   402 { error: "pro_required", limit: 3 }  — free daily limit reached.
  */
-export const POST: RequestHandler = async ({ params, request }) => {
+export const POST: RequestHandler = async ({ params, request, locals }) => {
 	const { slug, n } = params;
 	const chapter = parseInt(n, 10);
 	if (!slug || !chapter || chapter < 1) {
 		error(400, 'Invalid slug or chapter number');
 	}
 
+	// ── Paywall: 3 audio chapters/day for free users ───────────────────────────
+	if (!locals.isPro) {
+		// Check if audio already exists (cached) before counting — no charge for
+		// re-requesting something already generated
+		const statusRes = await backendFetch(
+			`/api/audio/status/${slug}/${chapter}`
+		).catch(() => null);
+		const statusData = statusRes?.ok
+			? ((await statusRes.json().catch(() => ({}))) as { status?: string })
+			: {};
+
+		if (statusData.status !== 'done') {
+			const identifier = locals.user?.id ?? locals.sessionId;
+			const count = await incrementDailyAudioCount(identifier);
+			if (count > FREE_DAILY_AUDIO_LIMIT) {
+				log.info('polar', 'free audio limit reached', { identifier, count });
+				return new Response(
+					JSON.stringify({ error: 'pro_required', limit: FREE_DAILY_AUDIO_LIMIT }),
+					{ status: 402, headers: { 'Content-Type': 'application/json' } }
+				);
+			}
+		}
+	}
+
 	let body: { voice?: string } = {};
 	try {
 		body = await request.json();
@@ -62,4 +115,3 @@ export const POST: RequestHandler = async ({ params, request }) => {
 		{ headers: { 'Content-Type': 'application/json' } }
 	);
 };
-

ui/src/routes/api/translation/[slug]/[n]/+server.ts

@@ -0,0 +1,69 @@
+import { error } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { log } from '$lib/server/logger';
+import { backendFetch } from '$lib/server/scraper';
+
+const SUPPORTED_LANGS = new Set(['ru', 'id', 'pt', 'fr']);
+
+/**
+ * POST /api/translation/[slug]/[n]?lang=<lang>
+ * Proxy to backend translation enqueue endpoint.
+ * Enforces Pro gate — free users cannot enqueue translations.
+ *
+ * GET /api/translation/[slug]/[n]?lang=<lang>
+ * Proxy to backend translation fetch (no gate — already gated at page.server.ts).
+ */
+export const GET: RequestHandler = async ({ params, url }) => {
+	const { slug, n } = params;
+	const lang = url.searchParams.get('lang') ?? '';
+	const res = await backendFetch(
+		`/api/translation/${encodeURIComponent(slug)}/${n}?lang=${lang}`
+	);
+	if (!res.ok) {
+		return new Response(null, { status: res.status });
+	}
+	const data = await res.json();
+	return new Response(JSON.stringify(data), {
+		headers: { 'Content-Type': 'application/json' }
+	});
+};
+
+export const POST: RequestHandler = async ({ params, url, locals }) => {
+	const { slug, n } = params;
+	const chapter = parseInt(n, 10);
+	const lang = url.searchParams.get('lang') ?? '';
+
+	if (!slug || !chapter || chapter < 1) error(400, 'Invalid slug or chapter');
+	if (!SUPPORTED_LANGS.has(lang)) error(400, 'Unsupported language');
+
+	// ── Pro gate ──────────────────────────────────────────────────────────────
+	if (!locals.isPro) {
+		log.info('polar', 'translation blocked for free user', {
+			userId: locals.user?.id,
+			slug,
+			chapter,
+			lang
+		});
+		return new Response(
+			JSON.stringify({ error: 'pro_required' }),
+			{ status: 402, headers: { 'Content-Type': 'application/json' } }
+		);
+	}
+
+	const res = await backendFetch(
+		`/api/translation/${encodeURIComponent(slug)}/${chapter}?lang=${lang}`,
+		{ method: 'POST' }
+	);
+
+	if (!res.ok) {
+		const text = await res.text().catch(() => '');
+		log.error('translation', 'backend translation enqueue failed', { slug, chapter, lang, status: res.status, body: text });
+		error(res.status as Parameters<typeof error>[0], text || 'Translation enqueue failed');
+	}
+
+	const data = await res.json();
+	return new Response(JSON.stringify(data), {
+		status: res.status,
+		headers: { 'Content-Type': 'application/json' }
+	});
+};

ui/src/routes/api/translation/status/[slug]/[n]/+server.ts

@@ -0,0 +1,23 @@
+import type { RequestHandler } from './$types';
+import { backendFetch } from '$lib/server/scraper';
+
+/**
+ * GET /api/translation/status/[slug]/[n]?lang=<lang>
+ * Proxies the translation status check to the backend.
+ */
+export const GET: RequestHandler = async ({ params, url }) => {
+	const { slug, n } = params;
+	const lang = url.searchParams.get('lang') ?? '';
+	const res = await backendFetch(
+		`/api/translation/status/${encodeURIComponent(slug)}/${n}?lang=${lang}`
+	);
+	if (!res.ok) {
+		return new Response(JSON.stringify({ status: 'idle' }), {
+			headers: { 'Content-Type': 'application/json' }
+		});
+	}
+	const data = await res.json();
+	return new Response(JSON.stringify(data), {
+		headers: { 'Content-Type': 'application/json' }
+	});
+};

ui/src/routes/api/webhooks/polar/+server.ts

@@ -0,0 +1,52 @@
+import type { RequestHandler } from './$types';
+import { log } from '$lib/server/logger';
+import { verifyPolarWebhook, handleSubscriptionEvent } from '$lib/server/polar';
+
+/**
+ * POST /api/webhooks/polar
+ *
+ * Receives Polar subscription lifecycle events and syncs user roles in PocketBase.
+ * Signature is verified via HMAC-SHA256 before any processing.
+ */
+export const POST: RequestHandler = async ({ request }) => {
+	const rawBody = await request.text();
+	const signature = request.headers.get('webhook-signature') ?? '';
+
+	if (!verifyPolarWebhook(rawBody, signature)) {
+		log.warn('polar', 'webhook signature verification failed');
+		return new Response('Unauthorized', { status: 401 });
+	}
+
+	let event: { type: string; data: Record<string, unknown> };
+	try {
+		event = JSON.parse(rawBody);
+	} catch {
+		return new Response('Bad Request', { status: 400 });
+	}
+
+	const { type, data } = event;
+	log.info('polar', 'webhook received', { type });
+
+	try {
+		switch (type) {
+			case 'subscription.created':
+			case 'subscription.updated':
+			case 'subscription.revoked':
+				await handleSubscriptionEvent(type, data as unknown as Parameters<typeof handleSubscriptionEvent>[1]);
+				break;
+
+			case 'order.created':
+				// One-time purchases — no role change needed for now
+				log.info('polar', 'order.created (no action)', { orderId: data.id });
+				break;
+
+			default:
+				log.debug('polar', 'unhandled webhook event type', { type });
+		}
+	} catch (err) {
+		// Log but return 200 — Polar retries on non-2xx, we don't want retry storms
+		log.error('polar', 'webhook handler error', { type, err: String(err) });
+	}
+
+	return new Response('OK', { status: 200 });
+};