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

docs/ops/photobooth/README.md

@@ -8,13 +8,15 @@ This guide explains how to operate the Photobooth FTP workflow end‑to‑end: p
 2. **Control Service** (REST) provisions FTP accounts. Laravel calls it during enable/rotate/disable actions.
 3. **Photobooth settings** (Filament SuperAdmin) define global port, rate limit, expiry grace, and Control Service connection.
 4. **Ingest command** copies uploaded files into the event’s storage disk, generates thumbnails, records `photos.ingest_source = photobooth`, and respects package quotas.
-5. **Guest PWA filter** consumes `/api/v1/events/{token}/photos?filter=photobooth` to render the “Fotobox” tab.
+5. **Guest PWA filter** consumes `/api/v1/events/{token}/photos?filter=photobooth` to render the “Fotobox” tab. Sparkbooth uploads reuse this filter via `ingest_source = sparkbooth`.
 
 ```
 Photobooth -> FTP (vsftpd) -> photobooth disk
        photobooth:ingest (queue/scheduler)
             -> Event media storage (public disk/S3)
             -> packages_usage, thumbnails, security scan
+
+Sparkbooth -> HTTP upload endpoint -> ingest (direct, no staging disk)
 ```
 
 ## Environment Variables
@@ -40,6 +42,12 @@ PHOTOBOOTH_IMPORT_DISK=photobooth
 PHOTOBOOTH_IMPORT_ROOT=/var/www/storage/app/photobooth
 PHOTOBOOTH_IMPORT_MAX_FILES=50
 PHOTOBOOTH_ALLOWED_EXTENSIONS=jpg,jpeg,png,webp
+
+# Sparkbooth defaults (optional overrides)
+SPARKBOOTH_ALLOWED_EXTENSIONS=jpg,jpeg,png,webp
+SPARKBOOTH_MAX_SIZE_KB=8192
+SPARKBOOTH_RATE_LIMIT_PER_MINUTE=20
+SPARKBOOTH_RESPONSE_FORMAT=json
 ```
 
 ### Filesystem Disk
@@ -72,13 +80,49 @@ You can run the ingest job manually for a specific event:
 php artisan photobooth:ingest --event=123 --max-files=20
 ```
 
+## Sparkbooth HTTP Uploads (Custom Upload)
+
+Use this when Sparkbooth runs in “Custom Upload” mode instead of FTP.
+
+- Endpoint: `POST /api/v1/photobooth/sparkbooth/upload`
+- Auth: per-event username/password (set in Event Admin → Fotobox-Uploads; switch mode to “Sparkbooth”).
+- Body (multipart/form-data): `media` (file or base64), `username`, `password`, optionally `name`, `email`, `message`.
+- Response:
+  - JSON success: `{"status":true,"error":null,"url":null}`
+  - JSON failure: `{"status":false,"error":"Invalid credentials"}`
+  - XML (if `format=xml` or event preference is XML):
+    - Success: `<rsp status="ok" url="..."/>`
+    - Failure: `<rsp status="fail"><err msg="Invalid credentials" /></rsp>`
+- Limits: allowed extensions reuse photobooth defaults; max size `SPARKBOOTH_MAX_SIZE_KB` (default 8 MB); per-event rate limit `SPARKBOOTH_RATE_LIMIT_PER_MINUTE` (fallback to photobooth rate limit).
+- Ingest: writes straight to the event’s hot storage, applies thumbnail/watermark/security scan, sets `photos.ingest_source = sparkbooth`.
+
+Example cURL (JSON response):
+
+```bash
+curl -X POST https://app.example.com/api/v1/photobooth/sparkbooth/upload \
+  -F "media=@/path/to/photo.jpg" \
+  -F "username=PB123" \
+  -F "password=SECRET" \
+  -F "message=Wedding booth"
+```
+
+Example cURL (request XML response):
+
+```bash
+curl -X POST https://app.example.com/api/v1/photobooth/sparkbooth/upload \
+  -F "media=@/path/to/photo.jpg" \
+  -F "username=PB123" \
+  -F "password=SECRET" \
+  -F "format=xml"
+```
+
 ## Tenant Admin UX
 
 Inside the Event Admin PWA, go to **Event → Fotobox-Uploads** to:
 
 1. Enable/disable the Photobooth link.
 2. Rotate credentials (max 10-char usernames, 8-char passwords).
-3. View rate limit + expiry info and copy the ftp:// link.
+3. Switch mode (FTP or Sparkbooth), view rate limit + expiry info, copy ftp:// or POST URL + creds.
 
 ## Guest PWA Filter
 
@@ -100,3 +144,4 @@ Response items contain `ingest_source`, allowing the frontend to toggle photoboo
 5. **Seed default storage target** (e.g., `MediaStorageTarget::create([... 'key' => 'public', ...])`) in non-test environments if not present.
 6. **Verify scheduler** (Horizon or cron) is running commands `photobooth:ingest` and `photobooth:cleanup-expired`.
 7. **Test end-to-end**: enable Photobooth on a staging event, upload a file via FTP, wait for ingest, and confirm it appears under the Fotobox filter in the PWA.
+8. **Test Sparkbooth**: switch event mode to Sparkbooth, copy Upload URL/user/pass, send a sample POST (or real Sparkbooth upload), verify it appears under the Fotobox filter.