feat(messaging): suite-channel email/SMS and entitlement sync

Prefer platform suite messaging (channel=suite) for attendee email, fall back
to Bird integrations; sync suite plan entitlements on subscribe/renew.

app/Services/Billing/PlatformEmailClient.php

@@ -4,16 +4,28 @@ namespace App\Services\Billing;
 
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
 
+/**
+ * Platform suite email (zero-config): POST /api/smtp/messages/send with channel=suite.
+ * No Bird API key or smtp_service_id required when platform messaging is enabled.
+ */
 class PlatformEmailClient
 {
     private ?string $lastError = null;
 
+    private ?string $lastErrorCode = null;
+
     public function lastError(): ?string
     {
         return $this->lastError;
     }
 
+    public function lastErrorCode(): ?string
+    {
+        return $this->lastErrorCode;
+    }
+
     private function base(): string
     {
         return rtrim((string) config('smtp.platform_api_url', 'https://ladill.com/api/smtp'), '/');
@@ -24,9 +36,30 @@ class PlatformEmailClient
         return (string) config('smtp.platform_api_key', '');
     }
 
-    public function send(string $ownerPublicId, string $to, string $subject, string $html, ?string $text = null): bool
+    public function isConfigured(): bool
     {
+        return $this->token() !== '';
+    }
+
+    public function messagingSettingsUrl(): string
+    {
+        return (string) config(
+            'smtp.messaging_settings_url',
+            'https://account.ladill.com/account/settings/messaging?reason=messaging_mailbox_required&from=suite',
+        );
+    }
+
+    public function send(
+        string $ownerPublicId,
+        string $to,
+        string $subject,
+        string $html,
+        ?string $text = null,
+        ?string $fromName = null,
+        ?string $idempotencyKey = null,
+    ): bool {
         $this->lastError = null;
+        $this->lastErrorCode = null;
 
         if (! $this->isConfigured()) {
             $this->lastError = 'Outbound email is not configured on this Events instance.';
@@ -34,28 +67,41 @@ class PlatformEmailClient
             return false;
         }
 
+        $key = $idempotencyKey ?: ('events-email-'.Str::uuid());
+
         try {
-            $res = Http::withToken($this->token())->acceptJson()->timeout(30)
+            $res = Http::withToken($this->token())
+                ->withHeaders(['Idempotency-Key' => $key])
+                ->acceptJson()
+                ->timeout(30)
                 ->post($this->base().'/messages/send', array_filter([
                     'user' => $ownerPublicId,
-                    'from' => config('smtp.from'),
-                    'from_name' => config('smtp.from_name'),
+                    'channel' => 'suite',
+                    'from_name' => $fromName ?? config('smtp.from_name'),
                     'to' => $to,
                     'subject' => $subject,
                     'html' => $html,
                     'text' => $text,
-                ]));
+                    'reference' => $key,
+                ], static fn ($v) => $v !== null && $v !== ''));
 
             if ($res->status() === 402) {
-                $this->lastError = (string) ($res->json('error') ?: 'Insufficient Bird email credits. Add funds in Billing and try again.');
-                Log::warning('Platform email send: insufficient balance', ['user' => $ownerPublicId]);
+                $this->lastErrorCode = (string) ($res->json('error') ?: 'allowance_exceeded');
+                $this->lastError = (string) ($res->json('error') ?: 'Email allowance exceeded. Upgrade your plan or top up your wallet.');
+                Log::warning('Events suite email: allowance/balance', ['user' => $ownerPublicId, 'body' => $res->body()]);
 
                 return false;
             }
 
             if ($res->failed()) {
-                $this->lastError = (string) ($res->json('error') ?: 'The email could not be sent. Please try again.');
-                Log::warning('Platform email send failed', ['status' => $res->status(), 'body' => $res->body()]);
+                $code = (string) ($res->json('error') ?: 'send_failed');
+                $this->lastErrorCode = $code;
+                if ($code === 'messaging_mailbox_required') {
+                    $this->lastError = 'Set a Ladill mailbox for suite email in Account → Messaging settings: '.$this->messagingSettingsUrl();
+                } else {
+                    $this->lastError = (string) ($res->json('error') ?: 'The email could not be sent. Please try again.');
+                }
+                Log::warning('Events suite email failed', ['status' => $res->status(), 'body' => $res->body()]);
 
                 return false;
             }
@@ -63,14 +109,9 @@ class PlatformEmailClient
             return (bool) ($res->json('success') ?? true);
         } catch (\Throwable $e) {
             $this->lastError = 'The email could not be sent. Please try again.';
-            Log::warning('Platform email send error', ['error' => $e->getMessage()]);
+            Log::warning('Events suite email error', ['error' => $e->getMessage()]);
 
             return false;
         }
     }
-
-    public function isConfigured(): bool
-    {
-        return $this->token() !== '';
-    }
 }