Upgrade docs Better Auth and Polar to API 2026-10 - #3149

Summary

• Upgrade docs auth/billing to Better Auth 1.7.7, @polar-sh/better-auth 2.0.0, and Polar SDK 1.0.1; pin the matching auth migration CLI.
• Adopt Polar's 2026-10 API, versioned SDK functions and snake_case payloads; update the client plugin and auth middleware imports.
• Preserve logged-out pay-first provisioning, customer linking, sign-in links, and subscription plan updates. Supply the new user provisioning source required by Better Auth.

Related: #2749 (dependency upgrade), #2870 (pay-first checkout).

Validation

• Targeted type-aware lint/type check passed for server auth, client auth, and the Next.js auth route (three files).
• Formatting, git diff --check, mocked auth/billing smoke checks, and offline frozen-lockfile installation passed.
• Docs workspace dependency builds and editor dependency builds passed; Next.js development server served pricing and auth routes successfully. A full production Next.js build was not run.
• Live Polar sandbox: completed logged-out monthly Business checkout; actual webhooks provisioned and linked the account; magic-link login produced a verified paid session.
• Repeated a reconstructed, signed subscription.active payload twice: both requests returned 200 with no duplicate user. This was not a dashboard replay of the original event.
• Actual sandbox scheduled cancellation preserved paid access; immediate revocation delivered webhooks and returned the authenticated session to Free.
• Isolated production-copy rehearsal: restored the public schema into private local Postgres. Better Auth generate and migrate reported no migrations needed. All six tables' row counts and data hashes remained unchanged; no duplicate provider account keys were present. This was a schema rehearsal, not a runtime login test against restored records.
• The CLI warned that existing verification.createdAt / updatedAt columns are nullable; neither contained nulls. That drift was not silently altered.

Production was accessed read-only for the copy; no production migrations or webhook changes were performed. The copied database, local SQLite data, and temporary Postgres instance were removed. Credentials, database dumps, and local dev proxy settings are not included in this PR. Smoke checks were temporary tooling, not new committed regression tests.

Production rollout (required, not performed by this PR)

• Confirm Node.js 22.12+ and production environment variables; rotate credentials exposed during troubleshooting before rollout.
• Take a fresh database backup; check duplicate (providerId, accountId) keys and review CLI generation against the actual target POSTGRES_URL. From docs/, run pnpm exec auth generate --config ./lib/auth.ts --output ./auth-migration.sql, then apply reviewed changes with pnpm exec auth migrate --config ./lib/auth.ts (the tested copy required none). Without POSTGRES_URL, development targets local SQLite instead.
• Drain old-version Polar webhook deliveries using the existing handler. Coordinate deployment with changing the production /api/auth/polar/webhooks endpoint to API 2026-10; queued/redelivered events retain their original contract.
• Verify email/password, verification, existing GitHub/sponsor accounts, and magic-link behavior; unverified accounts may require a password reset under Better Auth 1.7.
• Smoke-test new/existing and authenticated/pay-first purchases, customer portal access, plan updates, cancellation/revocation, and repeat delivery. Monitor auth and webhook failures.

Rollback must coordinate the application, database state, and Polar webhook contract; reverting dependencies alone is insufficient.

Summary by CodeRabbit

• Improvements
  • Updated the documentation site’s authentication and payment integration to work with the latest Polar services.
  • Improved account linking and account creation for pay-first checkouts.