@hienlh/ppm 0.9.81 → 0.9.83

package/.opencode/skills/payment-integration/references/polar/best-practices.md

@@ -1,902 +0,0 @@
-# Polar Best Practices
-
-Production-proven patterns from real SaaS implementations covering SDK initialization, checkout flows, webhooks, discounts, fee calculations, and error handling.
-
-## Environment Configuration
-
-### Required Environment Variables
-```bash
-# Core API
-POLAR_API_KEY=polar_at_xxx           # Access token from Polar Dashboard
-POLAR_ORGANIZATION_ID=org_xxx        # Your organization ID
-POLAR_WEBHOOK_SECRET=whsec_xxx       # Webhook signature verification
-
-# Product IDs (one per product)
-POLAR_PRODUCT_ENGINEER_ID=prod_xxx
-POLAR_PRODUCT_MARKETING_ID=prod_xxx
-POLAR_PRODUCT_COMBO_ID=prod_xxx
-
-# Environment (optional, defaults to production)
-POLAR_ENV=production                  # 'production' or 'sandbox'
-```
-
-### Lazy Initialization Pattern
-```typescript
-// lib/polar.ts - Defer validation until first access
-import { Polar } from '@polar-sh/sdk';
-import { z } from 'zod';
-
-const polarEnvSchema = z.object({
-  POLAR_API_KEY: z.string().min(1),
-  POLAR_ORGANIZATION_ID: z.string().min(1),
-  POLAR_WEBHOOK_SECRET: z.string().min(1),
-});
-
-let _polar: Polar | null = null;
-let _env: z.infer<typeof polarEnvSchema> | null = null;
-
-export function getPolarEnv() {
-  if (!_env) {
-    _env = polarEnvSchema.parse({
-      POLAR_API_KEY: process.env.POLAR_API_KEY,
-      POLAR_ORGANIZATION_ID: process.env.POLAR_ORGANIZATION_ID,
-      POLAR_WEBHOOK_SECRET: process.env.POLAR_WEBHOOK_SECRET,
-    });
-  }
-  return _env;
-}
-
-export function getPolar() {
-  if (!_polar) {
-    const env = getPolarEnv();
-    const polarEnv = process.env.POLAR_ENV || 'production';
-    _polar = new Polar({
-      accessToken: env.POLAR_API_KEY,
-      server: polarEnv as 'production' | 'sandbox',
-    });
-  }
-  return _polar;
-}
-```
-
-**Key Benefit:** Module imports succeed at build time; validation deferred until runtime when env vars are available.
-
-## Checkout Flow Implementation
-
-### Standard Checkout API
-```typescript
-// app/api/checkout/polar/route.ts
-import { NextResponse } from 'next/server';
-import { z } from 'zod';
-import { getPolar, getPolarEnv } from '@/lib/polar';
-
-const checkoutSchema = z.object({
-  email: z.string().email(),
-  name: z.string().optional(),
-  productType: z.enum(['engineer_kit', 'marketing_kit', 'combo']),
-  githubUsername: z.string().min(1),
-  referralCode: z.string().regex(/^[A-Z0-9]{8}$/).optional(),
-  couponCode: z.string().optional(),
-});
-
-// Pricing in cents
-const PRODUCT_PRICES = {
-  engineer_kit: 9900,   // $99
-  marketing_kit: 9900,  // $99
-  combo: 14900,         // $149
-} as const;
-
-export async function POST(request: Request) {
-  try {
-    const body = await request.json();
-    const data = checkoutSchema.parse(body);
-    const polar = getPolar();
-    const env = getPolarEnv();
-
-    // 1. Normalize email
-    const normalizedEmail = data.email.toLowerCase().trim();
-
-    // 2. Validate GitHub username against GitHub API
-    const githubValid = await validateGitHubUsername(data.githubUsername);
-    if (!githubValid) {
-      return NextResponse.json(
-        { error: 'Invalid GitHub username' },
-        { status: 400 }
-      );
-    }
-
-    // 3. Get product ID and base price
-    const productId = getProductId(data.productType);
-    const originalAmount = PRODUCT_PRICES[data.productType];
-
-    // 4. Apply discount hierarchy (order matters!)
-    let finalAmount = originalAmount;
-    let polarDiscountId: string | undefined;
-    let discountMetadata: Record<string, any> = {};
-
-    // Step A: Apply coupon FIRST (if provided)
-    if (data.couponCode) {
-      const couponResult = await validateAndApplyCoupon(
-        data.couponCode,
-        productId,
-        originalAmount
-      );
-      if (couponResult.valid) {
-        finalAmount = originalAmount - couponResult.discountAmount;
-        discountMetadata.couponCode = data.couponCode;
-        discountMetadata.couponDiscountAmount = couponResult.discountAmount;
-      }
-    }
-
-    // Step B: Apply referral discount SECOND (on post-coupon price)
-    if (data.referralCode) {
-      const referralResult = await calculateReferralDiscount(
-        data.referralCode,
-        finalAmount, // Applied to post-coupon amount
-        normalizedEmail
-      );
-
-      if (referralResult.valid && referralResult.discountAmount > 0) {
-        // Validate discount calculation
-        if (referralResult.discountAmount <= 0) {
-          return NextResponse.json(
-            { error: 'Invalid discount calculation - contact support' },
-            { status: 400 }
-          );
-        }
-
-        finalAmount -= referralResult.discountAmount;
-        discountMetadata.referralCode = data.referralCode;
-        discountMetadata.referralDiscountAmount = referralResult.discountAmount;
-        discountMetadata.referrerId = referralResult.referrerId;
-      }
-    }
-
-    // 5. Create order record BEFORE Polar checkout
-    const order = await db.insert(orders).values({
-      id: crypto.randomUUID(),
-      email: normalizedEmail,
-      productType: data.productType,
-      amount: finalAmount,
-      originalAmount,
-      currency: 'USD',
-      status: 'pending',
-      paymentProvider: 'polar',
-      referredBy: discountMetadata.referrerId,
-      discountAmount: originalAmount - finalAmount,
-      metadata: JSON.stringify({
-        ...discountMetadata,
-        githubUsername: data.githubUsername,
-      }),
-    }).returning();
-
-    // 6. Create dynamic Polar discount (if referral applied)
-    if (discountMetadata.referrerId && discountMetadata.referralDiscountAmount > 0) {
-      try {
-        const discount = await polar.discounts.create({
-          type: 'fixed',
-          name: `referral-${order[0].id.slice(0, 8)}`,
-          amount: discountMetadata.referralDiscountAmount,
-          currency: 'usd',
-          duration: 'once',
-          maxRedemptions: 1,
-          products: [productId],
-          metadata: {
-            orderId: order[0].id,
-            type: 'referral',
-            referrerId: discountMetadata.referrerId,
-          },
-        });
-        polarDiscountId = discount.id;
-      } catch (error) {
-        // FAIL-OPEN: Proceed with full price, flag for manual refund
-        console.error('⚠️ Failed to create Polar discount:', error);
-      }
-    }
-
-    // 7. Create Polar checkout session
-    const checkout = await polar.checkouts.create({
-      productPriceId: productId,
-      customerEmail: normalizedEmail,
-      successUrl: `${process.env.NEXT_PUBLIC_URL}/checkout/success?orderId=${order[0].id}`,
-      discountId: polarDiscountId,
-      allowDiscountCodes: !polarDiscountId, // Prevent stacking
-      metadata: {
-        orderId: order[0].id,
-        githubUsername: data.githubUsername,
-        referredBy: discountMetadata.referrerId,
-      },
-    });
-
-    return NextResponse.json({
-      checkoutUrl: checkout.url,
-      orderId: order[0].id,
-    });
-
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      return NextResponse.json({ error: error.errors }, { status: 400 });
-    }
-    console.error('Checkout error:', error);
-    return NextResponse.json(
-      { error: 'Failed to create checkout' },
-      { status: 500 }
-    );
-  }
-}
-```
-
-### Discount Application Order (Critical)
-```
-1. Original price (e.g., $99)
-2. Apply coupon discount FIRST → post-coupon price (e.g., $79)
-3. Apply referral discount SECOND → final price (e.g., $63.20)
-
-Never apply referral to original price if coupon was used!
-```
-
-## Webhook Handling
-
-### Signature Verification
-```typescript
-// app/api/webhooks/polar/route.ts
-import { validateEvent } from '@polar-sh/sdk/webhooks';
-import { NextResponse } from 'next/server';
-
-export async function POST(request: Request) {
-  const payload = await request.text();
-  const headers = Object.fromEntries(request.headers);
-  const secret = process.env.POLAR_WEBHOOK_SECRET!;
-
-  let webhookEvent;
-  try {
-    webhookEvent = validateEvent(payload, headers, secret);
-  } catch (error) {
-    console.error('Invalid webhook signature:', error);
-    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
-  }
-
-  // Extract event ID for idempotency
-  const parsedPayload = JSON.parse(payload);
-  const eventId = parsedPayload.id || `${parsedPayload.type}-${Date.now()}`;
-
-  // Check for duplicate processing
-  const existingEvent = await db.select()
-    .from(webhookEvents)
-    .where(eq(webhookEvents.eventId, eventId))
-    .limit(1);
-
-  if (existingEvent.length > 0) {
-    console.log(`Duplicate webhook ignored: ${eventId}`);
-    return NextResponse.json({ received: true });
-  }
-
-  // Record event BEFORE processing (idempotency)
-  await db.insert(webhookEvents).values({
-    id: crypto.randomUUID(),
-    provider: 'polar',
-    eventType: webhookEvent.type,
-    eventId,
-    payload,
-    processed: false,
-  });
-
-  try {
-    await handleWebhookEvent(webhookEvent);
-
-    // Mark as processed
-    await db.update(webhookEvents)
-      .set({ processed: true, processedAt: new Date() })
-      .where(eq(webhookEvents.eventId, eventId));
-
-  } catch (error) {
-    // Log error but don't fail the webhook
-    await db.update(webhookEvents)
-      .set({
-        processed: true,
-        processedAt: new Date(),
-        error: error instanceof Error ? error.message : 'Unknown error',
-      })
-      .where(eq(webhookEvents.eventId, eventId));
-  }
-
-  return NextResponse.json({ received: true });
-}
-```
-
-### Event Handlers
-```typescript
-async function handleWebhookEvent(event: WebhookEvent) {
-  switch (event.type) {
-    case 'checkout.created':
-      // Order already exists from API - just log
-      console.log(`Checkout created: ${event.data.id}`);
-      break;
-
-    case 'checkout.updated':
-      await handleCheckoutUpdated(event.data);
-      break;
-
-    case 'order.created':
-      await handleOrderCreated(event.data);
-      break;
-
-    case 'order.refunded':
-      await handleOrderRefunded(event.data);
-      break;
-
-    default:
-      console.log(`Unhandled event type: ${event.type}`);
-  }
-}
-
-async function handleOrderCreated(order: PolarOrder) {
-  const orderId = order.metadata?.orderId;
-  if (!orderId) {
-    console.error('Order missing orderId in metadata');
-    return;
-  }
-
-  const dbOrder = await db.select()
-    .from(orders)
-    .where(eq(orders.id, orderId))
-    .limit(1);
-
-  if (!dbOrder[0]) {
-    console.error(`Order not found: ${orderId}`);
-    return;
-  }
-
-  // 1. Update order status
-  await db.update(orders)
-    .set({
-      status: 'completed',
-      paymentId: order.id,
-      updatedAt: new Date(),
-    })
-    .where(eq(orders.id, orderId));
-
-  // 2. Create license (non-blocking)
-  try {
-    await createLicense(dbOrder[0]);
-  } catch (error) {
-    console.error('Failed to create license:', error);
-  }
-
-  // 3. Send confirmation email (non-blocking)
-  try {
-    await sendOrderConfirmation(dbOrder[0], order);
-  } catch (error) {
-    console.error('Failed to send confirmation:', error);
-  }
-
-  // 4. Create referral commission (non-blocking)
-  if (dbOrder[0].referredBy) {
-    try {
-      await createCommission(dbOrder[0]);
-    } catch (error) {
-      console.error('Failed to create commission:', error);
-    }
-  }
-
-  // 5. Grant GitHub access (non-blocking)
-  try {
-    const metadata = JSON.parse(dbOrder[0].metadata || '{}');
-    await inviteToGitHub(metadata.githubUsername, dbOrder[0].productType);
-  } catch (error) {
-    console.error('Failed to invite to GitHub:', error);
-  }
-
-  // 6. Send Discord notification (non-blocking)
-  try {
-    await sendSalesNotification(dbOrder[0]);
-  } catch (error) {
-    console.error('Failed to send Discord notification:', error);
-  }
-}
-```
-
-### Status Mapping
-```typescript
-function mapPolarStatusToAppStatus(polarStatus: string): string | null {
-  switch (polarStatus) {
-    case 'succeeded':
-      return 'completed';
-    case 'failed':
-    case 'expired':
-      return 'failed';
-    case 'open':
-    case 'confirmed':
-      return null; // Don't update - still pending
-    default:
-      return null;
-  }
-}
-```
-
-## Fee Calculation
-
-### Platform Fee Structure (Dec 2025)
-```typescript
-// lib/polar-fees.ts
-interface PolarFeeConfig {
-  basePercentage: number;     // 4%
-  baseFlatCents: number;      // $0.40 per transaction
-  internationalSurcharge: number;  // +1.5% for non-US cards
-  subscriptionSurcharge: number;   // +0.5% (not for one-time)
-}
-
-const POLAR_FEES: PolarFeeConfig = {
-  basePercentage: 0.04,
-  baseFlatCents: 40,
-  internationalSurcharge: 0.015,
-  subscriptionSurcharge: 0.005,
-};
-
-export function calculatePolarFees(
-  amountCents: number,
-  isInternational: boolean = true, // Conservative default
-  isSubscription: boolean = false
-): {
-  baseFee: number;
-  internationalFee: number;
-  subscriptionFee: number;
-  totalFee: number;
-  netRevenue: number;
-} {
-  // Handle zero/negative
-  if (amountCents <= 0) {
-    return { baseFee: 0, internationalFee: 0, subscriptionFee: 0, totalFee: 0, netRevenue: 0 };
-  }
-
-  const baseFee = Math.round(amountCents * POLAR_FEES.basePercentage + POLAR_FEES.baseFlatCents);
-  const internationalFee = isInternational
-    ? Math.round(amountCents * POLAR_FEES.internationalSurcharge)
-    : 0;
-  const subscriptionFee = isSubscription
-    ? Math.round(amountCents * POLAR_FEES.subscriptionSurcharge)
-    : 0;
-
-  const totalFee = baseFee + internationalFee + subscriptionFee;
-  const netRevenue = amountCents - totalFee;
-
-  return { baseFee, internationalFee, subscriptionFee, totalFee, netRevenue };
-}
-
-// Aggregate fees preserve per-transaction flat fees
-export function calculateAggregatePolarFees(transactionAmounts: number[]): {
-  totalFees: number;
-  totalNetRevenue: number;
-} {
-  let totalFees = 0;
-  let totalNetRevenue = 0;
-
-  for (const amount of transactionAmounts) {
-    const { totalFee, netRevenue } = calculatePolarFees(amount);
-    totalFees += totalFee;
-    totalNetRevenue += netRevenue;
-  }
-
-  return { totalFees, totalNetRevenue };
-}
-```
-
-## Discount Management
-
-### Discount Validation with Timeout
-```typescript
-// lib/polar-discounts.ts
-const VALIDATION_TIMEOUT_MS = 15000;
-
-export async function validateDiscount(
-  code: string,
-  productId: string
-): Promise<{ valid: boolean; discount?: PolarDiscount; reason?: string }> {
-  const sanitizedCode = code.trim().toUpperCase();
-  if (!sanitizedCode) {
-    return { valid: false, reason: 'Code cannot be empty' };
-  }
-
-  const polar = getPolar();
-  const env = getPolarEnv();
-
-  try {
-    // Race against timeout
-    const timeoutPromise = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error('Validation timeout')), VALIDATION_TIMEOUT_MS);
-    });
-
-    const searchPromise = polar.discounts.list({
-      organizationId: env.POLAR_ORGANIZATION_ID,
-      query: sanitizedCode,
-      limit: 100,
-    });
-
-    const result = await Promise.race([searchPromise, timeoutPromise]);
-
-    // Find exact match
-    const discount = result.items.find(d =>
-      d.code?.toUpperCase() === sanitizedCode
-    );
-
-    if (!discount) {
-      return { valid: false, reason: 'Code not found' };
-    }
-
-    // Check eligibility
-    const now = new Date();
-    if (discount.startsAt && now < new Date(discount.startsAt)) {
-      return { valid: false, reason: `Code starts on ${discount.startsAt}` };
-    }
-    if (discount.endsAt && now > new Date(discount.endsAt)) {
-      return { valid: false, reason: 'Code has expired' };
-    }
-    if (discount.maxRedemptions && discount.redemptionsCount >= discount.maxRedemptions) {
-      return { valid: false, reason: 'Code redemption limit reached' };
-    }
-    if (!discount.products?.some(p => p.id === productId)) {
-      return { valid: false, reason: 'Code not valid for this product' };
-    }
-
-    return { valid: true, discount };
-
-  } catch (error) {
-    console.error('Discount validation error:', error);
-    return { valid: false, reason: 'Validation failed - please try again' };
-  }
-}
-```
-
-### VND Conversion for Discounts
-```typescript
-const VND_TO_USD_RATE = 25000; // 1 USD = 25,000 VND
-
-export function convertDiscountToVND(discount: PolarDiscount, amountVND: number): number {
-  if (discount.type === 'percentage') {
-    // Basis points: 1000 = 10%, 10000 = 100%
-    const percentage = discount.basisPoints / 10000;
-    return Math.round(amountVND * percentage);
-  } else {
-    // Fixed amount in USD cents → VND
-    const amountUSD = discount.amount / 100;
-    return Math.round(amountUSD * VND_TO_USD_RATE);
-  }
-}
-```
-
-### Syncing SePay Redemptions to Polar
-```typescript
-// lib/polar-discount-sync.ts
-// When SePay payment completes, decrement Polar discount redemptions
-
-export async function syncPolarDiscountRedemption(
-  orderId: string,
-  discountId: string,
-  discountCode: string
-): Promise<{ success: boolean; action: string }> {
-  const order = await db.select().from(orders).where(eq(orders.id, orderId)).limit(1);
-  if (!order[0]) {
-    return { success: false, action: 'order_not_found' };
-  }
-
-  // Idempotency check
-  const metadata = order[0].metadata ? JSON.parse(order[0].metadata) : {};
-  if (metadata.polarDiscountSynced) {
-    return { success: true, action: 'already_synced' };
-  }
-
-  const polar = getPolar();
-
-  try {
-    const discount = await polar.discounts.get({ id: discountId });
-
-    if (discount.maxRedemptions === null || discount.maxRedemptions === undefined) {
-      return { success: true, action: 'skipped_unlimited' };
-    }
-
-    const currentMax = discount.maxRedemptions;
-
-    if (currentMax <= 1) {
-      await polar.discounts.delete({ id: discountId });
-      await markOrderSynced(orderId, 'deleted');
-    } else {
-      await polar.discounts.update({
-        id: discountId,
-        discountUpdate: { maxRedemptions: currentMax - 1 },
-      });
-      await markOrderSynced(orderId, 'decremented');
-    }
-
-    return { success: true, action: currentMax <= 1 ? 'deleted' : 'decremented' };
-
-  } catch (error: any) {
-    if (error.statusCode === 404) {
-      // Already deleted - treat as success
-      await markOrderSynced(orderId, 'already_deleted');
-      return { success: true, action: 'already_deleted' };
-    }
-    throw error;
-  }
-}
-
-async function markOrderSynced(orderId: string, action: string) {
-  const order = await db.select().from(orders).where(eq(orders.id, orderId)).limit(1);
-  const metadata = order[0].metadata ? JSON.parse(order[0].metadata) : {};
-
-  metadata.polarDiscountSynced = true;
-  metadata.polarDiscountSyncAction = action;
-  metadata.polarDiscountSyncedAt = new Date().toISOString();
-
-  await db.update(orders)
-    .set({ metadata: JSON.stringify(metadata) })
-    .where(eq(orders.id, orderId));
-}
-```
-
-## Revenue Tracking with Caching
-
-```typescript
-// lib/polar.ts
-const REVENUE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
-
-let revenueCache: {
-  data: { totalRevenueCents: number; orderCount: number } | null;
-  timestamp: number;
-} = { data: null, timestamp: 0 };
-
-export async function getPolarApiRevenue(): Promise<{
-  totalRevenueCents: number;
-  orderCount: number;
-  fromCache: boolean;
-}> {
-  const now = Date.now();
-
-  // Return cache if valid
-  if (revenueCache.data && now - revenueCache.timestamp < REVENUE_CACHE_TTL_MS) {
-    return { ...revenueCache.data, fromCache: true };
-  }
-
-  const polar = getPolar();
-  const env = getPolarEnv();
-
-  try {
-    let totalRevenueCents = 0;
-    let orderCount = 0;
-    let page = 1;
-    const maxPages = 100; // Safety limit
-
-    while (page <= maxPages) {
-      const response = await polar.orders.list({
-        organizationId: env.POLAR_ORGANIZATION_ID,
-        page,
-        limit: 100,
-      });
-
-      for (const order of response.items) {
-        if (order.status === 'succeeded') {
-          totalRevenueCents += order.netAmount; // After discounts, before tax
-          orderCount++;
-        }
-      }
-
-      if (!response.pagination.hasMore) break;
-      page++;
-    }
-
-    revenueCache = { data: { totalRevenueCents, orderCount }, timestamp: now };
-    return { totalRevenueCents, orderCount, fromCache: false };
-
-  } catch (error) {
-    // Return stale cache on error
-    if (revenueCache.data) {
-      console.warn('Using stale revenue cache due to API error');
-      return { ...revenueCache.data, fromCache: true };
-    }
-    throw error;
-  }
-}
-```
-
-## Error Handling Patterns
-
-### Fail-Open for Non-Critical Operations
-```typescript
-// Discount creation fails → proceed with full price
-try {
-  const discount = await createReferralDiscount(productId, amount, referralCode);
-  polarDiscountId = discount.id;
-} catch (error) {
-  console.error('⚠️ Discount creation failed - proceeding with full price:', error);
-  // Flag for manual refund investigation
-  await flagOrderForReview(orderId, 'discount_creation_failed');
-}
-```
-
-### Graceful Degradation in Webhooks
-```typescript
-// Non-critical operations don't block order completion
-const operations = [
-  { name: 'GitHub invite', fn: () => inviteToGitHub(username, productType) },
-  { name: 'Welcome email', fn: () => sendWelcomeEmail(order) },
-  { name: 'Discord notification', fn: () => sendSalesNotification(order) },
-  { name: 'Tier update', fn: () => updateReferrerTier(referrerId, revenueUsd) },
-];
-
-for (const op of operations) {
-  try {
-    await op.fn();
-  } catch (error) {
-    console.error(`❌ ${op.name} failed:`, error);
-    // Continue processing - don't block order
-  }
-}
-```
-
-### Rate Limit Handling with Exponential Backoff
-```typescript
-async function callWithRetry<T>(
-  fn: () => Promise<T>,
-  maxRetries: number = 3
-): Promise<T> {
-  let attempt = 0;
-
-  while (attempt < maxRetries) {
-    try {
-      return await fn();
-    } catch (error: any) {
-      if (error.statusCode === 429) {
-        const retryAfter = parseInt(error.headers?.['retry-after'] || '1', 10);
-        const delay = retryAfter * 1000 * Math.pow(2, attempt);
-        console.log(`Rate limited, retrying in ${delay}ms...`);
-        await sleep(delay);
-        attempt++;
-      } else {
-        throw error;
-      }
-    }
-  }
-
-  throw new Error('Max retries exceeded');
-}
-```
-
-## Database Schema
-
-### Orders Table
-```typescript
-// db/schema/orders.ts
-export const orders = pgTable('orders', {
-  id: uuid('id').primaryKey().defaultRandom(),
-  userId: uuid('user_id').references(() => users.id),
-  email: text('email').notNull(),
-  productType: text('product_type').notNull(),
-  amount: integer('amount').notNull(), // Final amount in cents
-  originalAmount: integer('original_amount'), // Before discounts
-  currency: text('currency').default('USD'),
-  status: text('status').default('pending'), // pending, completed, failed, refunded
-  paymentProvider: text('payment_provider').notNull(), // 'polar' or 'sepay'
-  paymentId: text('payment_id'), // External payment ID
-  referredBy: uuid('referred_by').references(() => users.id),
-  discountAmount: integer('discount_amount').default(0),
-  discountRate: numeric('discount_rate', { precision: 5, scale: 2 }),
-  metadata: text('metadata'), // JSON with audit trail
-  createdAt: timestamp('created_at').defaultNow(),
-  updatedAt: timestamp('updated_at').defaultNow(),
-});
-```
-
-### Webhook Events Table (Idempotency)
-```typescript
-export const webhookEvents = pgTable('webhook_events', {
-  id: uuid('id').primaryKey().defaultRandom(),
-  provider: text('provider').notNull(), // 'polar' or 'sepay'
-  eventType: text('event_type').notNull(),
-  eventId: text('event_id').notNull().unique(), // Idempotency key
-  payload: text('payload').notNull(),
-  processed: boolean('processed').default(false),
-  processedAt: timestamp('processed_at'),
-  error: text('error'),
-  createdAt: timestamp('created_at').defaultNow(),
-});
-```
-
-## Metadata Best Practices
-
-### Comprehensive Audit Trail
-```typescript
-// Store everything needed for debugging and reconciliation
-metadata: JSON.stringify({
-  // Pricing history
-  originalAmount: 9900,
-
-  // Coupon tracking
-  couponCode: 'LAUNCH20',
-  couponDiscountAmount: 1980,
-
-  // Referral tracking
-  referralCode: 'ABC12345',
-  referralDiscountAmount: 1584,
-  referrerId: 'user-uuid',
-
-  // Customer context
-  githubUsername: 'customer',
-
-  // Polar integration
-  polarDiscountId: 'disc_xxx',
-  polarDiscountSynced: true,
-  polarDiscountSyncAction: 'decremented',
-  polarDiscountSyncedAt: '2025-01-15T10:30:00Z',
-
-  // Team context (if applicable)
-  isTeamPurchase: false,
-  teamId: null,
-  quantity: 1,
-})
-```
-
-## Testing
-
-### Unit Tests for Fee Calculation
-```typescript
-// __tests__/lib/polar-fees.test.ts
-describe('calculatePolarFees', () => {
-  it('handles zero amount', () => {
-    const result = calculatePolarFees(0);
-    expect(result.totalFee).toBe(0);
-    expect(result.netRevenue).toBe(0);
-  });
-
-  it('calculates international one-time correctly', () => {
-    // $100 transaction
-    const result = calculatePolarFees(10000, true, false);
-    expect(result.baseFee).toBe(440);        // 4% + $0.40
-    expect(result.internationalFee).toBe(150); // 1.5%
-    expect(result.totalFee).toBe(590);
-    expect(result.netRevenue).toBe(9410);    // $94.10
-  });
-
-  it('preserves per-transaction flat fees in aggregate', () => {
-    // Two $100 transactions should each have $0.40 flat fee
-    const aggregate = calculateAggregatePolarFees([10000, 10000]);
-    const single = calculatePolarFees(20000);
-
-    expect(aggregate.totalFees).toBeGreaterThan(single.totalFee);
-    // Difference should be one extra flat fee ($0.40)
-    expect(aggregate.totalFees - single.totalFee).toBe(40);
-  });
-});
-```
-
-## Production Checklist
-
-- [ ] Environment variables configured in all environments
-- [ ] Sandbox testing completed for all checkout flows
-- [ ] Production API key obtained and secured
-- [ ] Webhook endpoint deployed and reachable
-- [ ] Webhook signature verification implemented
-- [ ] Idempotency handling tested with duplicate webhooks
-- [ ] Fee calculations verified against Polar dashboard
-- [ ] Discount validation timeout configured
-- [ ] Error monitoring enabled (Sentry, etc.)
-- [ ] Structured logging in place
-- [ ] Database indexes on orders.status, orders.paymentProvider
-- [ ] Revenue caching configured
-- [ ] Rate limit handling implemented
-- [ ] Fail-open patterns for non-critical operations
-- [ ] Customer email notifications working
-- [ ] Refund flow tested end-to-end
-- [ ] GitHub access grant/revoke tested
-- [ ] Discord sales notifications configured
-
-## Common Pitfalls
-
-1. **Applying discounts in wrong order** - Always coupon first, then referral
-2. **Trusting success redirect without verification** - Always verify via API or webhook
-3. **Not handling duplicate webhooks** - Use eventId for idempotency
-4. **Blocking webhook on non-critical failures** - Wrap in try-catch, log, continue
-5. **Hardcoding Polar customer IDs** - Use external_id (your user ID) for lookups
-6. **Not setting timeout on discount validation** - API can be slow
-7. **Calculating aggregate fees as single transaction** - Each transaction has flat fee
-8. **Exposing API keys client-side** - Always server-side
-9. **Not preserving original amount in metadata** - Need for audit/debugging
-10. **Syncing discount redemptions synchronously** - Can fail; use retry with backoff