feat: Universal Extension Marketplace Backend

[roncodes]

Overview

This PR implements the backend infrastructure for the Universal Extension Marketplace, enabling self-hosted Fleetbase instances to discover and purchase both free and paid extensions without requiring a cloud subscription.

Key Features

1. Public Extension Discovery

• New endpoint: GET /~registry/v1/extensions
• Returns all published extensions (free and paid)
• Publicly accessible (no authentication required)
• Cached for 15 minutes for optimal performance
• Ordered by install count (most popular first)

2. Polymorphic Purchase System

• Purchases can now be linked to either:
  • Company (cloud users)
  • RegistryDeveloperAccount (self-hosted users)
• Uses Laravel's polymorphic relationship pattern
• Maintains backward compatibility with existing purchases

3. Multi-Authentication Purchase Flow

• Supports two authentication methods:
  • Session-based (cloud users via company_uuid)
  • Token-based (developer accounts via bearer token)
• Automatically identifies purchaser type
• Creates appropriate purchase records

Database Changes

Migration 1: Convert to Polymorphic

// Add to registry_extension_purchases
- purchaser_uuid (string)
- purchaser_type (string)

// Migrate existing data
company_uuid → purchaser_uuid
'Fleetbase\Models\Company' → purchaser_type

Migration 2: Add Indexes

- purchases_purchaser_index (purchaser_uuid, purchaser_type)
- purchases_extension_purchaser_index (extension_uuid, purchaser_uuid, purchaser_type)

Code Changes

Models

RegistryExtensionPurchase

• Added purchaser() polymorphic relationship
• Kept company() for backward compatibility
• Updated `` to include new columns

Controllers

RegistryExtensionController

• Added listPublicExtensions() method
• Implements caching strategy
• Returns formatted resource collection

RegistryPaymentsController

• Updated getStripeCheckoutSessionStatus()
• Identifies purchaser from session or bearer token
• Creates polymorphic purchase records
• Maintains company_uuid for backward compatibility

Routes

• Added public route: GET /~registry/v1/extensions
• No middleware (publicly accessible)

Benefits

✅ For Self-Hosted Users

• Can discover all available extensions
• Can purchase paid extensions without cloud subscription
• Seamless experience via centralized purchase flow

✅ For Extension Developers

• Clear monetization path
• Access to entire Fleetbase user base
• Automatic payment processing via Stripe

✅ For Fleetbase

• Unified marketplace for all users
• Maintains 10% facilitator fee
• Centralized payment security

✅ For the Ecosystem

• Encourages high-quality extension development
• Creates vibrant commercial marketplace
• Increases extension adoption

Testing Checklist

• Test public extension endpoint returns all published extensions
• Verify caching works correctly (15-minute TTL)
• Test purchase flow with cloud user (session auth)
• Test purchase flow with developer account (token auth)
• Verify polymorphic relationships work correctly
• Confirm backward compatibility with existing purchases
• Test that duplicate purchases are prevented
• Verify Stripe integration still works

Migration Notes

• Existing company_uuid values are automatically migrated to polymorphic format
• No data loss during migration
• Backward compatible with existing code that uses company_uuid
• Can safely deploy without breaking existing functionality

Related Work

This PR works in conjunction with:

• PR feat: Add Registry Developer Account Support #27 - Registry Developer Account support
• Upcoming - Frontend purchase flow (separate web app)
• Upcoming - Console integration for marketplace UI

Security Considerations

• Public endpoint only exposes published extensions (no sensitive data)
• Purchase authentication required via session or token
• Stripe handles all payment processing (PCI compliant)
• Polymorphic relationship prevents unauthorized purchases

Performance

• 15-minute cache significantly reduces database load
• Indexed polymorphic columns ensure fast queries
• Ordered by popularity for better UX
• Minimal overhead on existing purchase flow