Add Polar Builder billing and credit lifecycle

[devhims]

Summary

• replace the previous Stripe placeholder with the Better Auth Polar plugin
• add Builder checkout, customer portal access, billing status, and the settings billing panel
• project Polar customer and subscription state into D1 through billing_accounts
• grant Builder credits only from verified paid-order webhooks
• reset refunded users to Starter and restore the Starter default credit balance
• document the Polar environment variables, secrets, webhook events, and deployment steps

Payment and credit policy

A successful order.paid event activates Builder and tops the current balance up to the 20,000-credit monthly allowance. Unused credits carry forward, but a renewal does not increase a balance already at or above the allowance.

A fully refunded order downgrades the account to Starter and adjusts the ledger so the resulting balance equals the 1,000-credit Starter default.

Polar order IDs and webhook event IDs provide idempotency. Billing projection, credit adjustment, and event recording run in one D1 batch. Credit changes also verify that the webhook owns the latest billing state, preventing an older paid event from restoring credits after a newer refund.

Calendar time, checkout redirects, and customer-state synchronization never grant credits.

Architecture

• Better Auth owns authentication and mounts Polar checkout, portal, and signed webhook routes.
• Polar remains the payment system of record.
• billing_accounts is the local authorization and billing UI projection.
• credit_ledger remains the source of truth for spendable credits.
• Wrangler applies the versioned D1 migration.
• This PR intentionally uses native D1 queries. The Drizzle refactor is isolated on a separate stacked branch.

Manual setup before deployment

1. Create the recurring Builder product in Polar.
2. Set POLAR_BUILDER_PRODUCT_ID for the target environment.
3. Store POLAR_ACCESS_TOKEN and POLAR_WEBHOOK_SECRET in Cloudflare secrets and local .dev.vars.
4. Configure the Polar webhook endpoint at /api/auth/polar/webhooks.
5. Enable order.paid, order.refunded, customer.state_changed, and subscription.revoked.
6. Apply migration 0014_polar_billing.sql before deploying the Worker.

Verification

• platform TypeScript build
• 186 platform unit tests
• 7 YouTube processor tests
• 11 Workers and isolated D1 integration tests
• payment tests cover renewal top-ups, retries, carried balances, refunds, stale event ordering, onboarding grants, reservations, settlements, releases, and insufficient balances

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
video2ctx	🟢 Ready	View Preview	Aug 20, 2026, 3:26 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
video2ctx-web	Ready	Preview	Aug 20, 2026 3:41pm