Billing & Subscriptions

Game Framework includes a comprehensive billing system built on Authsome's subscription plugin, providing flexible pricing, usage tracking, and hard-block feature enforcement.

System Architecture

sequenceDiagram
    participant Handler
    participant BillingService
    participant EnforcementService
    participant Repository
    
    Handler->>BillingService: EnforceFeature(workspaceID, featureKey)
    BillingService->>EnforcementService: Check Access
    EnforcementService->>Repository: Get Current Usage
    EnforcementService->>EnforcementService: Get Plan Limits + Addons
    EnforcementService->>EnforcementService: Compare Usage vs Limit
    alt Usage >= Limit
        EnforcementService-->>Handler: 402 Payment Required
    else Usage < Limit
        EnforcementService-->>Handler: Allow Operation
    end

Key Features

10 Trackable Features

Limit-Based Features

• Max Packages: Count-based limit (Free: 5, Pro: 50, Enterprise: Unlimited)
• Max Storage: Size-based limit in bytes (Free: 10GB, Pro: 100GB, Enterprise: 1TB)
• Max Downloads: Monthly count limit (Free: 1K, Pro: 100K, Enterprise: Unlimited)
• Max Versions: Per-package count limit (Free: 10/pkg, Pro: 100/pkg, Enterprise: Unlimited)
• Max Bandwidth: Monthly data transfer in bytes (Free: 50GB, Pro: 1TB, Enterprise: 10TB)

Boolean Features

• API Access: API key creation and programmatic access (Pro+)
• Advanced Analytics: Detailed download statistics and trends (Pro+)
• CDN Distribution: Global CDN delivery for faster downloads (Enterprise only)
• Priority Support: Faster response times and dedicated channel (Enterprise only)
• Team Features: Multi-user collaboration with roles (Pro+)

Hard-Block Enforcement

Game Framework uses hard-block enforcement - operations are prevented when limits are exceeded.

Enforcement Flow

graph TD
    A[User Attempts Action] --> B{Billing Service}
    B --> C[Get Current Usage]
    B --> D[Get Plan Limit]
    B --> E[Get Addon Capacity]
    C --> F{Usage >= Total Limit?}
    D --> F
    E --> F
    F -->|Yes| G[Return 402 Payment Required]
    F -->|No| H[Allow Operation]
    G --> I[Show Upgrade Prompt]
    H --> J[Execute Action]

Pricing Plans

Addon System

Workspaces can purchase addons to extend their base plan limits:

• Extra Bandwidth: $10 per 100GB/month
• Extra Storage: $20 per 100GB/month
• Build CPU: $15 per concurrent build/month

Learn more about addons →

Usage Tracking

The billing system tracks feature consumption in real-time:

• Package Count: Counted when packages are created/deleted
• Storage Usage: Sum of all artifact sizes
• Download Count: Incremented on each artifact download
• Bandwidth Usage: Sum of bytes transferred during downloads
• Version Count: Versions per package

Member-Based Billing

Pro and Enterprise plans bill based on active member count:

• ✓ Active members (not suspended, accepted invitation)
• ✗ Suspended members
• ✗ Deleted members
• ✗ Pending invitations

Flutter Integration Examples

Checking Limits Before Publishing

# Check current usage before publishing
curl https://registry.yourcompany.com/v1/workspaces/ws_ID/billing/usage \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "packages": {
    "current": 12,
    "limit": 50,
    "available": 38
  },
  "storage": {
    "current_bytes": 5368709120,
    "limit_bytes": 107374182400,
    "available_bytes": 102005473280,
    "current_gb": 5.0,
    "limit_gb": 100.0
  }
}

Handling Quota Errors

When you exceed limits:

# Publishing fails with 402
$ flutter pub publish --server=https://registry.yourcompany.com

Error: 402 Payment Required
{
  "error": {
    "code": "quota_exceeded",
    "message": "Package limit exceeded (5/5 packages)",
    "feature": "max_packages",
    "current_usage": 5,
    "limit": 5,
    "upgrade_url": "https://registry.yourcompany.com/billing/upgrade"
  }
}

Solution: Upgrade plan or delete unused packages.

Flutter Package Size Considerations

Monitor your package sizes to stay within storage limits:

# Check package size before publishing
flutter pub publish --dry-run

# Output shows size
Package archive: 2.5 MB

Storage tips for Flutter packages:

• Exclude build artifacts (.dart_tool/, build/)
• Use .pubignore for large files
• Compress images and assets
• Keep dependencies minimal

Example: Checking Limits in CI/CD

# GitHub Actions - Check quota before publishing
- name: Check Package Quota
  run: |
    USAGE=$(curl -s https://registry.yourcompany.com/v1/workspaces/$WS_ID/billing/usage \
      -H "Authorization: Bearer ${{ secrets.GAME_FRAMEWORK_TOKEN }}" \
      | jq '.packages.available')
    
    if [ "$USAGE" -le 0 ]; then
      echo "✗ Package limit reached. Please upgrade plan."
      exit 1
    fi
    
    echo "✓ Packages available: $USAGE"

- name: Publish Package
  run: flutter pub publish --force

Plan Comparison for Flutter Teams

Choosing the Right Plan

Free Plan - Perfect for:

• Solo developers
• Small side projects
• Testing Game Framework
• Personal packages

Pro Plan - Ideal for:

• Small to medium teams (2-10 developers)
• Multiple Flutter apps
• Active CI/CD pipelines
• Growing package libraries

Enterprise Plan - Best for:

• Large organizations (10+ developers)
• Multiple teams/workspaces
• High download volumes
• Compliance requirements

API Endpoints

All billing endpoints are workspace-scoped:

• GET /v1/workspaces/:id/billing/subscription - Get current subscription
• GET /v1/workspaces/:id/billing/features - List features with access status
• GET /v1/workspaces/:id/billing/usage - Get usage summary
• POST /v1/workspaces/:id/billing/subscription/change-plan - Change plan
• POST /v1/workspaces/:id/billing/subscription/cancel - Cancel subscription

View API Reference →

Next Steps

• Billing Plans - Detailed plan comparison
• Addons - Extend your limits
• Enforcement - How limits are enforced
• Quick Start - Publish your first package