Payments with Polar & BetterAuth

// auth/server.ts
import { betterAuth } from 'better-auth';
import {
	polar,
	checkout,
	portal,
	usage,
	webhooks,
} from '@polar-sh/better-auth';
import { Polar } from '@polar-sh/sdk';

export const polarSdk = new Polar({
	accessToken: process.env.POLAR_ACCESS_TOKEN!,
	// 'sandbox' in dev, 'production' in prod
	server: process.env.POLAR_ENV === 'production' ? 'production' : 'sandbox',
});

export const auth = betterAuth({
	// ... your core BetterAuth config (session, user model, etc.)
	plugins: [
		polar({
			client: polarSdk,
			createCustomerOnSignUp: true, // auto Polar Customer per user
			// Optionally attach extra metadata on customer creation:
			// getCustomerCreateParams: ({ user }, request) => ({
			//   metadata: { appUserId: user.id },
			// }),
			use: [
				checkout({
					products: [
						{
							productId: '123-456-789', // Polar Product ID
							slug: 'pro', // Used on client: authClient.checkout({ slug: 'pro' })
						},
					],
					successUrl: '/billing/success?checkout_id={CHECKOUT_ID}',
					authenticatedUsersOnly: true,
				}),
				portal(),
				usage(),
				webhooks({
					secret: process.env.POLAR_WEBHOOK_SECRET!,
					// We'll fill these in later:
					// onCustomerStateChanged: async (payload, ctx) => { ... },
					// onOrderPaid: async (payload, ctx) => { ... },
					// onPayload: async (payload, ctx) => { ... },
				}),
			],
		}),
	],
});

// lib/auth-client.ts
import { createAuthClient } from 'better-auth/react';
import { polarClient } from '@polar-sh/better-auth';

export const authClient = createAuthClient({
	plugins: [polarClient()],
});

// billing/sync.ts
import type { Polar, CustomerState } from '@polar-sh/sdk';

// Re-export the CustomerState type from the SDK for use in your app
export type { CustomerState };

export interface KV<T> {
	get(key: string): Promise<T | null>;
	set(key: string, value: T, opts?: { ex?: number }): Promise<void>;
	delete?(key: string): Promise<void>;
}

// TTL balances freshness vs API rate limits
// Longer TTL (1h+) reduces API calls; webhooks provide real-time updates
const STATE_TTL_SECONDS = 60 * 60; // 1 hour

export async function syncPolarStateToKVByExternalId(
	polar: Polar,
	kv: KV<CustomerState | null>,
	externalId: string
): Promise<CustomerState | null> {
	try {
		const state = await polar.customers.getStateExternal({ externalId });
		await kv.set(`polar:state:${externalId}`, state, {
			ex: STATE_TTL_SECONDS,
		});

		return state;
	} catch (error: unknown) {
		// Different runtimes / SDK versions may expose status in different places.
		// Type-safe error property access
		const status =
			error && typeof error === 'object' && 'status' in error
				? (error as { status: number }).status
				: error && typeof error === 'object' && 'statusCode' in error
				? (error as { statusCode: number }).statusCode
				: error && typeof error === 'object' && 'response' in error
				? (error as { response?: { status?: number } }).response?.status
				: undefined;

		if (status === 404) {
			// Customer doesn't exist yet - cache null to avoid repeated 404s
			await kv.set(`polar:state:${externalId}`, null, {
				ex: STATE_TTL_SECONDS,
			});
			return null;
		}

		if (status === 401 || status === 403) {
			console.error('[sync] Polar access token invalid or expired', {
				externalId,
				status,
				error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
			});
			// Alert ops team - this requires immediate attention
			throw new Error('Polar authentication failed - check access token');
		}

		if (status === 429) {
			console.error('[sync] Polar rate limit exceeded', {
				externalId,
				status,
				error: error instanceof Error ? { message: error.message } : error,
			});
			// Consider implementing exponential backoff or queuing
			throw error;
		}

		// Network or other errors - let caller handle retry logic
		console.error('[sync] Failed to sync customer state', { externalId, error });
		throw error;
	}
}

// routes/billing/success.ts
import { auth } from '../auth/server';
import { polarSdk } from '../auth/server';
import { syncPolarStateToKVByExternalId } from '../billing/sync';
import { isActiveSubscriber } from '../billing/access';
import { kv } from '../kv'; // your KV/DB adapter

/**
 * Pseudonymise user ID for safer logging.
 * Example: log a short, stable identifier derived from userId instead of raw PII.
 *
 * NOTE: This is still personal data under GDPR if you can link it back.
 * Use a real hash in production and keep keys separate.
 */
async function hashUserId(userId: string): Promise<string> {
	const data = new TextEncoder().encode(userId);
	const digest = await crypto.subtle.digest('SHA-256', data);
	const bytes = Array.from(new Uint8Array(digest));
	const hex = bytes.map((b) => b.toString(16).padStart(2, '0')).join('');
	return hex.slice(0, 8);
}

export async function handleBillingSuccess(req: Request): Promise<Response> {
	// 1. Auth user using BetterAuth
	const session = await auth.getSession(req);
	const user = session?.user;
	if (!user) {
		return new Response('Unauthorized', { status: 401 });
	}

	const url = new URL(req.url);
	const checkoutId = url.searchParams.get('checkout_id');

	// 2. (Recommended) Verify checkout belongs to this user
	if (checkoutId) {
		// Validate checkout ID format (Polar uses 'chk_' prefix)
		if (!checkoutId.startsWith('chk_')) {
			console.warn('[billing-success] Invalid checkout ID format', { checkoutId });
			return new Response('Invalid checkout ID format', { status: 400 });
		}

		try {
			const checkout = await polarSdk.checkouts.get({ id: checkoutId });

			// Verify checkout has a customer
			if (!checkout.customer?.externalId) {
				console.warn('[billing-success] Checkout missing customer', checkoutId);
				return new Response('Checkout has no customer', { status: 400 });
			}

			// Verify checkout belongs to authenticated user
			if (checkout.customer.externalId !== user.id) {
				console.warn('[billing-success] Checkout ownership mismatch', {
					checkoutId,
					expectedHash: hashUserId(user.id),
					actualHash: hashUserId(checkout.customer.externalId),
				});
				return new Response('Checkout belongs to different user', {
					status: 403,
				});
			}

			// Verify checkout was successful
			if (checkout.status !== 'succeeded' && checkout.status !== 'confirmed') {
				console.warn('[billing-success] Checkout not completed', {
					checkoutId,
					status: checkout.status,
				});
				return new Response('Checkout not completed', { status: 400 });
			}
		} catch (err) {
			console.error('[billing-success] Checkout verification failed', err);
			// Fail closed: don't proceed if we can't verify the checkout
			return new Response('Failed to verify checkout', { status: 500 });
		}
	}

	// 3. Eagerly sync Customer State
	let state: CustomerState | null;
	try {
		state = await syncPolarStateToKVByExternalId(polarSdk, kv, user.id);
	} catch (error) {
		console.error('[billing-success] Failed to sync state', {
			userIdHash: hashUserId(user.id),
			error,
		});
		// Polar API unreachable - redirect to finishing-setup page
		// which will poll for subscription status
		const baseUrl = process.env.BASE_URL || req.headers.get('origin') || 'http://localhost:3000';
		return Response.redirect(`${baseUrl}/billing/finishing-setup`, 302);
	}

	// 4. Route based on entitlements
	const baseUrl = process.env.BASE_URL || req.headers.get('origin') || 'http://localhost:3000';

	if (isActiveSubscriber(state)) {
		return Response.redirect(`${baseUrl}/app`, 302);
	}

	// Race with webhooks; show a safe "finishing setup" page
	// This page should poll for subscription status
	return Response.redirect(`${baseUrl}/billing/finishing-setup`, 302);
}

// auth/server.ts (continued)
import { syncPolarStateToKVByExternalId } from '../billing/sync';
import { kv } from '../kv';

export const auth = betterAuth({
	// ...
	plugins: [
		polar({
			client: polarSdk,
			createCustomerOnSignUp: true,
			use: [
				checkout({
					/* ... */
				}),
				portal(),
				usage(),
				webhooks({
					secret: process.env.POLAR_WEBHOOK_SECRET!,
					async onCustomerStateChanged(event, ctx) {
						// Replay attack protection: Reject events older than 5 minutes
						const eventTime = new Date(event.createdAt);
						const age = Date.now() - eventTime.getTime();
						const MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes

						if (age > MAX_AGE_MS) {
							console.warn('[webhook] Event too old, ignoring', {
								eventId: event.id,
								ageSeconds: Math.round(age / 1000),
							});
							return; // Don't process old events
						}

						const externalId = event.data.customer.externalId;
						if (!externalId) {
							console.warn('[webhook] No externalId in customer.state_changed', {
								eventId: event.id,
							});
							return; // Not an error - customer might not have external ID yet
						}

						// Idempotency: Check if we've already processed this event
						const processedKey = `polar:webhook:processed:${event.id}`;
						const alreadyProcessed = await kv.get(processedKey);
						if (alreadyProcessed) {
							console.log('[webhook] Event already processed, skipping', {
								eventId: event.id,
								externalId,
							});
							return;
						}

						try {
							await syncPolarStateToKVByExternalId(polarSdk, kv, externalId);

							// Mark event as processed (store for 24 hours)
							await kv.set(processedKey, true, { ex: 86400 });

							console.log('[webhook] Synced customer state', {
								eventId: event.id,
								externalId,
							});
						} catch (err) {
							console.error('[webhook] Sync failed for customer.state_changed', {
								eventId: event.id,
								externalId,
								error: err,
							});
							// Optionally: push to dead-letter queue for manual retry
							// await dlq.push({ eventId: event.id, externalId, error: err });

							// Re-throw to let Polar retry the webhook
							throw err;
						}
					},
					async onOrderPaid(event, ctx) {
						// Replay attack protection: Reject events older than 5 minutes
						const eventTime = new Date(event.createdAt);
						const age = Date.now() - eventTime.getTime();
						const MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes

						if (age > MAX_AGE_MS) {
							console.warn('[webhook] Event too old, ignoring', {
								eventId: event.id,
								ageSeconds: Math.round(age / 1000),
							});
							return; // Don't process old events
						}

						const externalId = event.data.customer?.externalId;
						if (!externalId) {
							console.warn('[webhook] No externalId in order.paid', {
								eventId: event.id,
							});
							return;
						}

						// Idempotency: Check if we've already processed this event
						const processedKey = `polar:webhook:processed:${event.id}`;
						const alreadyProcessed = await kv.get(processedKey);
						if (alreadyProcessed) {
							console.log('[webhook] Event already processed, skipping', {
								eventId: event.id,
								externalId,
							});
							return;
						}

						try {
							await syncPolarStateToKVByExternalId(polarSdk, kv, externalId);

							// Mark event as processed (store for 24 hours)
							await kv.set(processedKey, true, { ex: 86400 });

							console.log('[webhook] Synced on order.paid', {
								eventId: event.id,
								externalId,
							});
						} catch (err) {
							console.error('[webhook] Sync failed for order.paid', {
								eventId: event.id,
								externalId,
								error: err,
							});
							throw err;
						}
					},
					// Optional: catch-all logging
					async onPayload(event, ctx) {
						console.log('[polar webhook]', {
							type: event.type,
							id: event.id,
							timestamp: new Date().toISOString(),
						});
					},
				}),
			],
		}),
	],
});

// billing/access.ts
import type { CustomerState, KV } from './sync';

/**
 * Define which products/benefits unlock your "subscribed" experience.
 * Adjust these to match your Polar configuration.
 */
export type SubscriberPolicy = {
	// e.g. ['pro-plan', 'team-plan']
	allowedBenefitSlugs?: string[];

	// e.g. ['prod_12345678', 'prod_87654321']
	allowedProductIds?: string[];
};

export const DEFAULT_SUBSCRIBER_POLICY: SubscriberPolicy = {
	allowedBenefitSlugs: ['pro-plan'],
	// optionally also require specific product IDs:
	// allowedProductIds: ['prod_12345678'],
};

/**
 * Core helper: is this customer "subscribed" according to your policy?
 *
 * Policy-based entitlement check:
 * - If `allowedProductIds` is specified: checks if customer has active subscription to any allowed product
 * - If `allowedBenefitSlugs` is specified: checks if customer has any granted benefit matching allowed slugs
 * - Returns true if EITHER condition is met (OR logic)
 *
 * If neither is specified in policy, always returns false (explicit opt-in required).
 */
export function isActiveSubscriber(
	state: CustomerState | null | undefined,
	policy: SubscriberPolicy = DEFAULT_SUBSCRIBER_POLICY
): boolean {
	if (!state) return false;

	const { allowedBenefitSlugs, allowedProductIds } = policy;

	let hasAllowedSub = false;
	let hasAllowedBenefit = false;

	// Check subscription-based access
	// Only performs check if allowedProductIds is specified (length > 0)
	// This allows flexible policy configuration - omit to skip subscription checks
	if (Array.isArray(state.activeSubscriptions) && allowedProductIds?.length) {
		hasAllowedSub = state.activeSubscriptions.some((sub) =>
			allowedProductIds.includes(sub.productId)
		);
	}

	// Check benefit-based access
	// Only performs check if allowedBenefitSlugs is specified (length > 0)
	// Benefits can grant access independently of subscriptions
	if (Array.isArray(state.grantedBenefits) && allowedBenefitSlugs?.length) {
		hasAllowedBenefit = state.grantedBenefits.some((benefit) =>
			allowedBenefitSlugs.includes(benefit.slug)
		);
	}

	// OR logic: customer is "subscribed" if they have EITHER an allowed subscription OR an allowed benefit
	return hasAllowedSub || hasAllowedBenefit;
}

/** Check for a specific benefit slug ("beta-access", "enterprise-seat", etc.) */
export function hasBenefit(
	state: CustomerState | null | undefined,
	benefitSlug: string
): boolean {
	if (!state?.grantedBenefits) return false;
	return state.grantedBenefits.some((benefit) => benefit.slug === benefitSlug);
}

/**
 * Read a meter balance by slug (for usage-based entitlements).
 * For "increment" meters: returns total usage accumulated.
 * For "decrement" meters: returns remaining credits/quota.
 * Returns null if meter doesn't exist or isn't active.
 */
export function getMeterBalance(
	state: CustomerState | null | undefined,
	meterSlug: string
): number | null {
	if (!state?.activeMeters) return null;

	const meter = state.activeMeters.find((m) => m.slug === meterSlug);
	if (!meter || typeof meter.balance !== 'number') return null;

	return meter.balance;
}

/**
 * Prototype-friendly helper: ANY sub OR ANY benefit counts as "subscribed".
 * Fine for early demos; too broad for production.
 */
export function hasAnySubscriptionOrBenefit(
	state: CustomerState | null | undefined
): boolean {
	if (!state) return false;

	const hasSub =
		Array.isArray(state.activeSubscriptions) &&
		state.activeSubscriptions.length > 0;

	const hasBenefit =
		Array.isArray(state.grantedBenefits) && state.grantedBenefits.length > 0;

	return hasSub || hasBenefit;
}

// billing/guards.ts
import type { CustomerState, KV } from './sync';
import {
    isActiveSubscriber,
    DEFAULT_SUBSCRIBER_POLICY,
    SubscriberPolicy,
} from './access';

export async function requireSubscribedUser(
    kv: KV<CustomerState | null>,
    userId: string,
    policy: SubscriberPolicy = DEFAULT_SUBSCRIBER_POLICY
): Promise<CustomerState> {
    const state = await kv.get(`polar:state:${userId}`);
    if (!state || !isActiveSubscriber(state, policy)) {
        throw Object.assign(new Error('Subscription required'), { status: 403 });
    }
    return state;
}

import { describe, it, expect, vi } from 'vitest';
import { syncPolarStateToKVByExternalId } from '../billing/sync';
import { isActiveSubscriber } from '../billing/access';

describe('Billing Integration', () => {
  it('should sync customer state and validate subscription', async () => {
    const mockPolar = {
      customers: {
        getStateExternal: vi.fn().mockResolvedValue({
          customer: { id: 'cust_123', externalId: 'user_123' },
          activeSubscriptions: [
            { productId: 'prod_pro', status: 'active' },
          ],
          grantedBenefits: [{ slug: 'pro-plan' }],
          activeMeters: [],
        }),
      },
    };

    const mockKV = {
      get: vi.fn(),
      set: vi.fn(),
    };

    const state = await syncPolarStateToKVByExternalId(
      mockPolar as any,
      mockKV,
      'user_123'
    );

    expect(mockPolar.customers.getStateExternal).toHaveBeenCalledWith({
      externalId: 'user_123',
    });
    expect(mockKV.set).toHaveBeenCalled();
    expect(isActiveSubscriber(state)).toBe(true);
  });

  it('should handle 404 for non-existent customer', async () => {
    const mockPolar = {
      customers: {
        getStateExternal: vi.fn().mockRejectedValue({ status: 404 }),
      },
    };

    const mockKV = {
      get: vi.fn(),
      set: vi.fn(),
    };

    const state = await syncPolarStateToKVByExternalId(
      mockPolar as any,
      mockKV,
      'user_nonexistent'
    );

    expect(state).toBeNull();
    expect(mockKV.set).toHaveBeenCalledWith(
      'polar:state:user_nonexistent',
      null,
      expect.any(Object)
    );
  });
});