codex has reworked checkout, but frontend doesnt work

app/Http/Controllers/CheckoutController.php

@@ -0,0 +1,222 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Http\Requests\Auth\LoginRequest;
+use App\Mail\Welcome;
+use App\Models\Package;
+use App\Models\PackagePurchase;
+use App\Models\Tenant;
+use App\Models\TenantPackage;
+use App\Models\User;
+use Illuminate\Auth\Events\Registered;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\\Support\\Facades\\DB;\r\nuse Illuminate\\Support\\Facades\\Hash;\r\nuse Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Str;
+use Illuminate\Validation\Rules;
+use Illuminate\Validation\ValidationException;
+use Inertia\Response;
+use Throwable;
+
+class CheckoutController extends Controller
+{
+    /**
+     * Render the checkout wizard using the legacy marketing controller for now.
+     */
+    public function show(Request $request, Package $package): Response
+    {
+        $marketingController = app(MarketingController::class);
+
+        return $marketingController->purchaseWizard($request, $package->getKey());
+    }
+
+    public function login(LoginRequest $request): JsonResponse
+    {
+        app()->setLocale($request->input('locale', app()->getLocale()));
+
+        $request->authenticate();
+        $request->session()->regenerate();
+
+        $user = $request->user()?->fresh();
+
+        return response()->json([
+            'success' => true,
+            'user' => $this->transformUser($user),
+        ]);
+    }
+
+    public function register(Request $request): JsonResponse
+    {
+        app()->setLocale($request->input('locale', app()->getLocale()));
+
+        try {
+            $validated = $request->validate([
+                'username' => ['required', 'string', 'max:255', 'unique:'.User::class],
+                'email' => ['required', 'string', 'lowercase', 'email', 'max:255', 'unique:'.User::class],
+                'password' => ['required', 'confirmed', Rules\Password::defaults()],
+                'first_name' => ['required', 'string', 'max:255'],
+                'last_name' => ['required', 'string', 'max:255'],
+                'address' => ['required', 'string', 'max:500'],
+                'phone' => ['required', 'string', 'max:20'],
+                'privacy_consent' => ['accepted'],
+                'package_id' => ['nullable', 'integer'],
+            ]);
+        } catch (ValidationException $exception) {
+            throw $exception;
+        }
+
+        $shouldAutoVerify = app()->environment(['local', 'testing']);
+
+        DB::beginTransaction();
+
+        try {
+            $user = User::create([
+                'username' => $validated['username'],
+                'email' => $validated['email'],
+                'first_name' => $validated['first_name'],
+                'last_name' => $validated['last_name'],
+                'address' => $validated['address'],
+                'phone' => $validated['phone'],
+                'password' => bcrypt($validated['password']),
+                'role' => 'user',
+                'pending_purchase' => !empty($validated['package_id']),
+            ]);
+
+            if ($user->pending_purchase) {
+                $request->session()->put('pending_user_id', $user->id);
+            }
+
+            if ($shouldAutoVerify) {
+                $user->forceFill(['email_verified_at' => now()])->save();
+            }
+
+            $tenant = Tenant::create([
+                'user_id' => $user->id,
+                'name' => $validated['first_name'].' '.$validated['last_name'],
+                'slug' => Str::slug($validated['first_name'].' '.$validated['last_name'].'-'.now()->timestamp),
+                'email' => $validated['email'],
+                'is_active' => true,
+                'is_suspended' => false,
+                'event_credits_balance' => 0,
+                'subscription_tier' => 'free',
+                'subscription_expires_at' => null,
+                'settings' => json_encode([
+                    'branding' => [
+                        'logo_url' => null,
+                        'primary_color' => '#3B82F6',
+                        'secondary_color' => '#1F2937',
+                        'font_family' => 'Inter, sans-serif',
+                    ],
+                    'features' => [
+                        'photo_likes_enabled' => false,
+                        'event_checklist' => false,
+                        'custom_domain' => false,
+                        'advanced_analytics' => false,
+                    ],
+                    'custom_domain' => null,
+                    'contact_email' => $validated['email'],
+                    'event_default_type' => 'general',
+                ]),
+            ]);
+
+            event(new Registered($user));
+
+            Auth::login($user);
+            $request->session()->regenerate();
+
+            DB::commit();
+
+            Mail::to($user)->queue(new Welcome($user));
+
+            $redirect = $shouldAutoVerify ? route('dashboard') : route('verification.notice');
+            $pendingPurchase = $user->pending_purchase;
+
+            if (!empty($validated['package_id'])) {
+                $package = Package::find($validated['package_id']);
+
+                if (!$package) {
+                    throw ValidationException::withMessages([
+                        'package_id' => __('validation.exists', ['attribute' => 'package'])
+                    ]);
+                }
+
+                if ((float) $package->price <= 0.0) {
+                    TenantPackage::create([
+                        'tenant_id' => $tenant->id,
+                        'package_id' => $package->id,
+                        'price' => 0,
+                        'active' => true,
+                    ]);
+
+                    PackagePurchase::create([
+                        'tenant_id' => $tenant->id,
+                        'package_id' => $package->id,
+                        'type' => $package->type === 'endcustomer' ? 'endcustomer_event' : 'reseller_subscription',
+                        'price' => 0,
+                        'purchased_at' => now(),
+                        'provider_id' => 'free',
+                    ]);
+
+                    $tenant->update(['subscription_status' => 'active']);
+                    $user->update(['role' => 'tenant_admin', 'pending_purchase' => false]);
+                    $pendingPurchase = false;
+                    $redirect = $shouldAutoVerify ? route('dashboard') : route('verification.notice');
+                } else {
+                    $pendingPurchase = true;
+                    $redirect = route('buy.packages', $package->id);
+                }
+            }
+
+            $freshUser = $user->fresh();
+
+            return response()->json([
+                'success' => true,
+                'user' => $this->transformUser($freshUser),
+                'pending_purchase' => $pendingPurchase,
+                'redirect' => $redirect,
+            ]);
+        } catch (ValidationException $validationException) {
+            DB::rollBack();
+            throw $validationException;
+        } catch (Throwable $throwable) {
+            DB::rollBack();
+            report($throwable);
+
+            return response()->json([
+                'success' => false,
+                'message' => __('auth.registration_failed'),
+            ], 500);
+        }
+    }
+
+    private function transformUser(?User $user): ?array
+    {
+        if (!$user) {
+            return null;
+        }
+
+        return [
+            'id' => $user->id,
+            'email' => $user->email,
+            'name' => trim(($user->first_name ?? '').' '.($user->last_name ?? '')) ?: $user->name,
+            'pending_purchase' => (bool) $user->pending_purchase,
+            'email_verified_at' => $user->email_verified_at,
+        ];
+    }
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+

app/Http/Controllers/MarketingController.php

@@ -129,6 +129,12 @@ class MarketingController extends Controller
     public function purchaseWizard(Request $request, $packageId)
     {
         $package = Package::findOrFail($packageId)->append(['features', 'limits']);
+        $packageOptions = Package::where('type', $package->type)
+            ->orderBy('price')
+            ->get()
+            ->map(function ($candidate) {
+                return $candidate->append(['features', 'limits']);
+            });
         $stripePublishableKey = config('services.stripe.key');
         $privacyHtml = view('legal.datenschutz-partial', ['locale' => app()->getLocale()])->render();
 
@@ -136,6 +142,7 @@ class MarketingController extends Controller
 
         $response = Inertia::render('marketing/PurchaseWizard', [
             'package' => $package,
+            'packageOptions' => $packageOptions,
             'stripePublishableKey' => $stripePublishableKey,
             'privacyHtml' => $privacyHtml,
         ])->toResponse($request);

app/Models/CheckoutSession.php

@@ -0,0 +1,106 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+class CheckoutSession extends Model
+{
+    use HasFactory;
+    use HasUuids;
+    use SoftDeletes;
+
+    public const STATUS_DRAFT = 'draft';
+    public const STATUS_AWAITING_METHOD = 'awaiting_payment_method';
+    public const STATUS_REQUIRES_CUSTOMER_ACTION = 'requires_customer_action';
+    public const STATUS_PROCESSING = 'processing';
+    public const STATUS_COMPLETED = 'completed';
+    public const STATUS_FAILED = 'failed';
+    public const STATUS_CANCELLED = 'cancelled';
+
+    public const PROVIDER_NONE = 'none';
+    public const PROVIDER_STRIPE = 'stripe';
+    public const PROVIDER_PAYPAL = 'paypal';
+    public const PROVIDER_FREE = 'free';
+
+    /**
+     * The attributes that aren't mass assignable.
+     */
+    protected $guarded = [];
+
+    /**
+     * Indicates if the IDs are auto-incrementing.
+     */
+    public $incrementing = false;
+
+    /**
+     * The data type of the primary key.
+     */
+    protected $keyType = 'string';
+
+    /**
+     * The attributes that should be cast.
+     */
+    protected $casts = [
+        'package_snapshot' => 'array',
+        'status_history' => 'array',
+        'provider_metadata' => 'array',
+        'expires_at' => 'datetime',
+        'completed_at' => 'datetime',
+        'amount_subtotal' => 'decimal:2',
+        'amount_total' => 'decimal:2',
+    ];
+
+    /**
+     * Default attributes.
+     */
+    protected $attributes = [
+        'status_history' => '[]',
+        'package_snapshot' => '[]',
+        'provider_metadata' => '[]',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function tenant(): BelongsTo
+    {
+        return $this->belongsTo(Tenant::class);
+    }
+
+    public function package(): BelongsTo
+    {
+        return $this->belongsTo(Package::class);
+    }
+
+    public function scopeActive($query)
+    {
+        return $query->whereNotIn('status', [
+            self::STATUS_COMPLETED,
+            self::STATUS_CANCELLED,
+        ])->where(function ($inner) {
+            $inner->whereNull('expires_at')->orWhere('expires_at', '>', now());
+        });
+    }
+
+    public function scopeByProviderId($query, string $providerField, string $value)
+    {
+        return $query->where($providerField, $value);
+    }
+
+    public function isExpired(): bool
+    {
+        return (bool) $this->expires_at && $this->expires_at->isPast();
+    }
+
+    public function requiresCustomerAction(): bool
+    {
+        return $this->status === self::STATUS_REQUIRES_CUSTOMER_ACTION;
+    }
+}

app/Providers/AppServiceProvider.php

@@ -2,6 +2,9 @@
 
 namespace App\Providers;
 
+use App\Services\Checkout\CheckoutAssignmentService;
+use App\Services\Checkout\CheckoutPaymentService;
+use App\Services\Checkout\CheckoutSessionService;
 use Illuminate\Cache\RateLimiting\Limit;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\RateLimiter;
@@ -14,7 +17,9 @@ class AppServiceProvider extends ServiceProvider
      */
     public function register(): void
     {
-        //
+        $this->app->singleton(CheckoutSessionService::class);
+        $this->app->singleton(CheckoutAssignmentService::class);
+        $this->app->singleton(CheckoutPaymentService::class);
     }
 
     /**
@@ -40,4 +45,4 @@ class AppServiceProvider extends ServiceProvider
             $this->app->register(\App\Providers\Filament\AdminPanelProvider::class);
         }
     }
-}
+}

app/Services/Checkout/CheckoutAssignmentService.php

@@ -0,0 +1,144 @@
+<?php
+
+namespace App\Services\Checkout;
+
+use App\Mail\Welcome;
+use App\Models\CheckoutSession;
+use App\Models\Package;
+use App\Models\PackagePurchase;
+use App\Models\Tenant;
+use App\Models\TenantPackage;
+use App\Models\User;
+use Illuminate\Auth\Events\Registered;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Str;
+
+class CheckoutAssignmentService
+{
+    /**
+     * Persist the purchase artefacts for a completed checkout session.
+     *
+     * @param  array{provider_reference?: string, payload?: array}  $options
+     */
+    public function finalise(CheckoutSession $session, array $options = []): void
+    {
+        DB::transaction(function () use ($session, $options) {
+            $tenant = $session->tenant;
+            $user = $session->user;
+
+            if (! $tenant && $user) {
+                $tenant = $this->ensureTenant($user, $session);
+            }
+
+            if (! $tenant) {
+                Log::warning('Checkout assignment skipped: missing tenant', ['session' => $session->id]);
+
+                return;
+            }
+
+            $package = $session->package;
+            if (! $package) {
+                Log::warning('Checkout assignment skipped: missing package', ['session' => $session->id]);
+
+                return;
+            }
+
+            $providerReference = $options['provider_reference']
+                ?? $session->stripe_payment_intent_id
+                ?? $session->paypal_order_id
+                ?? 'free';
+
+            $purchase = PackagePurchase::updateOrCreate(
+                [
+                    'tenant_id' => $tenant->id,
+                    'package_id' => $package->id,
+                    'provider_id' => $providerReference,
+                ],
+                [
+                    'price' => $session->amount_total,
+                    'type' => $package->type === 'reseller' ? 'reseller_subscription' : 'endcustomer_event',
+                    'purchased_at' => now(),
+                    'metadata' => $options['payload'] ?? null,
+                ]
+            );
+
+            TenantPackage::updateOrCreate(
+                [
+                    'tenant_id' => $tenant->id,
+                    'package_id' => $package->id,
+                ],
+                [
+                    'price' => $session->amount_total,
+                    'active' => true,
+                    'purchased_at' => now(),
+                    'expires_at' => $this->resolveExpiry($package, $tenant),
+                ]
+            );
+
+            if ($user && $user->pending_purchase) {
+                $this->activateUser($user);
+            }
+
+            if ($user) {
+                Mail::to($user)->queue(new Welcome($user));
+            }
+
+            Log::info('Checkout session assigned', [
+                'session' => $session->id,
+                'tenant' => $tenant->id,
+                'package' => $package->id,
+                'purchase' => $purchase->id,
+            ]);
+        });
+    }
+
+    protected function ensureTenant(User $user, CheckoutSession $session): ?Tenant
+    {
+        if ($user->tenant) {
+            return $user->tenant;
+        }
+
+        $tenant = Tenant::create([
+            'user_id' => $user->id,
+            'name' => $session->package_snapshot['name'] ?? $user->name,
+            'slug' => Str::slug(($user->name ?: $user->email).' '.now()->timestamp),
+            'email' => $user->email,
+            'is_active' => true,
+            'is_suspended' => false,
+            'event_credits_balance' => 0,
+            'subscription_tier' => 'free',
+            'subscription_status' => 'active',
+            'settings' => [
+                'contact_email' => $user->email,
+            ],
+        ]);
+
+        event(new Registered($user));
+
+        return $tenant;
+    }
+
+    protected function resolveExpiry(Package $package, Tenant $tenant)
+    {
+        if ($package->type === 'reseller') {
+            $hasActive = TenantPackage::where('tenant_id', $tenant->id)
+                ->where('active', true)
+                ->exists();
+
+            return $hasActive ? now()->addYear() : now()->addDays(14);
+        }
+
+        return now()->addYear();
+    }
+
+    protected function activateUser(User $user): void
+    {
+        $user->forceFill([
+            'email_verified_at' => $user->email_verified_at ?? now(),
+            'role' => $user->role === 'user' ? 'tenant_admin' : $user->role,
+            'pending_purchase' => false,
+        ])->save();
+    }
+}

app/Services/Checkout/CheckoutPaymentService.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace App\Services\Checkout;
+
+use App\Models\CheckoutSession;
+use App\Models\Tenant;
+use LogicException;
+
+class CheckoutPaymentService
+{
+    public function __construct(
+        private readonly CheckoutSessionService $sessions,
+        private readonly CheckoutAssignmentService $assignment,
+    ) {
+    }
+
+    public function initialiseStripe(CheckoutSession $session, array $payload = []): array
+    {
+        if ($session->provider !== CheckoutSession::PROVIDER_STRIPE) {
+            $this->sessions->selectProvider($session, CheckoutSession::PROVIDER_STRIPE);
+        }
+
+        // TODO: integrate Stripe PaymentIntent creation and return client_secret + publishable key
+        return [
+            'session_id' => $session->id,
+            'status' => $session->status,
+            'message' => 'Stripe integration pending implementation.',
+        ];
+    }
+
+    public function confirmStripe(CheckoutSession $session, array $payload = []): CheckoutSession
+    {
+        if ($session->provider !== CheckoutSession::PROVIDER_STRIPE) {
+            throw new LogicException('Cannot confirm Stripe payment on a non-Stripe session.');
+        }
+
+        // TODO: verify PaymentIntent status with Stripe SDK and update session metadata
+        $this->sessions->markProcessing($session);
+
+        return $session;
+    }
+
+    public function initialisePayPal(CheckoutSession $session, array $payload = []): array
+    {
+        if ($session->provider !== CheckoutSession::PROVIDER_PAYPAL) {
+            $this->sessions->selectProvider($session, CheckoutSession::PROVIDER_PAYPAL);
+        }
+
+        // TODO: integrate PayPal Orders API and return order id + approval link
+        return [
+            'session_id' => $session->id,
+            'status' => $session->status,
+            'message' => 'PayPal integration pending implementation.',
+        ];
+    }
+
+    public function capturePayPal(CheckoutSession $session, array $payload = []): CheckoutSession
+    {
+        if ($session->provider !== CheckoutSession::PROVIDER_PAYPAL) {
+            throw new LogicException('Cannot capture PayPal payment on a non-PayPal session.');
+        }
+
+        // TODO: call PayPal capture endpoint and persist order/subscription identifiers
+        $this->sessions->markProcessing($session);
+
+        return $session;
+    }
+
+    public function finaliseFree(CheckoutSession $session): CheckoutSession
+    {
+        if ($session->provider !== CheckoutSession::PROVIDER_FREE) {
+            $this->sessions->selectProvider($session, CheckoutSession::PROVIDER_FREE);
+        }
+
+        $this->sessions->markProcessing($session);
+        $this->assignment->finalise($session, ['source' => 'free']);
+
+        return $this->sessions->markCompleted($session);
+    }
+
+    public function attachTenantAndResume(CheckoutSession $session, Tenant $tenant): CheckoutSession
+    {
+        $this->sessions->attachTenant($session, $tenant);
+        $this->sessions->refreshExpiration($session);
+
+        return $session;
+    }
+}

app/Services/Checkout/CheckoutSessionService.php

@@ -0,0 +1,216 @@
+<?php
+
+namespace App\Services\Checkout;
+
+use App\Models\CheckoutSession;
+use App\Models\Package;
+use App\Models\Tenant;
+use App\Models\User;
+use Carbon\CarbonInterface;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+use RuntimeException;
+
+class CheckoutSessionService
+{
+    private int $sessionTtlMinutes;
+
+    private int $historyRetention;
+
+    public function __construct(?int $sessionTtlMinutes = null, ?int $historyRetention = null)
+    {
+        $this->sessionTtlMinutes = $sessionTtlMinutes ?? (int) config('checkout.session_ttl_minutes', 30);
+        $this->historyRetention = $historyRetention ?? (int) config('checkout.status_history_max', 25);
+    }
+
+    public function createOrResume(?User $user, Package $package, array $context = []): CheckoutSession
+    {
+        return DB::transaction(function () use ($user, $package, $context) {
+            $existing = $this->findActiveSession($user, $package);
+
+            if ($existing) {
+                $this->refreshExpiration($existing);
+
+                return $existing;
+            }
+
+            $session = new CheckoutSession();
+            $session->id = (string) Str::uuid();
+            $session->status = CheckoutSession::STATUS_DRAFT;
+            $session->provider = CheckoutSession::PROVIDER_NONE;
+            $session->user()->associate($user);
+            $session->tenant()->associate($context['tenant'] ?? null);
+            $session->package()->associate($package);
+            $session->package_snapshot = $this->packageSnapshot($package);
+            $session->currency = Arr::get($session->package_snapshot, 'currency', 'EUR');
+            $session->amount_subtotal = Arr::get($session->package_snapshot, 'price', 0);
+            $session->amount_total = Arr::get($session->package_snapshot, 'price', 0);
+            $session->locale = $context['locale'] ?? app()->getLocale();
+            $session->expires_at = now()->addMinutes($this->sessionTtlMinutes);
+            $session->status_history = [];
+            $this->appendStatus($session, CheckoutSession::STATUS_DRAFT, 'session_created');
+
+            $session->save();
+
+            return $session;
+        });
+    }
+
+    public function updatePackage(CheckoutSession $session, Package $package): CheckoutSession
+    {
+        return DB::transaction(function () use ($session, $package) {
+            $session->package()->associate($package);
+            $session->package_snapshot = $this->packageSnapshot($package);
+            $session->amount_subtotal = Arr::get($session->package_snapshot, 'price', 0);
+            $session->amount_total = Arr::get($session->package_snapshot, 'price', 0);
+            $session->provider = CheckoutSession::PROVIDER_NONE;
+            $session->status = CheckoutSession::STATUS_DRAFT;
+            $session->stripe_payment_intent_id = null;
+            $session->stripe_customer_id = null;
+            $session->stripe_subscription_id = null;
+            $session->paypal_order_id = null;
+            $session->paypal_subscription_id = null;
+            $session->provider_metadata = [];
+            $session->failure_reason = null;
+            $session->expires_at = now()->addMinutes($this->sessionTtlMinutes);
+            $this->appendStatus($session, CheckoutSession::STATUS_DRAFT, 'package_switched');
+            $session->save();
+
+            return $session;
+        });
+    }
+
+    public function selectProvider(CheckoutSession $session, string $provider): CheckoutSession
+    {
+        $provider = strtolower($provider);
+
+        if (! in_array($provider, [CheckoutSession::PROVIDER_STRIPE, CheckoutSession::PROVIDER_PAYPAL, CheckoutSession::PROVIDER_FREE], true)) {
+            throw new RuntimeException("Unsupported checkout provider [{$provider}]");
+        }
+
+        $session->provider = $provider;
+        $session->status = $provider === CheckoutSession::PROVIDER_FREE
+            ? CheckoutSession::STATUS_PROCESSING
+            : CheckoutSession::STATUS_AWAITING_METHOD;
+        $session->failure_reason = null;
+        $session->expires_at = now()->addMinutes($this->sessionTtlMinutes);
+        $this->appendStatus($session, $session->status, 'provider_selected');
+        $session->save();
+
+        return $session;
+    }
+
+    public function markRequiresCustomerAction(CheckoutSession $session, string $reason = null): CheckoutSession
+    {
+        $session->status = CheckoutSession::STATUS_REQUIRES_CUSTOMER_ACTION;
+        $session->failure_reason = $reason;
+        $this->appendStatus($session, CheckoutSession::STATUS_REQUIRES_CUSTOMER_ACTION, $reason ?? 'requires_action');
+        $session->save();
+
+        return $session;
+    }
+
+    public function markProcessing(CheckoutSession $session, array $metadata = []): CheckoutSession
+    {
+        $session->status = CheckoutSession::STATUS_PROCESSING;
+        if (! empty($metadata)) {
+            $session->provider_metadata = array_merge($session->provider_metadata ?? [], $metadata);
+        }
+        $session->failure_reason = null;
+        $this->appendStatus($session, CheckoutSession::STATUS_PROCESSING, 'processing');
+        $session->save();
+
+        return $session;
+    }
+
+    public function markCompleted(CheckoutSession $session, ?CarbonInterface $completedAt = null): CheckoutSession
+    {
+        $session->status = CheckoutSession::STATUS_COMPLETED;
+        $session->completed_at = $completedAt ?? now();
+        $session->failure_reason = null;
+        $this->appendStatus($session, CheckoutSession::STATUS_COMPLETED, 'completed');
+        $session->save();
+
+        return $session;
+    }
+
+    public function markFailed(CheckoutSession $session, string $reason): CheckoutSession
+    {
+        $session->status = CheckoutSession::STATUS_FAILED;
+        $session->failure_reason = $reason;
+        $this->appendStatus($session, CheckoutSession::STATUS_FAILED, $reason);
+        $session->save();
+
+        return $session;
+    }
+
+    public function cancel(CheckoutSession $session, string $reason = 'cancelled'): CheckoutSession
+    {
+        $session->status = CheckoutSession::STATUS_CANCELLED;
+        $session->failure_reason = $reason;
+        $this->appendStatus($session, CheckoutSession::STATUS_CANCELLED, $reason);
+        $session->save();
+
+        return $session;
+    }
+
+    public function refreshExpiration(CheckoutSession $session): CheckoutSession
+    {
+        $session->expires_at = now()->addMinutes($this->sessionTtlMinutes);
+        $session->save();
+
+        return $session;
+    }
+
+    public function attachTenant(CheckoutSession $session, Tenant $tenant): CheckoutSession
+    {
+        $session->tenant()->associate($tenant);
+        $session->save();
+
+        return $session;
+    }
+
+    protected function appendStatus(CheckoutSession $session, string $status, ?string $reason = null): void
+    {
+        $history = $session->status_history ?? [];
+        $history[] = [
+            'status' => $status,
+            'reason' => $reason,
+            'at' => now()->toIso8601String(),
+        ];
+
+        if (count($history) > $this->historyRetention) {
+            $history = array_slice($history, -1 * $this->historyRetention);
+        }
+
+        $session->status_history = $history;
+    }
+
+    protected function packageSnapshot(Package $package): array
+    {
+        return [
+            'id' => $package->getKey(),
+            'name' => $package->name,
+            'type' => $package->type,
+            'price' => (float) $package->price,
+            'currency' => $package->currency ?? 'EUR',
+            'features' => $package->features,
+            'limits' => $package->limits,
+        ];
+    }
+
+    protected function findActiveSession(?User $user, Package $package): ?CheckoutSession
+    {
+        if (! $user) {
+            return null;
+        }
+
+        return CheckoutSession::query()
+            ->where('user_id', $user->getKey())
+            ->where('package_id', $package->getKey())
+            ->active()
+            ->orderByDesc('created_at')
+            ->first();
+    }
+}