feat: implement billing package with FedaPay and Mobile Money support

Complete billing system for West African markets including subscriptions,
one-time payments, marketplace commissions, and seller payouts.

Author: Just Chris

CLAUDE.md

@@ -2,59 +2,88 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Project Overview
-
-Laravel billing package for the Ratoufa project. Built on PHP 8.4+ with Laravel 11/12 support using Spatie's Laravel Package Tools.
-
 ## Commands
 
 ```bash
-# Run all tests and checks
+# Install dependencies
+composer install
+
+# Run all tests (lint, type coverage, typos, unit tests, static analysis, refactoring checks)
 composer test
 
 # Run specific test suites
-composer test:unit          # Pest tests (parallel)
+composer test:unit          # Pest unit tests (parallel)
 composer test:types         # PHPStan static analysis
 composer test:lint          # Pint code style check
-composer test:typos         # Peck typo checker
+composer test:type-coverage # Type coverage (100% required)
+composer test:typos         # Peck typo detection
 composer test:refactor      # Rector dry-run
-composer test:type-coverage # Type coverage (requires 100%)
-composer test:unit:coverage # Unit test coverage (requires 100%)
 
 # Run a single test file
-./vendor/bin/pest tests/ExampleTest.php
+./vendor/bin/pest tests/Unit/ExampleTest.php
 
 # Run a single test by name
 ./vendor/bin/pest --filter="test name here"
 
-# Fix code style and run refactoring
-composer fix               # Runs PHPStan, Rector, then Pint
-composer lint              # Pint auto-fix
-composer refactor          # Rector auto-fix
-composer analyse           # PHPStan only
+# Fix code style and run fixes
+composer lint               # Fix code style with Pint
+composer refactor           # Apply Rector refactoring
+composer fix                # PHPStan + Rector + Pint combined
 ```
 
 ## Architecture
 
-This is a Laravel package using Spatie's `laravel-package-tools` for service provider configuration:
+This is a Laravel billing package for West African markets with FedaPay integration supporting Mobile Money payments.
+
+### Core Components
+
+- **BillingManager** (`src/BillingManager.php`) - Extends Laravel's Manager class, provides the main facade for all billing operations. Manages provider drivers and exposes methods like `charge()`, `createPaymentIntent()`, `getCheckoutUrl()`.
+
+- **BillingProvider Contract** (`src/Contracts/BillingProvider.php`) - Interface that all payment providers must implement. Defines methods for customer management, charges, refunds, subscriptions, and webhooks.
+
+- **AbstractProvider** (`src/Providers/AbstractProvider.php`) - Base class for payment providers with shared logic.
+
+- **FedaPayProvider** (`src/Providers/FedaPay/`) - Default implementation for FedaPay with Mobile Money support (MTN, Moov, Togocel).
+
+### Traits for Eloquent Models
+
+- **Billable** (`src/Concerns/Billable.php`) - Add to User model for subscription and payment capabilities: `subscriptions()`, `payments()`, `charge()`, `pay()`, `newSubscription()`.
+
+- **Commissionable** (`src/Concerns/Commissionable.php`) - Add to seller/organization models for marketplace features: commission tracking, payouts, transaction recording.
+
+### Data Transfer Objects
+
+Located in `src/Data/`: `CommissionData`, `CustomerData`, `PayoutData`, `PaymentIntentData`, `CheckoutData`.
+
+### Services
+
+- **SubscriptionBuilderService** - Fluent builder for creating subscriptions with trials, metadata.
+- **CommissionCalculator** / **CommissionService** - Calculate and record marketplace commissions.
+- **InstantPayoutService** - Process seller payouts.
+
+### Models
+
+- `Plan` - Subscription plans with pricing, intervals.
+- `Subscription` - User subscriptions with status, trial dates, grace periods.
+- `Payment` - Payment records.
+- `Transaction` - Marketplace sale transactions.
+- `Payout` - Seller payout records.
+
+### Enums
 
-- `src/BillingServiceProvider.php` - Package configuration (config, views, migrations, commands)
-- `src/Billing.php` - Main service class
-- `src/Facades/Billing.php` - Facade for the Billing service
-- `src/Commands/` - Artisan commands
-- `config/billing.php` - Package configuration
-- `database/migrations/` - Migration stubs (published with `--tag="laravel-billing-migrations"`)
+Located in `src/Enums/`: `PaymentStatusEnum`, `SubscriptionStatusEnum`, `PlanIntervalEnum`, `PayoutStatusEnum`, `PayoutMethodEnum`, `TransactionStatusEnum`.
 
-Tests use Orchestra Testbench with Pest. Base test case in `tests/TestCase.php` configures the package providers and factory resolution.
+## Code Style
 
-## Code Style Requirements
+- PHP 8.4+ with strict types (`declare(strict_types=1)`)
+- All classes must be `final` (enforced by Pint)
+- PHPStan level 5 with 100% type coverage required
+- Laravel Pint with strict rules (see `pint.json`): `final_class`, `strict_comparison`, `date_time_immutable`, `mb_str_functions`
+- Class element ordering enforced: traits, constants, properties, constructor, magic methods, public methods, protected methods, private methods
 
-Enforced via Pint (`pint.json`):
-- `declare(strict_types=1)` required
-- Classes should be `final`
-- Use `DateTimeImmutable` over `DateTime`
-- Use `mb_str_*` functions
-- Strict comparisons (`===`, `!==`)
-- Specific class element ordering (traits, constants, properties, constructor, then methods by visibility)
+## Adding a New Provider
 
-Architecture tests (`tests/ArchTest.php`) forbid: `dd`, `dump`, `ray`
+1. Create provider class extending `AbstractProvider` in `src/Providers/`
+2. Implement all methods from `BillingProvider` contract
+3. Optionally implement `MobileMoneyProvider` or `PayoutProvider` contracts
+4. Register driver in `BillingManager::createXxxDriver()` or via `extend()` in a service provider