products:
    sparki_team_tier:
        # Polar Product
        id: 'prod_sparki_team'
        name: 'Sparki Team Tier - Forgery Unlocked'
        description: 'Collaborative testing, guilds, leaderboards + full Sparki features'

        # Pricing
        pricing:
            - type: 'recurring'
              interval: 'monthly'
              interval_count: 1
              price_amount: 2500 # $25.00 USD
              currency: 'usd'

            - type: 'recurring'
              interval: 'yearly'
              interval_count: 1
              price_amount: 25000 # $250.00 USD (2-month discount)
              currency: 'usd'

        # Product Metadata
        metadata:
            sparki_tier: 'team'
            forgery_features:
                - 'guild_system'
                - 'team_leaderboards'
                - 'collaborative_quests'
                - 'persistence_7_days'
                - 'advanced_monitoring'
            max_users: 5
            max_collaborators: 10

    sparki_pro_tier:
        id: 'prod_sparki_pro'
        name: 'Sparki Pro Tier - Advanced Forgery'
        pricing:
            - type: 'recurring'
              interval: 'monthly'
              price_amount: 9900 # $99.00 USD

            - type: 'recurring'
              interval: 'yearly'
              price_amount: 99000 # $990.00 USD (1-month discount)

        metadata:
            sparki_tier: 'pro'
            forgery_features:
                - 'crucible_network_testing'
                - 'ai_quest_suggestions'
                - 'tournament_hosting'
                - 'guild_tournaments'
                - 'global_leaderboards'
                - 'persistence_90_days'
                - 'sprite_marketplace'

    sparki_enterprise:
        id: 'prod_sparki_enterprise'
        name: 'Sparki Enterprise'
        pricing:
            - type: 'custom'
              billing_type: 'annual'

        metadata:
            sparki_tier: 'enterprise'
            forgery_features:
                - 'unlimited_everything'
                - 'white_label_quests'
                - 'custom_domains'
                - 'compliance_testing'
                - 'governance_system'

User Action: "Upgrade to Team Tier"
  ↓
GET /api/forgery/upgrade/team
  ├─ Check current tier
  ├─ Calculate proration (if applicable)
  └─ Fetch Polar product details
  ↓
POST /api/forgery/checkout/create
  ├─ Create Polar checkout link
  │  └─ polar.checkout.create({
  │      product_id: "prod_sparki_team",
  │      success_url: "/upgrade/success",
  │      cancel_url: "/upgrade/cancel"
  │    })
  └─ Return checkout URL
  ↓
Browser redirects → polar.sh checkout
  ├─ User enters payment info
  ├─ Polar processes transaction
  └─ Webhook: checkout.completed
  ↓
POST /api/webhooks/polar
  ├─ Verify signature
  ├─ Update user tier in Forgery
  ├─ Unlock features
  └─ Send confirmation email
  ↓
Redirect → /upgrade/success
  └─ Display "Welcome to Team Tier!"

community:
    max_concurrent_quests: 1
    quests_per_day: 5
    max_guild_size: 5
    max_guilds: 1
    tournament_participation: false
    api_requests_per_day: 1000

team:
    max_concurrent_quests: 3
    quests_per_day: 20
    max_guild_size: 25
    max_guilds: 3
    tournament_participation: true
    api_requests_per_day: 10000
    team_members: 5

pro:
    max_concurrent_quests: 10
    quests_per_day: unlimited
    max_guild_size: 100
    max_guilds: unlimited
    tournament_participation: true
    api_requests_per_day: 100000
    team_members: 25

enterprise:
    max_concurrent_quests: unlimited
    quests_per_day: unlimited
    max_guild_size: unlimited
    max_guilds: unlimited
    tournament_participation: true
    api_requests_per_day: 'custom'
    team_members: unlimited

// Pseudocode: Feature Gate
package forgery

type FeatureGate struct {
  tier    string // "community", "team", "pro", "enterprise"
  userID  string
}

func (fg *FeatureGate) IsFeatureEnabled(feature string) bool {
  switch feature {
  case "guild_system":
    return fg.tier != "" // All tiers
  case "team_leaderboard":
    return fg.tier == "team" || fg.tier == "pro" || fg.tier == "enterprise"
  case "crucible":
    return fg.tier == "pro" || fg.tier == "enterprise"
  case "ai_suggestions":
    return fg.tier == "pro" || fg.tier == "enterprise"
  case "tournament_hosting":
    return fg.tier == "pro" || fg.tier == "enterprise"
  case "white_label":
    return fg.tier == "enterprise"
  default:
    return false
  }
}

func (fg *FeatureGate) GetQuotaRemaining(feature string) int {
  limits := GetTierLimits(fg.tier)
  used := GetFeatureUsage(fg.userID, feature)
  return limits[feature] - used
}

Competitor Pricing (CI/CD + Gamification):
  GitHub Actions:      Free (basic) - $21/mo (pro org)
  GitLab CI:          $228/year individual
  CircleCI:           $0-$2400+/month (scale dependent)

Sparki Positioning:
  Community:          $0/month (freemium)
  Team:               $25/month (2-5 person team)
  Pro:                $99/month (individual power user)
  Enterprise:         Custom (org-scale)

Year 1: Penetration pricing
  Team: $25/month (moderate discount to free)
  Pro:  $99/month (competitive with competitors)

Year 2: Value-based pricing
  Team: $35/month (+40% increase)
  Pro:  $129/month (+30% increase)

Year 3+: Market-based pricing
  Team: $49/month (align with GitHub)
  Pro:  $199/month (premium position)

Community Users: 10,000
  ↓ (Monthly)
  └─ Conversion Rate: 5-7% → Team Tier
     └─ Team Users: 500-700
        └─ Conversion Rate: 10-15% → Pro Tier
           └─ Pro Users: 50-105

community_to_team:
    trial_duration: 7 days
    trial_access: ['team_leaderboards', 'collaborative_quests', 'persistence']
    requires: 'Level 5+'

team_to_pro:
    trial_duration: 30 days
    trial_access: ['crucible', 'tournaments', 'marketplace', 'global_leaderboards']
    requires: 'Level 20+'

risk_reversal:
    money_back_guarantee: '30 days, 100% refund'
    no_questions_asked: true
    automatic: 'refund if no usage after 3 days'

Month 1 Target:  $2,500 MRR
  ├─ 100 Team @ $25 = $2,500
  └─ 0 Pro

Month 3 Target:  $15,000 MRR
  ├─ 500 Team @ $25 = $12,500
  ├─ 25 Pro @ $99 = $2,475
  └─ 0 Enterprise

Month 6 Target:  $50,000+ MRR
  ├─ 1,500 Team @ $25 = $37,500
  ├─ 100 Pro @ $99 = $9,900
  └─ 2 Enterprise @ $5,000 = $2,600

Month 12 Target: $250,000+ MRR
  ├─ 5,000 Team @ $25 = $125,000
  ├─ 1,000 Pro @ $99 = $99,000
  └─ 10 Enterprise @ $2,000 = $20,000

Month 12: $250K MRR × 12 = $3M ARR
  ├─ Forgery (40%): $1.2M ARR
  ├─ Loco Deployments (30%): $900K ARR
  ├─ Bind Verification (20%): $600K ARR
  └─ Plugins/Marketplace (10%): $300K ARR

cosmetics_shop:
  name: "Smithy Cosmetics"
  currency: "In-Game Credits (earned XP)"
  monthly_revenue_target: "$5,000" (5% of subscription)

  items:
    - name: "Mythic Title"
      cost: "1000 credits"
      usd_equivalent: "$10"
      margin: "70% (Polar takes 2.5% + $0.25)"

    - name: "Rainbow Username Color"
      cost: "500 credits"
      usd_equivalent: "$5"
      margin: "70%"

marketplace:
  name: "Artifact Trading"
  mechanism: "User-to-user trading + creator royalties"

  fees:
    transaction_fee: "5%" (Polar processes)
    creator_royalty: "10%" (Polar takes 2.5% + $0.25)
    platform_fee: "5%" (Sparki operations)

  examples:
    - item: "Legendary Storm-Tested Ingot"
      list_price: "$2.50"
      creator_royalty: "$0.25"
      platform_fee: "$0.12"
      seller_net: "$2.13"

enterprise_premium:
    white_label_quests: '$5,000 setup + $500/mo'
    compliance_testing_modules: '$10,000+/mo'
    custom_domain_support: '$2,000/mo'
    governance_audit: '$5,000 per audit'

// Polar Webhook Handler
package webhooks

func HandlePolarEvent(event PolarEvent) error {
  switch event.Type {
  case "checkout.created":
    return handleCheckoutCreated(event)

  case "checkout.updated":
    return handleCheckoutUpdated(event)

  case "checkout.expired":
    return handleCheckoutExpired(event)

  case "subscription.created":
    return handleSubscriptionCreated(event)

  case "subscription.activated":
    return handleSubscriptionActivated(event)

  case "subscription.cancelled":
    return handleSubscriptionCancelled(event)

  case "subscription.updated":
    return handleSubscriptionUpdated(event)

  case "invoice.created":
    return handleInvoiceCreated(event)

  case "invoice.payment_succeeded":
    return handleInvoicePaymentSucceeded(event)

  case "invoice.payment_failed":
    return handleInvoicePaymentFailed(event)

  default:
    return fmt.Errorf("unknown event type: %s", event.Type)
  }
}

// Subscription Activation
func handleSubscriptionActivated(event PolarEvent) error {
  sub := event.Data.Subscription

  // Update user tier
  user := GetUser(sub.CustomerEmail)
  user.Tier = mapPolarProductToTier(sub.ProductID)
  user.SubscriptionID = sub.ID
  user.SubscriptionStatus = "active"
  user.FeatureFlags = GetTierFeatures(user.Tier)
  user.SaveToDatabase()

  // Send welcome email
  SendWelcomeEmail(user, user.Tier)

  // Log event
  LogSubscriptionEvent(user.ID, "activated", user.Tier)

  return nil
}

// Subscription Cancellation
func handleSubscriptionCancelled(event PolarEvent) error {
  sub := event.Data.Subscription
  user := GetUser(sub.CustomerEmail)

  // Downgrade to community
  user.Tier = "community"
  user.SubscriptionStatus = "cancelled"
  user.SubscriptionCancelledAt = time.Now()
  user.FeatureFlags = GetTierFeatures("community")
  user.SaveToDatabase()

  // Send cancellation survey
  SendCancellationSurvey(user)

  // Log event
  LogSubscriptionEvent(user.ID, "cancelled", user.Tier)

  return nil
}

func VerifyPolarSignature(payload []byte, signature string) bool {
  secret := os.Getenv("POLAR_WEBHOOK_SECRET")

  // Create HMAC-SHA256 signature
  h := hmac.New(sha256.New, []byte(secret))
  h.Write(payload)
  expected := hex.EncodeToString(h.Sum(nil))

  // Compare with provided signature
  return subtle.ConstantTimeCompare([]byte(signature), []byte(expected)) == 1
}

email_sequence:
    day_0:
        subject: 'We miss you! 50% off your next month'
        offer: 'Team tier at $12.50/mo for 1 month'

    day_7:
        subject: 'New features in Forgery this week'
        benefit: 'Check out tournaments + marketplace'

    day_14:
        subject: 'What can we improve?'
        type: 'Feedback survey'
        offer: '1-month free trial if you rejoin'

    day_30:
        subject: 'Your free tier is ready'
        message: 'Come back anytime!'

type ChurnRisk struct {
  UserID        string
  TierLost      string
  DaysInactive  int
  LastQuestDate time.Time
  RiskLevel     string // low, medium, high
}

func CalculateChurnRisk(userID string) ChurnRisk {
  user := GetUser(userID)
  lastQuestDate := GetLastQuestDate(userID)
  daysSinceQuest := time.Now().Sub(lastQuestDate).Hours() / 24

  riskLevel := "low"
  if daysSinceQuest > 7 {
    riskLevel = "medium"
  }
  if daysSinceQuest > 30 {
    riskLevel = "high"
  }

  return ChurnRisk{
    UserID:        userID,
    TierLost:      user.Tier,
    DaysInactive:  int(daysSinceQuest),
    LastQuestDate: lastQuestDate,
    RiskLevel:     riskLevel,
  }
}

retention_mechanics:
  weekly_quests_reset: "Every Monday"

  seasonal_events:
    - "Founder's Month" (Dec): 2x XP all quests
    - "New Year Sprint" (Jan): Team tournaments
    - "Summer Surge" (Jul): Marketplace additions

  surprise_rewards:
    - Random "Double XP" hour (1x per week)
    - "Lucky Forge" bonus achievement (5% of logins)
    - Surprise cosmetics (Team+ only, 1x per month)

  content_updates:
    - New domains/quests: Monthly
    - New achievements: Monthly
    - New cosmetics: Bi-weekly
    - New lore chapters: Quarterly

Detection:
  ├─ Monitor payment disputes via Polar API
  ├─ Flag accounts with 2+ chargebacks
  └─ Temporary tier downgrade pending investigation

Resolution:
  ├─ Automatic chargeback response (Polar handles)
  ├─ Email user with dispute details
  ├─ Offer 7-day "cool off" period
  └─ Restore tier if dispute resolved in our favor

func DetectFraudulentUsage(userID string) bool {
  usage := GetUserUsage(userID)

  // Red flags
  if usage.QuestsCompletedToday > 1000 {
    return true // Impossible human rate
  }
  if usage.LocationChanges > 5 {
    return true // Rapid location hops
  }
  if usage.DevicesLastHour > 10 {
    return true // Multi-device spam
  }
  if usage.FailureRate < 0.1 {
    return true // Too good to be true
  }

  return false
}

## Forgery Tier Features

-   **Community Tier:** Free, features limited, no guarantee of persistence
-   **Team Tier:** Paid, team collaboration features, 7-day persistence
-   **Pro Tier:** Paid, advanced features, 90-day persistence
-   **Enterprise:** Custom agreement required

## Acceptable Use

Users may not:

-   Automate quest completion
-   Sell/trade accounts (except Enterprise marketplace)
-   Reverse-engineer gamification algorithms
-   Use Forgery for malicious domain testing

## Refund Policy

Polar handles all refunds per their merchant agreement.
Sparki honors 30-day money-back guarantee.

Data Handling:
  ├─ User quest data: Deleted upon request
  ├─ Leaderboard stats: Anonymized after 1 year
  ├─ Payment info: Handled by Polar (PCI-DSS compliant)
  └─ Email: Opt-in/out via account settings

-- Cohort Retention (% of users retained by week)
SELECT
  signup_cohort,
  week_0 = 100%, -- All users (baseline)
  week_1 = 85%,  -- After 1 week
  week_2 = 72%,  -- After 2 weeks
  week_4 = 58%,  -- After 1 month
  week_12 = 35%  -- After 3 months
FROM user_cohorts;

-- Conversion Cohort (% of free users converting to paid)
SELECT
  signup_cohort,
  users_total,
  users_converted_to_team = 150 (3%),
  users_converted_to_pro = 15 (0.3%),
  revenue = $3,975
FROM conversion_cohorts;

polar_fees:
    transaction_fee: 2.9% + $0.25 USD
    payout_frequency: 'Monthly'
    payout_delay: '2 business days'
    minimum_payout: '$0'

    example_calculation:
        subscription_amount: $25.00
        polar_fee: ($25 × 0.029) + $0.25 = $0.975
        sparki_net: $25.00 - $0.975 = $24.025
        margin_after_polar: 96% (excellent)

Month 3: 300 subscribers × $25 = $7,500 gross
  └─ Polar fees: $7,500 × 0.029 + (300 × $0.25) = $293 + $75 = $368
  └─ Sparki net: $7,132
  └─ Margin: 95.1%

Month 6: 1,500 subscribers × $25 = $37,500 gross
  └─ Polar fees: $37,500 × 0.029 + (1,500 × $0.25) = $1,088 + $375 = $1,463
  └─ Sparki net: $36,037
  └─ Margin: 96.1%