geschenkgutscheine implementiert ("Paket verschenken"). Neuer Upload-Provider: Sparkbooth.

app/Services/Checkout/CheckoutWebhookService.php

@@ -7,6 +7,7 @@ use App\Models\Package;
 use App\Models\Tenant;
 use App\Models\TenantPackage;
 use App\Services\Coupons\CouponRedemptionService;
+use App\Services\GiftVouchers\GiftVoucherService;
 use App\Services\Paddle\PaddleSubscriptionService;
 use Carbon\Carbon;
 use Illuminate\Support\Arr;
@@ -21,6 +22,7 @@ class CheckoutWebhookService
         private readonly CheckoutAssignmentService $assignment,
         private readonly PaddleSubscriptionService $paddleSubscriptions,
         private readonly CouponRedemptionService $couponRedemptions,
+        private readonly GiftVoucherService $giftVouchers,
     ) {}
 
     public function handleStripeEvent(array $event): bool
@@ -93,6 +95,16 @@ class CheckoutWebhookService
             return $this->handlePaddleSubscriptionEvent($eventType, $data);
         }
 
+        if ($this->isGiftVoucherEvent($data)) {
+            if ($eventType === 'transaction.completed') {
+                $this->giftVouchers->issueFromPaddle($data);
+
+                return true;
+            }
+
+            return in_array($eventType, ['transaction.processing', 'transaction.created', 'transaction.failed', 'transaction.cancelled'], true);
+        }
+
         $session = $this->locatePaddleSession($data);
 
         if (! $session) {
@@ -429,6 +441,25 @@ class CheckoutWebhookService
         return null;
     }
 
+    protected function isGiftVoucherEvent(array $data): bool
+    {
+        $metadata = $data['metadata'] ?? [];
+
+        $type = is_array($metadata) ? ($metadata['type'] ?? $metadata['kind'] ?? $metadata['category'] ?? null) : null;
+
+        if ($type && in_array(strtolower($type), ['gift_card', 'gift_voucher'], true)) {
+            return true;
+        }
+
+        $priceId = $data['price_id'] ?? Arr::get($metadata, 'paddle_price_id');
+        $tiers = collect(config('gift-vouchers.tiers', []))
+            ->pluck('paddle_price_id')
+            ->filter()
+            ->all();
+
+        return $priceId && in_array($priceId, $tiers, true);
+    }
+
     protected function locatePaddleSession(array $data): ?CheckoutSession
     {
         $metadata = $data['metadata'] ?? [];

app/Services/Coupons/CouponRedemptionService.php

@@ -4,10 +4,13 @@ namespace App\Services\Coupons;
 
 use App\Models\CheckoutSession;
 use App\Models\CouponRedemption;
+use App\Services\GiftVouchers\GiftVoucherService;
 use Illuminate\Support\Arr;
 
 class CouponRedemptionService
 {
+    public function __construct(private readonly GiftVoucherService $giftVouchers) {}
+
     public function recordSuccess(CheckoutSession $session, array $payload = []): void
     {
         if (! $session->coupon_id) {
@@ -41,6 +44,8 @@ class CouponRedemptionService
         );
 
         $session->coupon?->increment('redemptions_count');
+
+        $this->giftVouchers->markRedeemed($session->coupon, $transactionId);
     }
 
     public function recordFailure(CheckoutSession $session, string $reason): void

app/Services/GiftVouchers/GiftVoucherCheckoutService.php

@@ -0,0 +1,100 @@
+<?php
+
+namespace App\Services\GiftVouchers;
+
+use App\Services\Paddle\PaddleClient;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\App;
+use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
+
+class GiftVoucherCheckoutService
+{
+    public function __construct(private readonly PaddleClient $client) {}
+
+    /**
+     * @return array<int, array{key:string,label:string,amount:float,currency:string,paddle_price_id?:string|null,can_checkout:bool}>
+     */
+    public function tiers(): array
+    {
+        return collect(config('gift-vouchers.tiers', []))
+            ->map(function (array $tier): array {
+                $currency = Str::upper($tier['currency'] ?? 'EUR');
+                $priceId = $tier['paddle_price_id'] ?? null;
+
+                return [
+                    'key' => $tier['key'],
+                    'label' => $tier['label'],
+                    'amount' => (float) $tier['amount'],
+                    'currency' => $currency,
+                    'paddle_price_id' => $priceId,
+                    'can_checkout' => ! empty($priceId),
+                ];
+            })
+            ->values()
+            ->all();
+    }
+
+    /**
+     * @param  array{tier_key:string,purchaser_email:string,recipient_email?:string|null,recipient_name?:string|null,message?:string|null,success_url?:string|null,return_url?:string|null}  $data
+     * @return array{checkout_url:?string,expires_at:?string,id:?string}
+     */
+    public function create(array $data): array
+    {
+        $tier = $this->findTier($data['tier_key']);
+
+        if (! $tier || empty($tier['paddle_price_id'])) {
+            throw ValidationException::withMessages([
+                'tier_key' => __('Gift voucher is not available right now.'),
+            ]);
+        }
+
+        $payload = [
+            'items' => [
+                [
+                    'price_id' => $tier['paddle_price_id'],
+                    'quantity' => 1,
+                ],
+            ],
+            'customer_email' => $data['purchaser_email'],
+            'metadata' => array_filter([
+                'type' => 'gift_voucher',
+                'tier_key' => $tier['key'],
+                'purchaser_email' => $data['purchaser_email'],
+                'recipient_email' => $data['recipient_email'] ?? null,
+                'recipient_name' => $data['recipient_name'] ?? null,
+                'message' => $data['message'] ?? null,
+                'app_locale' => App::getLocale(),
+            ]),
+            'success_url' => $data['success_url'] ?? route('marketing.success', ['locale' => App::getLocale(), 'type' => 'gift']),
+            'cancel_url' => $data['return_url'] ?? route('packages', ['locale' => App::getLocale()]),
+        ];
+
+        $response = $this->client->post('/checkout/links', $payload);
+
+        return [
+            'checkout_url' => Arr::get($response, 'data.url') ?? Arr::get($response, 'url'),
+            'expires_at' => Arr::get($response, 'data.expires_at') ?? Arr::get($response, 'expires_at'),
+            'id' => Arr::get($response, 'data.id') ?? Arr::get($response, 'id'),
+        ];
+    }
+
+    /**
+     * @return array<string, mixed>|null
+     */
+    protected function findTier(string $key): ?array
+    {
+        $tiers = collect(config('gift-vouchers.tiers', []))
+            ->keyBy('key');
+
+        $tier = $tiers->get($key);
+
+        if (! $tier) {
+            return null;
+        }
+
+        $tier['currency'] = Str::upper($tier['currency'] ?? 'EUR');
+
+        return $tier;
+    }
+}

app/Services/GiftVouchers/GiftVoucherService.php

@@ -0,0 +1,215 @@
+<?php
+
+namespace App\Services\GiftVouchers;
+
+use App\Enums\CouponStatus;
+use App\Enums\CouponType;
+use App\Jobs\SyncCouponToPaddle;
+use App\Models\Coupon;
+use App\Models\GiftVoucher;
+use App\Models\Package;
+use App\Services\Paddle\PaddleTransactionService;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
+
+class GiftVoucherService
+{
+    public function __construct(private readonly PaddleTransactionService $transactions) {}
+
+    /**
+     * Create a voucher from a Paddle transaction payload.
+     */
+    public function issueFromPaddle(array $payload): GiftVoucher
+    {
+        $metadata = $payload['metadata'] ?? [];
+        $priceId = $this->resolvePriceId($payload);
+        $amount = $this->resolveAmount($payload);
+        $currency = Str::upper($this->resolveCurrency($payload));
+
+        $expiresAt = now()->addYears((int) config('gift-vouchers.default_valid_years', 5));
+
+        $voucher = GiftVoucher::query()->updateOrCreate(
+            [
+                'paddle_transaction_id' => $payload['id'] ?? null,
+            ],
+            [
+                'code' => $metadata['gift_code'] ?? $this->generateCode(),
+                'amount' => $amount,
+                'currency' => $currency,
+                'status' => GiftVoucher::STATUS_ISSUED,
+                'purchaser_email' => $metadata['purchaser_email'] ?? Arr::get($payload, 'customer.email'),
+                'recipient_email' => $metadata['recipient_email'] ?? null,
+                'recipient_name' => $metadata['recipient_name'] ?? null,
+                'message' => $metadata['message'] ?? null,
+                'paddle_checkout_id' => $payload['checkout_id'] ?? Arr::get($payload, 'details.checkout_id'),
+                'paddle_price_id' => $priceId,
+                'metadata' => $metadata,
+                'expires_at' => $expiresAt,
+                'refunded_at' => null,
+                'redeemed_at' => null,
+            ]
+        );
+
+        if (! $voucher->coupon_id) {
+            $coupon = $this->createCouponForVoucher($voucher);
+            $voucher->forceFill(['coupon_id' => $coupon->id])->save();
+            SyncCouponToPaddle::dispatch($coupon);
+        }
+
+        return $voucher;
+    }
+
+    public function markRedeemed(?Coupon $coupon, ?string $transactionId = null): void
+    {
+        if (! $coupon?->giftVoucher) {
+            return;
+        }
+
+        $voucher = $coupon->giftVoucher;
+
+        if ($voucher->isRedeemed()) {
+            return;
+        }
+
+        $voucher->forceFill([
+            'status' => GiftVoucher::STATUS_REDEEMED,
+            'redeemed_at' => now(),
+            'metadata' => array_merge($voucher->metadata ?? [], array_filter([
+                'redeemed_transaction_id' => $transactionId,
+            ])),
+        ])->save();
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function refund(GiftVoucher $voucher, ?string $reason = null): array
+    {
+        if (! $voucher->canBeRefunded()) {
+            throw ValidationException::withMessages([
+                'voucher' => __('Voucher cannot be refunded after redemption or refund.'),
+            ]);
+        }
+
+        if (! $voucher->paddle_transaction_id) {
+            throw ValidationException::withMessages([
+                'voucher' => __('Missing Paddle transaction for refund.'),
+            ]);
+        }
+
+        $response = $this->transactions->refund($voucher->paddle_transaction_id, array_filter([
+            'reason' => $reason,
+        ]));
+
+        $voucher->forceFill([
+            'status' => GiftVoucher::STATUS_REFUNDED,
+            'refunded_at' => now(),
+        ])->save();
+
+        if ($voucher->coupon) {
+            $voucher->coupon->forceFill([
+                'status' => CouponStatus::ARCHIVED,
+                'enabled_for_checkout' => false,
+            ])->save();
+        }
+
+        return $response;
+    }
+
+    protected function createCouponForVoucher(GiftVoucher $voucher): Coupon
+    {
+        $packages = $this->eligiblePackages();
+
+        $coupon = Coupon::create([
+            'name' => 'Gutschein '.$voucher->code,
+            'code' => $voucher->code,
+            'type' => CouponType::FLAT,
+            'amount' => $voucher->amount,
+            'currency' => $voucher->currency,
+            'status' => CouponStatus::ACTIVE,
+            'enabled_for_checkout' => true,
+            'is_stackable' => false,
+            'usage_limit' => 1,
+            'per_customer_limit' => 1,
+            'auto_apply' => false,
+            'description' => 'Geschenkgutschein '.number_format((float) $voucher->amount, 2).' '.$voucher->currency.' für Endkunden-Pakete.',
+            'starts_at' => now(),
+            'ends_at' => $voucher->expires_at,
+        ]);
+
+        if ($packages->isNotEmpty()) {
+            $coupon->packages()->sync($packages->pluck('id'));
+        }
+
+        return $coupon;
+    }
+
+    protected function eligiblePackages(): Collection
+    {
+        $types = (array) config('gift-vouchers.package_types', ['endcustomer']);
+
+        return Package::query()
+            ->whereIn('type', $types)
+            ->whereNotNull('paddle_price_id')
+            ->get(['id']);
+    }
+
+    protected function resolvePriceId(array $payload): ?string
+    {
+        $metadata = $payload['metadata'] ?? [];
+
+        if (is_array($metadata) && ! empty($metadata['paddle_price_id'])) {
+            return $metadata['paddle_price_id'];
+        }
+
+        $items = Arr::get($payload, 'items', Arr::get($payload, 'details.items', []));
+        if (is_array($items) && isset($items[0]['price_id'])) {
+            return $items[0]['price_id'];
+        }
+
+        return $payload['price_id'] ?? null;
+    }
+
+    protected function resolveAmount(array $payload): float
+    {
+        $tiers = Collection::make(config('gift-vouchers.tiers', []))
+            ->keyBy(fn ($tier) => $tier['paddle_price_id'] ?? null);
+
+        $priceId = $this->resolvePriceId($payload);
+        if ($priceId && $tiers->has($priceId)) {
+            return (float) $tiers->get($priceId)['amount'];
+        }
+
+        $amount = Arr::get($payload, 'totals.grand_total.amount')
+            ?? Arr::get($payload, 'totals.grand_total')
+            ?? Arr::get($payload, 'details.totals.grand_total.amount')
+            ?? Arr::get($payload, 'details.totals.grand_total')
+            ?? Arr::get($payload, 'amount');
+
+        if (is_numeric($amount)) {
+            $value = (float) $amount;
+
+            return $value >= 100 ? round($value / 100, 2) : round($value, 2);
+        }
+
+        Log::warning('[GiftVoucher] Unable to resolve amount, defaulting to 0', ['payload' => $payload]);
+
+        return 0.0;
+    }
+
+    protected function resolveCurrency(array $payload): string
+    {
+        return $payload['currency_code']
+            ?? Arr::get($payload, 'details.totals.currency_code')
+            ?? Arr::get($payload, 'currency')
+            ?? 'EUR';
+    }
+
+    protected function generateCode(): string
+    {
+        return 'GIFT-'.Str::upper(Str::random(8));
+    }
+}

app/Services/Paddle/PaddleCatalogService.php

@@ -51,7 +51,7 @@ class PaddleCatalogService
      */
     public function createPrice(Package $package, string $productId, array $overrides = []): array
     {
-        $payload = $this->buildPricePayload($package, $productId, $overrides);
+        $payload = $this->buildPricePayload($package, $productId, $overrides, includeProduct: true);
 
         return $this->extractEntity($this->client->post('/prices', $payload));
     }
@@ -61,7 +61,12 @@ class PaddleCatalogService
      */
     public function updatePrice(string $priceId, Package $package, array $overrides = []): array
     {
-        $payload = $this->buildPricePayload($package, $overrides['product_id'] ?? $package->paddle_product_id, $overrides);
+        $payload = $this->buildPricePayload(
+            $package,
+            $overrides['product_id'] ?? $package->paddle_product_id,
+            $overrides,
+            includeProduct: false
+        );
 
         return $this->extractEntity($this->client->patch("/prices/{$priceId}", $payload));
     }
@@ -85,19 +90,24 @@ class PaddleCatalogService
     /**
      * @return array<string, mixed>
      */
-    public function buildPricePayload(Package $package, string $productId, array $overrides = []): array
+    public function buildPricePayload(Package $package, string $productId, array $overrides = [], bool $includeProduct = true): array
     {
         $unitPrice = $overrides['unit_price'] ?? [
             'amount' => (string) $this->priceToMinorUnits($package->price),
             'currency_code' => Str::upper((string) ($package->currency ?? 'EUR')),
         ];
 
-        $payload = array_merge([
-            'product_id' => $productId,
+        $base = [
             'description' => $this->resolvePriceDescription($package, $overrides),
             'unit_price' => $unitPrice,
             'custom_data' => $this->buildCustomData($package, $overrides['custom_data'] ?? []),
-        ], Arr::except($overrides, ['unit_price', 'description', 'custom_data']));
+        ];
+
+        if ($includeProduct) {
+            $base['product_id'] = $productId;
+        }
+
+        $payload = array_merge($base, Arr::except($overrides, ['unit_price', 'description', 'custom_data', 'product_id']));
 
         return $this->cleanPayload($payload);
     }

app/Services/Paddle/PaddleGiftVoucherCatalogService.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace App\Services\Paddle;
+
+use Illuminate\Support\Arr;
+use Illuminate\Support\Str;
+
+class PaddleGiftVoucherCatalogService
+{
+    public function __construct(private readonly PaddleClient $client) {}
+
+    /**
+     * @param  array{key:string,label:string,amount:float,currency?:string,paddle_product_id?:string|null,paddle_price_id?:string|null}  $tier
+     * @return array{product_id:string,price_id:string}
+     */
+    public function ensureTier(array $tier): array
+    {
+        $product = $tier['paddle_product_id'] ?? null;
+        $price = $tier['paddle_price_id'] ?? null;
+
+        if (! $product) {
+            $product = $this->createProduct($tier)['id'];
+        }
+
+        if (! $price) {
+            $price = $this->createPrice($tier, $product)['id'];
+        }
+
+        return [
+            'product_id' => $product,
+            'price_id' => $price,
+        ];
+    }
+
+    /**
+     * @param  array{key:string,label:string,amount:float,currency?:string}  $tier
+     * @return array<string, mixed>
+     */
+    public function createProduct(array $tier): array
+    {
+        $payload = [
+            'name' => $tier['label'],
+            'description' => sprintf('Geschenkgutschein im Wert von %.2f %s für Fotospiel Pakete.', $tier['amount'], $this->currency($tier)),
+            'type' => 'standard',
+            'tax_category' => 'standard',
+            'custom_data' => [
+                'kind' => 'gift_voucher',
+                'tier_key' => $tier['key'],
+                'amount' => $tier['amount'],
+                'currency' => $this->currency($tier),
+            ],
+        ];
+
+        $response = $this->client->post('/products', $payload);
+
+        return Arr::get($response, 'data', $response);
+    }
+
+    /**
+     * @param  array{key:string,label:string,amount:float,currency?:string}  $tier
+     * @return array<string, mixed>
+     */
+    public function createPrice(array $tier, string $productId): array
+    {
+        $payload = [
+            'product_id' => $productId,
+            'description' => sprintf('Geschenkgutschein %.2f %s', $tier['amount'], $this->currency($tier)),
+            'unit_price' => [
+                'amount' => (string) $this->toMinorUnits($tier['amount']),
+                'currency_code' => $this->currency($tier),
+            ],
+            'custom_data' => [
+                'kind' => 'gift_voucher',
+                'tier_key' => $tier['key'],
+            ],
+        ];
+
+        $response = $this->client->post('/prices', $payload);
+
+        return Arr::get($response, 'data', $response);
+    }
+
+    protected function currency(array $tier): string
+    {
+        return Str::upper($tier['currency'] ?? 'EUR');
+    }
+
+    protected function toMinorUnits(float $amount): int
+    {
+        return (int) round($amount * 100);
+    }
+}

app/Services/Photobooth/Exceptions/SparkboothUploadException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Services\Photobooth\Exceptions;
+
+use RuntimeException;
+
+class SparkboothUploadException extends RuntimeException
+{
+    public function __construct(
+        public readonly string $reason,
+        string $message,
+        public readonly ?int $statusCode = null
+    ) {
+        parent::__construct($message);
+    }
+}

app/Services/Photobooth/PhotoboothIngestService.php

@@ -33,7 +33,7 @@ class PhotoboothIngestService
         $this->hasPathColumn = Schema::hasColumn('photos', 'path');
     }
 
-    public function ingest(Event $event, ?int $maxFiles = null): array
+    public function ingest(Event $event, ?int $maxFiles = null, string $ingestSource = Photo::SOURCE_PHOTOBOOTH): array
     {
         $tenant = $event->tenant;
 
@@ -90,7 +90,7 @@ class PhotoboothIngestService
             }
 
             try {
-                $result = $this->importFile($event, $eventPackage, $disk, $importDisk, $file);
+                $result = $this->importFile($event, $eventPackage, $disk, $importDisk, $file, $ingestSource);
                 if ($result) {
                     $processed++;
                     Storage::disk($importDisk)->delete($file);
@@ -116,6 +116,7 @@ class PhotoboothIngestService
         string $destinationDisk,
         string $importDisk,
         string $file,
+        string $ingestSource,
     ): bool {
         $stream = Storage::disk($importDisk)->readStream($file);
 
@@ -191,8 +192,8 @@ class PhotoboothIngestService
                 'file_path' => $watermarkedPath,
                 'thumbnail_path' => $watermarkedThumb,
                 'status' => 'pending',
-                'guest_name' => Photo::SOURCE_PHOTOBOOTH,
-                'ingest_source' => Photo::SOURCE_PHOTOBOOTH,
+                'guest_name' => $ingestSource,
+                'ingest_source' => $ingestSource,
                 'ip_address' => null,
             ];
 

app/Services/Photobooth/PhotoboothProvisioner.php

@@ -124,6 +124,79 @@ class PhotoboothProvisioner
         });
     }
 
+    public function enableSparkbooth(Event $event, ?PhotoboothSetting $settings = null): Event
+    {
+        $settings ??= PhotoboothSetting::current();
+        $event->loadMissing('tenant');
+
+        return DB::transaction(function () use ($event, $settings) {
+            $username = $this->generateUniqueUsername($event, $settings);
+            $password = $this->credentialGenerator->generatePassword();
+            $path = $this->buildPath($event);
+            $expiresAt = $this->resolveExpiry($event, $settings);
+
+            $event->forceFill([
+                'photobooth_enabled' => true,
+                'photobooth_mode' => 'sparkbooth',
+                'sparkbooth_username' => $username,
+                'sparkbooth_password' => $password,
+                'sparkbooth_expires_at' => $expiresAt,
+                'sparkbooth_status' => 'active',
+                'photobooth_path' => $path,
+                'sparkbooth_uploads_last_24h' => 0,
+            ])->save();
+
+            return tap($event->refresh(), function (Event $refreshed) use ($password) {
+                $refreshed->setAttribute('plain_sparkbooth_password', $password);
+            });
+        });
+    }
+
+    public function rotateSparkbooth(Event $event, ?PhotoboothSetting $settings = null): Event
+    {
+        $settings ??= PhotoboothSetting::current();
+
+        if ($event->photobooth_mode !== 'sparkbooth' || ! $event->sparkbooth_username) {
+            return $this->enableSparkbooth($event, $settings);
+        }
+
+        return DB::transaction(function () use ($event, $settings) {
+            $password = $this->credentialGenerator->generatePassword();
+            $expiresAt = $this->resolveExpiry($event, $settings);
+
+            $event->forceFill([
+                'sparkbooth_password' => $password,
+                'sparkbooth_expires_at' => $expiresAt,
+                'sparkbooth_status' => 'active',
+                'photobooth_enabled' => true,
+                'photobooth_mode' => 'sparkbooth',
+            ])->save();
+
+            return tap($event->refresh(), function (Event $refreshed) use ($password) {
+                $refreshed->setAttribute('plain_sparkbooth_password', $password);
+            });
+        });
+    }
+
+    public function disableSparkbooth(Event $event): Event
+    {
+        return DB::transaction(function () use ($event) {
+            $event->forceFill([
+                'photobooth_enabled' => false,
+                'photobooth_mode' => 'ftp',
+                'sparkbooth_username' => null,
+                'sparkbooth_password' => null,
+                'sparkbooth_expires_at' => null,
+                'sparkbooth_status' => 'inactive',
+                'sparkbooth_last_upload_at' => null,
+                'sparkbooth_uploads_last_24h' => 0,
+                'sparkbooth_uploads_total' => 0,
+            ])->save();
+
+            return $event->refresh();
+        });
+    }
+
     protected function resolveExpiry(Event $event, PhotoboothSetting $settings): CarbonInterface
     {
         $eventEnd = $event->date ? Carbon::parse($event->date) : now();
@@ -143,6 +216,7 @@ class PhotoboothProvisioner
 
             $exists = Event::query()
                 ->where('photobooth_username', $username)
+                ->orWhere('sparkbooth_username', $username)
                 ->whereKeyNot($event->getKey())
                 ->exists();
 

app/Services/Photobooth/SparkboothUploadService.php

@@ -0,0 +1,138 @@
+<?php
+
+namespace App\Services\Photobooth;
+
+use App\Models\Event;
+use App\Models\Photo;
+use App\Services\Photobooth\Exceptions\SparkboothUploadException;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\RateLimiter;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+
+class SparkboothUploadService
+{
+    public function __construct(private readonly PhotoboothIngestService $ingestService) {}
+
+    /**
+     * @return array{event: Event, processed: int, skipped: int}
+     *
+     * @throws SparkboothUploadException
+     */
+    public function handleUpload(UploadedFile $media, ?string $username, ?string $password): array
+    {
+        $event = $this->authenticate($username, $password);
+
+        $this->enforceExpiry($event);
+        $this->enforceRateLimit($event);
+        $this->assertValidFile($media);
+
+        $importDisk = config('photobooth.import.disk', 'photobooth');
+        $basePath = ltrim((string) ($event->photobooth_path ?: $this->buildPath($event)), '/');
+        $extension = strtolower($media->getClientOriginalExtension() ?: $media->extension() ?: 'jpg');
+        $filename = Str::uuid().'.'.$extension;
+        $relativePath = "{$basePath}/{$filename}";
+
+        if (! $event->photobooth_path) {
+            $event->forceFill([
+                'photobooth_path' => $basePath,
+            ])->save();
+        }
+
+        Storage::disk($importDisk)->makeDirectory($basePath);
+        Storage::disk($importDisk)->putFileAs($basePath, $media, $filename);
+
+        $summary = $this->ingestService->ingest($event->fresh(), 1, Photo::SOURCE_SPARKBOOTH);
+
+        if (($summary['processed'] ?? 0) < 1) {
+            throw new SparkboothUploadException('ingest_failed', 'Upload failed, please retry.', 500);
+        }
+
+        $event->forceFill([
+            'sparkbooth_last_upload_at' => now(),
+            'sparkbooth_uploads_last_24h' => ($event->sparkbooth_uploads_last_24h ?? 0) + 1,
+            'sparkbooth_uploads_total' => ($event->sparkbooth_uploads_total ?? 0) + 1,
+        ])->save();
+
+        return [
+            'event' => $event->fresh(),
+            'processed' => $summary['processed'] ?? 0,
+            'skipped' => $summary['skipped'] ?? 0,
+        ];
+    }
+
+    protected function authenticate(?string $username, ?string $password): Event
+    {
+        if (! $username || ! $password) {
+            throw new SparkboothUploadException('missing_credentials', 'Invalid credentials', 401);
+        }
+
+        $normalizedUsername = strtolower(trim($username));
+
+        /** @var Event|null $event */
+        $event = Event::query()
+            ->whereRaw('LOWER(sparkbooth_username) = ?', [$normalizedUsername])
+            ->first();
+
+        if (! $event) {
+            throw new SparkboothUploadException('invalid_credentials', 'Invalid credentials', 401);
+        }
+
+        if ($event->photobooth_mode !== 'sparkbooth' || ! $event->photobooth_enabled) {
+            throw new SparkboothUploadException('disabled', 'Upload not active for this event', 403);
+        }
+
+        if (! hash_equals($event->sparkbooth_password ?? '', $password ?? '')) {
+            throw new SparkboothUploadException('invalid_credentials', 'Invalid credentials', 401);
+        }
+
+        return $event;
+    }
+
+    protected function enforceExpiry(Event $event): void
+    {
+        if ($event->sparkbooth_expires_at && $event->sparkbooth_expires_at->isPast()) {
+            throw new SparkboothUploadException('expired', 'Upload access has expired', 403);
+        }
+    }
+
+    protected function enforceRateLimit(Event $event): void
+    {
+        $limit = (int) (config('photobooth.sparkbooth.rate_limit_per_minute') ?? 0);
+        if ($limit <= 0) {
+            return;
+        }
+
+        $key = sprintf('sparkbooth:event:%d', $event->id);
+
+        if (RateLimiter::tooManyAttempts($key, $limit)) {
+            throw new SparkboothUploadException('rate_limited', 'Upload limit reached; try again in a moment.', 429);
+        }
+
+        RateLimiter::hit($key, 60);
+    }
+
+    protected function assertValidFile(UploadedFile $file): void
+    {
+        $allowed = config('photobooth.sparkbooth.allowed_extensions', ['jpg', 'jpeg', 'png', 'webp']);
+        $extension = strtolower($file->getClientOriginalExtension() ?: $file->extension() ?: '');
+
+        if (! $extension || ! in_array($extension, $allowed, true)) {
+            throw new SparkboothUploadException('invalid_file', 'Unsupported file type', 400);
+        }
+
+        $maxSize = (int) config('photobooth.sparkbooth.max_size_kb', 8192) * 1024;
+        $size = $file->getSize() ?? 0;
+
+        if ($maxSize > 0 && $size > $maxSize) {
+            throw new SparkboothUploadException('file_too_large', 'File too large', 400);
+        }
+    }
+
+    protected function buildPath(Event $event): string
+    {
+        $tenantKey = $event->tenant?->slug ?? $event->tenant_id;
+
+        return trim((string) $tenantKey, '/').'/'.$event->getKey();
+    }
+}