SUBSCRIPTION (fixed monthly):
  → Plan limits included (X discoveries/mo, Y contact reveals/mo)
  → Managed via payment provider subscription (Lemon Squeezy)

CREDIT PACK (pay-as-you-go):
  → For users who exceed plan limits
  → Payment provider one-time transaction
  → Added to org wallet
  → Decreases as used

Beta (until launch):
  → All invited users are on the FREE plan
  → Free limits: 5 discoveries/mo, 0 reveals (contacts fully gated), 10 leads
  → Cost display is ACTIVE (users see their consumption)
  → Payment provider is INACTIVE (no payments)
  → "Beta" badge visible in UI
  → Feedback collection active
  → Bonus credits can be given to beta users (for reveal testing)

Launch:
  → Activate payment provider (Lemon Squeezy)
  → Enable Pro plan purchase ($49/mo)
  → Enable credit pack purchase

Provider Entities (Lemon Squeezy example):
  → Customer = export_ai_organizations (1:1)
  → Subscription = org's active plan
  → Order = credit pack purchase (one-time)
  → Webhook = subscription status, payment success/failure

Flow:
  Owner clicks "Upgrade to Pro"
  → Provider Checkout is created (Lemon Squeezy Checkout)
  → User pays via provider
  → Webhook → update subscription record
  → Plan limits activate instantly

-- Plan definitions (managed by admin)
CREATE TABLE export_ai_plan_limits (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  plan TEXT NOT NULL UNIQUE,  -- 'free' | 'pro' | 'team' | 'enterprise'
  limits JSONB NOT NULL,
  -- {
  --   "discoveries_per_month": 3,
  --   "companies_per_search": 10,
  --   "contact_reveals_per_month": 1,
  --   "saved_leads": 20,
  --   "max_members": 1,
  --   "max_orgs": 1,
  --   "batch_operations": false,
  --   "api_access": false,
  --   "auto_headhunt": false,
  --   "ai_analysis": false,
  --   "shared_workspace": false,
  --   "multi_org": false
  -- }
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- Org credit wallet
CREATE TABLE export_ai_credit_wallets (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL UNIQUE REFERENCES export_ai_organizations(id),
  balance INT NOT NULL DEFAULT 0,     -- current credits
  lifetime_earned INT DEFAULT 0,       -- total earned
  lifetime_spent INT DEFAULT 0,        -- total spent
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- Credit transactions
CREATE TABLE export_ai_credit_transactions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES export_ai_organizations(id),
  amount INT NOT NULL,                 -- positive: addition, negative: consumption
  balance_after INT NOT NULL,          -- balance after transaction
  transaction_type TEXT NOT NULL,      -- 'purchase' | 'consume' | 'refund' | 'bonus'
  description TEXT,                    -- "Discovery search: Germany + chemicals"
  reference_type TEXT,                 -- 'discovery' | 'headhunt' | 'enrichment' | 'credit_pack'
  reference_id UUID,                   -- ID of the related record
  created_by UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Monthly usage counters (billing period based)
CREATE TABLE export_ai_usage_monthly (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES export_ai_organizations(id),
  period_start DATE NOT NULL,          -- billing period start (subscription.current_period_start)
  period_end DATE NOT NULL,            -- billing period end (subscription.current_period_end)
  discoveries INT DEFAULT 0,
  contact_reveals INT DEFAULT 0,
  enrichments INT DEFAULT 0,
  batch_operations INT DEFAULT 0,
  created_at TIMESTAMPTZ DEFAULT now(),
  UNIQUE(organization_id, period_start)
);

-- Payment provider subscription record (provider-agnostic)
CREATE TABLE export_ai_subscriptions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL UNIQUE REFERENCES export_ai_organizations(id),
  provider TEXT NOT NULL DEFAULT 'lemonsqueezy',  -- 'lemonsqueezy' | 'paddle' | 'stripe'
  provider_subscription_id TEXT,
  provider_customer_id TEXT,
  plan TEXT NOT NULL DEFAULT 'free',
  status TEXT NOT NULL DEFAULT 'active',  -- 'active' | 'past_due' | 'canceled' | 'trialing'
  current_period_start TIMESTAMPTZ,
  current_period_end TIMESTAMPTZ,
  cancel_at_period_end BOOLEAN DEFAULT false,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- Webhook idempotency table (duplicate event prevention)
CREATE TABLE export_ai_webhook_events (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  provider TEXT NOT NULL,                  -- 'lemonsqueezy' | 'paddle' | 'stripe'
  provider_event_id TEXT NOT NULL UNIQUE,  -- event ID given by the provider
  event_type TEXT NOT NULL,                -- 'subscription_created' | 'order_created' etc.
  payload JSONB,                           -- raw event data (for debugging)
  processed_at TIMESTAMPTZ DEFAULT now(),
  created_at TIMESTAMPTZ DEFAULT now()
);

-- RLS on all tables
ALTER TABLE export_ai_plan_limits ENABLE ROW LEVEL SECURITY;
ALTER TABLE export_ai_credit_wallets ENABLE ROW LEVEL SECURITY;
ALTER TABLE export_ai_credit_transactions ENABLE ROW LEVEL SECURITY;
ALTER TABLE export_ai_usage_monthly ENABLE ROW LEVEL SECURITY;
ALTER TABLE export_ai_subscriptions ENABLE ROW LEVEL SECURITY;
ALTER TABLE export_ai_webhook_events ENABLE ROW LEVEL SECURITY;

-- Indexes
CREATE INDEX idx_credit_tx_org ON export_ai_credit_transactions(organization_id, created_at DESC);
CREATE INDEX idx_usage_monthly_org ON export_ai_usage_monthly(organization_id, period_start DESC);
CREATE UNIQUE INDEX idx_webhook_events_provider_id ON export_ai_webhook_events(provider_event_id);

User clicks "Discovery"
  → Frontend: GET /api/usage/check?action=discovery
    → Backend:
      1. Get org's plan + billing period (subscriptions table → current_period_start/end)
      2. Get plan limits (plan_limits table)
      3. Get active billing period usage (usage_monthly WHERE period_start = current_period_start)
      4. Check subscription status (past_due/canceled → block)
      5. Compare:
         - Within limit? → { allowed: true, remaining: 47, planLimit: 50 }
         - Limit exceeded but has credits? → { allowed: true, creditCost: 1, creditBalance: 23 }
         - No credits either? → { allowed: false, reason: "limit_exceeded", upgradeUrl: "/pricing" }
  → Frontend: Show confirmation dialog (05-usage-confirmation)
  → User confirms → operation starts
  → On completion: usage_monthly++ and/or credit_transactions insert

Provider Event → POST /api/webhooks/payment
  → Generic event type:
    - subscription.activated    → create/update subscription
    - subscription.updated      → reflect plan/period change
    - subscription.canceled     → status: canceled
    - subscription.past_due     → status: past_due
    - transaction.completed     → add credits to wallet for credit pack
    - transaction.payment_failed → log failed payment

Credit consumption flow:
  1. Acquire advisory lock → pg_advisory_xact_lock(org_id_hash)
  2. Read current balance (SELECT ... FOR UPDATE)
  3. Is balance >= consumption? → If no, abort
  4. credit_transactions INSERT (amount: -N, balance_after: new balance)
  5. credit_wallets UPDATE (balance -= N)
  6. Lock auto-releases (transaction commit)

→ Double-spend is PREVENTED: if 2 operations arrive simultaneously, one waits.

lib/billing/
  providers/
    lemonsqueezy.ts → ILemonSqueezyProvider implements IPaymentProvider
    paddle.ts       → IPaddleProvider implements IPaymentProvider (alternative)
    stripe.ts       → IStripeProvider implements IPaymentProvider (future)
  payment-provider.ts → IPaymentProvider interface + factory
  webhook-handler.ts  → Generic handler, dispatches by provider