Release v0.1.15 — Phase 15: Conversion Cost Estimator

app/Actions/Conversions/CreateConversionJobAction.php

@@ -4,20 +4,27 @@
 
 namespace App\Actions\Conversions;
 
+use App\Contracts\Billing\CreditLedger;
+use App\Enums\ConversionCreditChargeStatus;
 use App\Enums\ConversionStatus;
 use App\Enums\FileFormat;
+use App\Exceptions\Billing\InsufficientCreditsException;
 use App\Jobs\ProcessConversionJob;
+use App\Models\ConversionCreditCharge;
 use App\Models\ConversionJob;
 use App\Models\FileRecord;
 use App\Models\User;
 use App\Support\Conversions\Exceptions\UnsupportedConversionException;
 use App\Support\Converters\ConverterRegistry;
 use App\Support\Converters\Exceptions\UnsupportedFormatException;
+use Illuminate\Support\Facades\DB;
 
 final class CreateConversionJobAction
 {
     public function __construct(
         private readonly ConverterRegistry $converterRegistry,
+        private readonly EstimateConversionCostAction $estimateCost,
+        private readonly CreditLedger $creditLedger,
     ) {}
 
     /**
@@ -48,19 +55,47 @@ public function handle(
 
         $normalizedOptions = $converter->validateOptions($options);
 
-        $job = ConversionJob::create([
-            'user_id' => $user->id,
-            'source_file_id' => $sourceFile->id,
-            'source_format' => $sourceFormat,
-            'target_format' => $normalizedTarget,
-            // Driver-registry key (e.g. "png_to_jpg") — distinct from the catalog
-            // Converter::key() ("png:jpg"). ConverterDriverRegistry::findOrFail()
-            // resolves drivers on this value, so it must match driver keys.
-            'converter_key' => "{$sourceFormat}_to_{$normalizedTarget}",
-            'options_json' => $normalizedOptions,
-            'status' => ConversionStatus::Queued,
-            'progress' => 0,
-        ]);
+        $cost = $this->estimateCost->handle($sourceFile, $converter, $normalizedOptions);
+
+        $balance = $this->creditLedger->balance($user);
+
+        if ($balance < $cost->amount) {
+            throw InsufficientCreditsException::make(
+                required: $cost->amount,
+                available: $balance,
+            );
+        }
+
+        // Wrap job + charge creation in a transaction so a failed charge insert
+        // cannot leave an orphan queued job. Dispatch happens after commit so
+        // the worker never picks up a job whose charge record does not exist.
+        $job = DB::transaction(function () use ($user, $sourceFile, $sourceFormat, $normalizedTarget, $normalizedOptions, $cost) {
+            $job = ConversionJob::create([
+                'user_id' => $user->id,
+                'source_file_id' => $sourceFile->id,
+                'source_format' => $sourceFormat,
+                'target_format' => $normalizedTarget,
+                // Driver-registry key (e.g. "png_to_jpg") — distinct from the catalog
+                // Converter::key() ("png:jpg"). ConverterDriverRegistry::findOrFail()
+                // resolves drivers on this value, so it must match driver keys.
+                'converter_key' => "{$sourceFormat}_to_{$normalizedTarget}",
+                'options_json' => $normalizedOptions,
+                'status' => ConversionStatus::Queued,
+                'progress' => 0,
+            ]);
+
+            ConversionCreditCharge::create([
+                'user_id' => $user->id,
+                'conversion_job_id' => $job->id,
+                'estimated_amount' => $cost->amount,
+                'captured_amount' => 0,
+                'refunded_amount' => 0,
+                'status' => ConversionCreditChargeStatus::Estimated,
+                'breakdown_json' => $cost->breakdown,
+            ]);
+
+            return $job;
+        });
 
         ProcessConversionJob::dispatch($job->id);
 

app/Actions/Conversions/EstimateConversionCostAction.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\Conversions;
+
+use App\Contracts\Billing\ConversionCostEstimator;
+use App\Data\Credits\CreditCost;
+use App\Models\FileRecord;
+use App\Support\Converters\Contracts\Converter;
+
+final class EstimateConversionCostAction
+{
+    public function __construct(
+        private readonly ConversionCostEstimator $estimator,
+    ) {}
+
+    /**
+     * @param  array<string, mixed>  $options
+     */
+    public function handle(FileRecord $file, Converter $converter, array $options = []): CreditCost
+    {
+        return $this->estimator->estimate($file, $converter, $options);
+    }
+}

app/Contracts/Billing/ConversionCostEstimator.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Contracts\Billing;
+
+use App\Data\Credits\CreditCost;
+use App\Models\FileRecord;
+use App\Support\Converters\Contracts\Converter;
+
+interface ConversionCostEstimator
+{
+    /**
+     * @param  array<string, mixed>  $options
+     */
+    public function estimate(FileRecord $file, Converter $converter, array $options = []): CreditCost;
+}

app/Data/Credits/CreditCost.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Data\Credits;
+
+final readonly class CreditCost
+{
+    public function __construct(
+        public int $amount,
+        public array $breakdown,
+    ) {
+        if ($this->amount < 0) {
+            throw new \InvalidArgumentException('Credit cost amount cannot be negative.');
+        }
+    }
+}

app/Data/Credits/CreditCostBreakdown.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Data\Credits;
+
+final readonly class CreditCostBreakdown
+{
+    public function __construct(
+        public int $base,
+        public int $size,
+        public int $features,
+        public int $total,
+        public array $details,
+    ) {
+        if ($this->base < 0) {
+            throw new \InvalidArgumentException('Breakdown base cannot be negative.');
+        }
+        if ($this->size < 0) {
+            throw new \InvalidArgumentException('Breakdown size cannot be negative.');
+        }
+        if ($this->features < 0) {
+            throw new \InvalidArgumentException('Breakdown features cannot be negative.');
+        }
+        if ($this->total < 0) {
+            throw new \InvalidArgumentException('Breakdown total cannot be negative.');
+        }
+        if ($this->total !== ($this->base + $this->size + $this->features)) {
+            throw new \InvalidArgumentException(
+                "Breakdown total ({$this->total}) must equal base + size + features ({$this->base} + {$this->size} + {$this->features})."
+            );
+        }
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'base' => $this->base,
+            'size' => $this->size,
+            'features' => $this->features,
+            'total' => $this->total,
+            'details' => $this->details,
+        ];
+    }
+}

app/Enums/ConversionCreditChargeStatus.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums;
+
+enum ConversionCreditChargeStatus: string
+{
+    case Estimated = 'estimated';
+    case Captured = 'captured';
+    case Refunded = 'refunded';
+    case Failed = 'failed';
+}

app/Exceptions/Billing/UnsupportedConversionCostException.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Billing;
+
+use DomainException;
+
+final class UnsupportedConversionCostException extends DomainException
+{
+    public static function forPair(string $source, string $target): self
+    {
+        return new self("Cannot estimate cost for unsupported conversion: {$source} → {$target}.");
+    }
+}

app/Jobs/ProcessConversionJob.php

@@ -5,7 +5,10 @@
 namespace App\Jobs;
 
 use App\Actions\Conversions\RecordConversionResultFileAction;
+use App\Contracts\Billing\CreditLedger;
+use App\Enums\ConversionCreditChargeStatus;
 use App\Enums\ConversionStatus;
+use App\Models\ConversionCreditCharge;
 use App\Models\ConversionJob;
 use App\Support\Conversions\ConverterDriverRegistry;
 use App\Support\Conversions\DTO\ConversionContext;
@@ -14,6 +17,7 @@
 use Illuminate\Foundation\Bus\Dispatchable;
 use Illuminate\Queue\InteractsWithQueue;
 use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Str;
 use Throwable;
 
@@ -31,6 +35,7 @@ public function __construct(
     public function handle(
         ConverterDriverRegistry $drivers,
         RecordConversionResultFileAction $recorder,
+        CreditLedger $creditLedger,
     ): void {
         $job = ConversionJob::find($this->conversionJobId);
 
@@ -64,6 +69,15 @@ public function handle(
                 'progress' => 100,
                 'completed_at' => now(),
             ])->save();
+
+            // Capture credits separately — a billing failure must not undo a
+            // successful conversion, so we report and move on rather than
+            // letting the exception propagate to the failure catch block below.
+            try {
+                $this->captureCredits($job, $creditLedger);
+            } catch (Throwable $captureException) {
+                report($captureException);
+            }
         } catch (Throwable $exception) {
             $job->forceFill([
                 'status' => ConversionStatus::Failed,
@@ -72,7 +86,56 @@ public function handle(
                 'completed_at' => now(),
             ])->save();
 
+            $this->markChargeFailed($job);
+
             report($exception);
         }
     }
+
+    private function captureCredits(ConversionJob $job, CreditLedger $creditLedger): void
+    {
+        $charge = $job->creditCharge;
+
+        if ($charge === null) {
+            return;
+        }
+
+        DB::transaction(function () use ($job, $charge, $creditLedger) {
+            // Lock the charge row and verify it is still in the expected state
+            // before spending, so duplicate executions are idempotent.
+            $lockedCharge = ConversionCreditCharge::lockForUpdate()->find($charge->id);
+
+            if ($lockedCharge === null || $lockedCharge->status !== ConversionCreditChargeStatus::Estimated) {
+                return;
+            }
+
+            $creditLedger->spend(
+                user: $job->user,
+                amount: $lockedCharge->estimated_amount,
+                reason: 'conversion_completed',
+                meta: [
+                    'conversion_job_id' => $job->id,
+                    'converter_key' => $job->converter_key,
+                ],
+            );
+
+            $lockedCharge->forceFill([
+                'captured_amount' => $lockedCharge->estimated_amount,
+                'status' => ConversionCreditChargeStatus::Captured,
+            ])->save();
+        });
+    }
+
+    private function markChargeFailed(ConversionJob $job): void
+    {
+        $charge = $job->creditCharge;
+
+        if ($charge === null) {
+            return;
+        }
+
+        $charge->forceFill([
+            'status' => ConversionCreditChargeStatus::Failed,
+        ])->save();
+    }
 }

app/Livewire/Dashboard/DashboardConverter.php

@@ -3,8 +3,11 @@
 namespace App\Livewire\Dashboard;
 
 use App\Actions\Conversions\CreateConversionJobAction;
+use App\Actions\Conversions\EstimateConversionCostAction;
 use App\Actions\Files\StoreUploadedFileAction;
 use App\Enums\ConversionStatus;
+use App\Exceptions\Billing\InsufficientCreditsException;
+use App\Exceptions\Billing\UnsupportedConversionCostException;
 use App\Exceptions\Files\FileStorageException;
 use App\Exceptions\Files\UnsupportedFileFormatException;
 use App\Exceptions\Storage\StorageLimitExceededException;
@@ -60,6 +63,8 @@ class DashboardConverter extends Component
 
     public ?string $convertError = null;
 
+    public ?int $estimatedCreditCost = null;
+
     public function updatedUpload(): void
     {
         $this->storeUpload(app(StoreUploadedFileAction::class), app(FeatureAccessService::class));
@@ -190,6 +195,18 @@ public function selectTargetFormat(string $targetFormat): void
             $this->initializeOptionsFromSchema();
         }
 
+        try {
+            $cost = app(EstimateConversionCostAction::class)->handle(
+                $this->currentFile,
+                $converter,
+                $this->options,
+            );
+            $this->estimatedCreditCost = $cost->amount;
+        } catch (UnsupportedConversionCostException|\InvalidArgumentException) {
+            // Known pricing failures — unsupported pair or misconfigured rule.
+            $this->estimatedCreditCost = null;
+        }
+
         $this->step = 'settings';
     }
 
@@ -244,6 +261,12 @@ public function convert(): void
             $this->convertError = 'This conversion is not supported. Please choose a different format.';
             $this->step = 'format';
 
+            return;
+        } catch (InsufficientCreditsException $e) {
+            $this->convertError = 'Not enough credits. This conversion requires '
+                .($this->estimatedCreditCost ?? '?')
+                .' credit(s). Please top up your balance.';
+
             return;
         } catch (Throwable) {
             $this->convertError = 'Something went wrong. Please try again.';
@@ -338,6 +361,7 @@ private function resetTargetSelection(): void
         $this->optionsSchema = [];
         $this->options = [];
         $this->optionsByTarget = [];
+        $this->estimatedCreditCost = null;
     }
 
     public function getCurrentJobProperty(): ?ConversionJob