.env.example

# ============================================
# JudgeFinder Platform - Environment Variables
# ============================================
# Copy this to .env.local for local development
# All production values are configured in Netlify
# ============================================
#
# VARIABLE STATUS LEGEND:
# [REQUIRED] - Must be set for application to run
# [OPTIONAL] - Can be omitted, feature will be disabled
# [RECOMMENDED] - Should be set for production
# ============================================

# ------------------------------
# Database Configuration (Supabase)
# ------------------------------
# Get these from: https://app.supabase.com/project/_/settings/api
# [REQUIRED] Supabase project URL - used for all database connections
NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co

# [REQUIRED] Supabase anonymous key - used for client-side queries with RLS
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_ANON_KEY_HERE

# [REQUIRED] Supabase service role key - DANGER: bypasses RLS, server-side only
# NEVER expose this in client-side code or commit to version control
# NOTE: Use sparingly - prefer service account client for most backend operations
SUPABASE_SERVICE_ROLE_KEY=YOUR_SERVICE_ROLE_KEY_HERE

# ------------------------------
# V3 Database Configuration (JudgeFinder V3)
# ------------------------------
# V3 database contains: judges, practice_area_config, subspecialty_config,
# judge_practice_areas, judge_subspecialties, courts, judge_court_assignments, cases
# Project ID: rzaucwpoqjkmitbsvlnc
# [OPTIONAL] V3 Supabase project URL - defaults to rzaucwpoqjkmitbsvlnc if not set
NEXT_PUBLIC_SUPABASE_V3_URL=https://rzaucwpoqjkmitbsvlnc.supabase.co

# [OPTIONAL] V3 Supabase anonymous key - used for V3 API routes
NEXT_PUBLIC_SUPABASE_V3_ANON_KEY=YOUR_V3_ANON_KEY_HERE

# [OPTIONAL] V3 Supabase service role key - for admin operations on V3 database
SUPABASE_V3_SERVICE_ROLE_KEY=YOUR_V3_SERVICE_ROLE_KEY_HERE
# Optional: direct Postgres connection string (required for automated migrations)
SUPABASE_DB_URL=postgresql://postgres:YOUR_PASSWORD@YOUR_PROJECT_ID.supabase.co:5432/postgres

# [REQUIRED] Supabase JWT secret - used to sign service account tokens
# Get from: https://app.supabase.com/project/_/settings/api (scroll to JWT Secret)
# Used by lib/supabase/service-account.ts for authenticated backend operations
SUPABASE_JWT_SECRET=your-super-secret-jwt-token-with-at-least-32-characters-long

# ------------------------------
# Authentication (Clerk)
# ------------------------------
# Get these from: https://dashboard.clerk.com
# [REQUIRED] Clerk publishable key - safe for client-side use
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_CLERK_PUBLISHABLE_KEY_HERE

# [REQUIRED] Clerk secret key - server-side only, never expose publicly
CLERK_SECRET_KEY=YOUR_CLERK_SECRET_KEY_HERE

# [OPTIONAL] Clerk URL configuration - defaults shown below
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/dashboard
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/welcome

# ------------------------------
# Bot Protection (Cloudflare Turnstile)
# ------------------------------
# Get these from: https://dash.cloudflare.com/ > Turnstile
# Turnstile is a free, privacy-friendly CAPTCHA alternative by Cloudflare
# [REQUIRED for production] Turnstile site key - safe for client-side use
# Format: Starts with '0x' for real keys, '1x' for test keys
NEXT_PUBLIC_TURNSTILE_SITE_KEY=YOUR_TURNSTILE_SITE_KEY_HERE

# [REQUIRED for production] Turnstile secret key - server-side only
# Used to verify CAPTCHA tokens and prevent bot abuse on AI chatbox and sign-up
TURNSTILE_SECRET_KEY=YOUR_TURNSTILE_SECRET_KEY_HERE

# ------------------------------
# AI Services
# ------------------------------
# [OPTIONAL] OpenAI API key - used as fallback for AI analytics
# Get from: https://platform.openai.com/api-keys
# Format must start with 'sk-'
OPENAI_API_KEY=YOUR_OPENAI_API_KEY_HERE

# [RECOMMENDED] Google AI (Gemini) API key - primary AI provider for analytics
# Get from: https://makersuite.google.com/app/apikey
# More cost-effective than OpenAI for most operations
GOOGLE_AI_API_KEY=YOUR_GOOGLE_AI_API_KEY_HERE

# ------------------------------
# External APIs
# ------------------------------
# [REQUIRED] CourtListener API key - fetches judicial data and case information
# Get from: https://www.courtlistener.com/help/api/
# Rate limits: 5000 requests/hour with valid key
COURTLISTENER_API_KEY=YOUR_COURTLISTENER_API_KEY_HERE

# [OPTIONAL] CourtListener webhook secret - validates webhook events
# Get from: CourtListener webhook configuration dashboard
# Used to verify webhook signatures for security (HMAC-SHA256)
# Generate with: openssl rand -hex 32
COURTLISTENER_WEBHOOK_SECRET=YOUR_COURTLISTENER_WEBHOOK_SECRET_HERE

# [OPTIONAL] CourtListener webhook verification token - for webhook setup
# Used during initial webhook verification handshake
COURTLISTENER_WEBHOOK_VERIFY_TOKEN=YOUR_VERIFY_TOKEN_HERE

# CourtListener API Configuration (fine-tuning)
# [OPTIONAL] Base delay between API requests in milliseconds (default: 1000)
COURTLISTENER_REQUEST_DELAY_MS=1000

# [OPTIONAL] Maximum retry attempts for failed requests (default: 5)
COURTLISTENER_MAX_RETRIES=5

# [OPTIONAL] Request timeout in milliseconds (default: 30000)
COURTLISTENER_REQUEST_TIMEOUT_MS=30000

# [OPTIONAL] Maximum backoff delay when retrying (default: 15000)
COURTLISTENER_BACKOFF_CAP_MS=15000

# [OPTIONAL] Maximum jitter to add to retry delays in milliseconds (default: 500)
COURTLISTENER_RETRY_JITTER_MAX_MS=500

# [OPTIONAL] Circuit breaker error threshold (default: 5)
COURTLISTENER_CIRCUIT_THRESHOLD=5

# [OPTIONAL] Circuit breaker cooldown period in milliseconds (default: 60000)
COURTLISTENER_CIRCUIT_COOLDOWN_MS=60000

# [OPTIONAL] UniCourt API - fetches structured case dockets, parties, and counsel data
# Get from: https://unicourt.com/api (requires paid plan with API access)
# UniCourt provides normalized case data with parties, dockets, and event timelines
UNICOURT_CLIENT_ID=YOUR_UNICOURT_CLIENT_ID_HERE
UNICOURT_CLIENT_SECRET=YOUR_UNICOURT_CLIENT_SECRET_HERE

# [OPTIONAL] UniCourt bearer token - some plans provide static tokens
# If your plan uses OAuth, leave blank and client will use client_id/secret flow
UNICOURT_BEARER_TOKEN=YOUR_UNICOURT_BEARER_TOKEN_HERE

# [OPTIONAL] UniCourt API base URL (default: https://api.unicourt.com)
UNICOURT_BASE_URL=https://api.unicourt.com

# UniCourt API Configuration (fine-tuning)
# [OPTIONAL] Base delay between API requests in milliseconds (default: 170)
# Trial rate limit: 30 requests per 5 seconds = 167ms minimum delay
# 170ms provides small buffer for safety
UNICOURT_REQUEST_DELAY_MS=170

# [OPTIONAL] Maximum retry attempts for failed requests (default: 3)
UNICOURT_MAX_RETRIES=3

# [OPTIONAL] Request timeout in milliseconds (default: 30000)
UNICOURT_REQUEST_TIMEOUT_MS=30000

# [OPTIONAL] Maximum backoff delay when retrying (default: 15000)
UNICOURT_BACKOFF_CAP_MS=15000

# [OPTIONAL] Circuit breaker error threshold (default: 5)
UNICOURT_CIRCUIT_THRESHOLD=5

# [OPTIONAL] Circuit breaker cooldown period in milliseconds (default: 60000)
UNICOURT_CIRCUIT_COOLDOWN_MS=60000

# [OPTIONAL] UniCourt webhook secret - validates Case Track webhook events
# Get from: UniCourt API portal when configuring webhook subscriptions
# Used to verify webhook signatures for security (HMAC-SHA256)
# Generate with: openssl rand -hex 32
UNICOURT_WEBHOOK_SECRET=YOUR_UNICOURT_WEBHOOK_SECRET_HERE

# UniCourt Cron Job Toggles
# [OPTIONAL] Enable UniCourt weekly comprehensive sync (default: false)
# WARNING: This job makes ~3,000+ API calls per run - only enable with sufficient quota
# Schedule: Sundays at 4:00 AM UTC
UNICOURT_WEEKLY_SYNC_ENABLED=false

# [OPTIONAL] Enable UniCourt daily ingestion sync (default: false)
# This job makes ~200 API calls per run
# Schedule: Daily at 2:00 AM UTC
UNICOURT_DAILY_SYNC_ENABLED=false

# [OPTIONAL] Enable UniCourt analytics weekly sync (default: false)
# This job syncs judge/attorney/law firm analytics
# Schedule: Sundays at 3:00 AM UTC
UNICOURT_ANALYTICS_ENABLED=false

# UniCourt Quota Configuration
# [OPTIONAL] Daily API request quota limit (default: 500)
# Check your UniCourt plan for actual limits
UNICOURT_DAILY_QUOTA=500

# [OPTIONAL] Warning threshold percentage (default: 80)
# Logs warning when this percentage of daily quota is reached
UNICOURT_QUOTA_WARNING_THRESHOLD=80

# [OPTIONAL] Circuit breaker threshold percentage (default: 90)
# Blocks new requests to preserve remaining quota for critical operations
UNICOURT_QUOTA_CIRCUIT_THRESHOLD=90

# UniCourt Trial Mode Configuration
# Reference: Email from Christina Carducci (UniCourt) - December 16, 2024
# Trial terms: 1000 API calls TOTAL for 30-day period, 30 requests per 5 seconds

# [OPTIONAL] Enable trial budget mode (default: false)
# When enabled, tracks cumulative API calls against total trial budget
# instead of daily reset quota
UNICOURT_TRIAL_MODE=false

# [OPTIONAL] Total trial budget in API calls (default: 1000)
# This is the TOTAL calls allowed for the entire trial period
UNICOURT_TRIAL_BUDGET=1000

# [OPTIONAL] Trial start date in ISO format (default: current date)
# Used to calculate trial period expiration
# Format: YYYY-MM-DD
UNICOURT_TRIAL_START_DATE=

# [OPTIONAL] Trial period duration in days (default: 30)
UNICOURT_TRIAL_PERIOD_DAYS=30

# [OPTIONAL] Trial warning threshold percentage (default: 50)
# Triggers warning when this percentage of trial budget is consumed
UNICOURT_TRIAL_WARNING_THRESHOLD=50

# [OPTIONAL] Trial block threshold percentage (default: 90)
# Blocks new requests when this percentage of trial budget is consumed
UNICOURT_TRIAL_BLOCK_THRESHOLD=90

# ------------------------------
# Cache & Rate Limiting (Upstash Redis)
# ------------------------------
# Get from: https://console.upstash.com/
# [REQUIRED] Upstash Redis REST URL - used for rate limiting and caching
UPSTASH_REDIS_REST_URL=https://YOUR_UPSTASH_INSTANCE.upstash.io

# [REQUIRED] Upstash Redis REST token - authentication for Redis operations
UPSTASH_REDIS_REST_TOKEN=AYourUpstashTokenHere

# ------------------------------
# Payment Processing (Stripe)
# ------------------------------
# Get from: https://dashboard.stripe.com/apikeys
# [REQUIRED] Stripe secret key for server-side payment processing
# Use test key (sk_test_) for development, live key (sk_live_) for production
STRIPE_SECRET_KEY=YOUR_STRIPE_SECRET_KEY_HERE

# [REQUIRED] Stripe publishable key for client-side checkout
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=YOUR_STRIPE_PUBLISHABLE_KEY_HERE

# [REQUIRED] Stripe webhook signing secret - validates webhook events
# Get from: https://dashboard.stripe.com/webhooks
# Used to verify webhook signatures for security (HMAC-SHA256)
# Format: whsec_... (starts with 'whsec_')
STRIPE_WEBHOOK_SECRET=YOUR_STRIPE_WEBHOOK_SECRET_HERE

# ------------------------------
# Pricing Tiers (Final Structure - 2025-11-13)
# ------------------------------
# JudgeFinder uses a 6-tier pricing model split across B2C (user subscriptions) and B2B (advertising)
#
# B2C: User Subscriptions (Individual Platform Users)
# - Free: $0/month (no payment required)
# - Professional: $29/month or $290/year
# - Enterprise/Ultrathink: $299/month or $2,990/year
# All annual plans include 2 months free (10x monthly pricing)
#
# B2B: Advertising Tiers (State/Federal Courts and Court Organizations)
# - State Judges: $500/month or $5,000/year
# - Federal Judges: $500/month or $5,000/year
# - Court Advertising: $5,000/month or $50,000/year

# ==============================
# B2C User Subscription Tiers
# ==============================
# Get from: https://dashboard.stripe.com/products
# These are for individual user subscriptions (separate from court/judge advertising)

# [REQUIRED] Professional Tier - $29/month or $290/year
# Features: Unlimited courts, exports, advanced filters, judge comparison
STRIPE_PRICE_PROFESSIONAL_MONTHLY=STRIPE_PRICE_PROFESSIONAL_MONTHLY_PLACEHOLDER
STRIPE_PRICE_PROFESSIONAL_ANNUAL=STRIPE_PRICE_PROFESSIONAL_ANNUAL_PLACEHOLDER

# [REQUIRED] Enterprise Tier (Ultrathink) - $299/month or $2,990/year
# Features: Everything in Professional + Full API access + Organization billing + Priority support
STRIPE_PRICE_ENTERPRISE_MONTHLY=STRIPE_PRICE_ENTERPRISE_MONTHLY_PLACEHOLDER
STRIPE_PRICE_ENTERPRISE_ANNUAL=STRIPE_PRICE_ENTERPRISE_ANNUAL_PLACEHOLDER

# ==============================
# B2B Advertising Tiers
# ==============================
# Get from: https://dashboard.stripe.com/products
# These are for judges and courts advertising on the platform

# [REQUIRED] State Judges Advertising - $500/month or $5,000/year
# Target: State court judges | Visibility: Standard | Support: Email
STRIPE_PRICE_STATE_JUDGE_MONTHLY=STRIPE_PRICE_STATE_JUDGE_MONTHLY_PLACEHOLDER
STRIPE_PRICE_STATE_JUDGE_ANNUAL=STRIPE_PRICE_STATE_JUDGE_ANNUAL_PLACEHOLDER

# [REQUIRED] Federal Judges Advertising - $500/month or $5,000/year
# Target: Federal court judges | Visibility: Premium | Support: Email
STRIPE_PRICE_FEDERAL_JUDGE_MONTHLY=STRIPE_PRICE_FEDERAL_JUDGE_MONTHLY_PLACEHOLDER
STRIPE_PRICE_FEDERAL_JUDGE_ANNUAL=STRIPE_PRICE_FEDERAL_JUDGE_ANNUAL_PLACEHOLDER

# [REQUIRED] Court Advertising (Ultrathink) - $5,000/month or $50,000/year
# Target: Court organizations (state/federal) | Visibility: Premium | Support: Priority
# Use this tier for courts and court organizations seeking ultra-prominent positioning
STRIPE_PRICE_COURT_ADVERTISING_MONTHLY=STRIPE_PRICE_COURT_ADVERTISING_MONTHLY_PLACEHOLDER
STRIPE_PRICE_COURT_ADVERTISING_ANNUAL=STRIPE_PRICE_COURT_ADVERTISING_ANNUAL_PLACEHOLDER

# ------------------------------
# Payment Processing (Coinbase Commerce)
# ------------------------------
# Get from: https://commerce.coinbase.com/dashboard/settings
# [OPTIONAL] Coinbase Commerce API key for cryptocurrency payments
# Supports: Bitcoin, Ethereum, Solana, Bitcoin Cash, Litecoin, USDC
# Use test key for development, live key for production
COINBASE_COMMERCE_API_KEY=YOUR_COINBASE_COMMERCE_API_KEY_HERE

# [OPTIONAL] Coinbase Commerce webhook secret - validates webhook events
# Get from: https://commerce.coinbase.com/dashboard/settings (webhook subscriptions)
# Used to verify webhook signatures for security (HMAC-SHA256)
# Format: Long alphanumeric string
COINBASE_COMMERCE_WEBHOOK_SECRET=YOUR_COINBASE_COMMERCE_WEBHOOK_SECRET_HERE

# [OPTIONAL] Enable cryptocurrency payments (feature flag)
# When enabled, users can pay with crypto alongside credit cards
# Webhook URL: https://judgefinder.io/api/webhooks/commerce
ENABLE_CRYPTO_PAYMENTS=false

# [OPTIONAL] Minimum blockchain confirmations required (default: 3)
# Lower = faster activation, Higher = more secure
COMMERCE_MIN_CONFIRMATIONS=3

# [OPTIONAL] Charge expiration time in seconds (default: 3600 = 1 hour)
# Time customers have to complete crypto payment
COMMERCE_CHARGE_EXPIRATION=3600

# ------------------------------
# Email Service (SendGrid)
# ------------------------------
# Get from: https://app.sendgrid.com/settings/api_keys
# [RECOMMENDED] SendGrid API key for transactional emails
# Used for: newsletter welcome emails, payment receipts, payment failures, dunning emails, subscription cancellations
# If omitted, emails are skipped but recorded in email_send_log for auditing
SENDGRID_API_KEY=YOUR_SENDGRID_API_KEY_HERE

# [RECOMMENDED] SendGrid from email address (must be verified in SendGrid)
# Should match your domain for better deliverability
# Used for all transactional emails (newsletter, billing, etc.)
SENDGRID_FROM_EMAIL=noreply@judgefinder.io

# [OPTIONAL] Alternative: Billing from email (legacy fallback)
# Used if SENDGRID_FROM_EMAIL is not set
BILLING_FROM_EMAIL=noreply@judgefinder.io

# ------------------------------
# Monitoring & Error Tracking (Sentry)
# ------------------------------
# Get from: https://sentry.io/settings/projects/
# [RECOMMENDED] Sentry DSN for server-side error tracking
SENTRY_DSN=https://YOUR_KEY@YOUR_ORG.ingest.sentry.io/YOUR_PROJECT_ID

# [RECOMMENDED] Sentry DSN for client-side error tracking
NEXT_PUBLIC_SENTRY_DSN=https://YOUR_KEY@YOUR_ORG.ingest.sentry.io/YOUR_PROJECT_ID

# [OPTIONAL] Sentry environment identifier
SENTRY_ENVIRONMENT=production

# [OPTIONAL] Sentry release version for tracking
SENTRY_RELEASE=1.0.0

# [OPTIONAL] Sentry auth token for source map uploads during build
SENTRY_AUTH_TOKEN=YOUR_SENTRY_AUTH_TOKEN_HERE

# [OPTIONAL] Sentry performance monitoring sample rates (0.0 to 1.0)
# Controls what percentage of transactions are sent to Sentry
SENTRY_TRACES_SAMPLE_RATE=0.1
SENTRY_PROFILES_SAMPLE_RATE=0.1

# ------------------------------
# Analytics & Tracking
# ------------------------------
# [OPTIONAL] Google Analytics 4 measurement ID
# Get from: https://analytics.google.com/analytics/web/#/a{accountId}w{propertyId}p{viewId}/admin/streams/table/
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

# [OPTIONAL] PostHog project API key for product analytics
# Get from: https://app.posthog.com/project/settings
NEXT_PUBLIC_POSTHOG_KEY=phc_YOUR_POSTHOG_PROJECT_KEY_HERE
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

# ------------------------------
# Site Configuration
# ------------------------------
# [REQUIRED] Public site URL - must match your production domain
# Used for: SEO, sitemaps, canonical URLs, Open Graph tags
# Replace with actual deployment URL (example: https://app.example.com)
NEXT_PUBLIC_SITE_URL=https://your-site-url.com

# [REQUIRED] Application URL - typically same as NEXT_PUBLIC_SITE_URL
NEXT_PUBLIC_APP_URL=https://your-site-url.com

# [OPTIONAL] Application name displayed in UI
NEXT_PUBLIC_APP_NAME=Your App Name

# [OPTIONAL] Public brand references used in marketing/docs (sanitized for scanners)
NEXT_PUBLIC_APP_NAME_SHORT=Your App
NEXT_PUBLIC_SITE_DOMAIN=your-site-url.com

# [OPTIONAL] Custom auth routes (defaults used if not set)
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

# [REQUIRED] Node environment - determines build optimizations
# Values: development | production | test
NODE_ENV=production

# ------------------------------
# Admin Configuration
# ------------------------------
# [REQUIRED] Comma-separated list of Clerk user IDs with admin access
# Get user IDs from: https://dashboard.clerk.com/apps/{app_id}/users
# Example: user_2abc123def,user_2xyz456ghi
ADMIN_USER_IDS=user_YOUR_CLERK_USER_ID_HERE

# ------------------------------
# Internal Security & API Protection
# ------------------------------
# [REQUIRED] API key for internal sync operations
# Generate with: openssl rand -base64 32
# Used to authenticate cron jobs and internal API calls
SYNC_API_KEY=YOUR_RANDOM_32_CHAR_SYNC_API_KEY_HERE

# [REQUIRED] Secret for authenticating scheduled/cron functions
# Generate with: openssl rand -base64 32
# Prevents unauthorized execution of scheduled tasks
CRON_SECRET=YOUR_RANDOM_32_CHAR_CRON_SECRET_HERE

# [REQUIRED] Admin API key for bulk import and admin operations
# Generate with: openssl rand -base64 32
# Used to authenticate admin API endpoints like bulk data imports
ADMIN_API_KEY=YOUR_RANDOM_32_CHAR_ADMIN_API_KEY_HERE

# [REQUIRED in production] Encryption key for sensitive data and service account operations
# Generate with: openssl rand -base64 32
# Used for encrypting sensitive data and signing service account tokens
# CRITICAL: Keep this secret secure - changing it will invalidate encrypted data
ENCRYPTION_KEY=YOUR_RANDOM_32_CHAR_ENCRYPTION_KEY_HERE

# ------------------------------
# SEO & Search Engine Verification
# ------------------------------
# [OPTIONAL] Google Search Console verification code
# Get from: https://search.google.com/search-console
# Instructions: Add property -> HTML tag method
NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION=your-google-verification-code-here

# [OPTIONAL] Bing Webmaster Tools verification code
# Get from: https://www.bing.com/webmasters
# Instructions: Add site -> HTML meta tag method
NEXT_PUBLIC_BING_SITE_VERIFICATION=your-bing-verification-code-here

# ------------------------------
# Feature Flags & Experimental
# ------------------------------
# [OPTIONAL] Enable beta features for testing
ENABLE_BETA_FEATURES=false

# [OPTIONAL] Enable detailed debug logging (verbose)
DEBUG_MODE=false

# [OPTIONAL] Enable maintenance mode (shows maintenance page)
MAINTENANCE_MODE=false

# Claude AI (preferred over OpenAI for chat)
ANTHROPIC_API_KEY=

STRIPE_PRICE_JUDGE_AD_ANNUAL=STRIPE_PRICE_JUDGE_AD_ANNUAL_PLACEHOLDER
STRIPE_PRICE_COURT_AD_MONTHLY=STRIPE_PRICE_COURT_AD_MONTHLY_PLACEHOLDER
STRIPE_PRICE_COURT_AD_ANNUAL=STRIPE_PRICE_COURT_AD_ANNUAL_PLACEHOLDER