feat: handle invoice.payment_failed — set grace period and queue reminders

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/Listeners/HandleStripeWebhook.php

@@ -2,8 +2,10 @@
 
 namespace App\Listeners;
 
+use App\Jobs\SendPaymentFailedReminderJob;
 use App\Models\User;
 use App\Models\UserNotificationPreference;
+use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Cache;
 use Laravel\Cashier\Events\WebhookReceived;
 
@@ -29,6 +31,7 @@ final class HandleStripeWebhook
             'customer.subscription.updated' => $this->bustPlanCache($user),
             'customer.subscription.deleted' => $this->handleSubscriptionDeleted($user),
             'invoice.payment_succeeded' => $this->handlePaymentSucceeded($user),
+            'invoice.payment_failed' => $this->handlePaymentFailed($user),
             default => null,
         };
     }
@@ -51,6 +54,23 @@ final class HandleStripeWebhook
         $this->bustPlanCache($user);
     }
 
+    private function handlePaymentFailed(User $user): void
+    {
+        // Idempotency: only the first failed-payment event in a grace window
+        // transitions state + dispatches reminders. Stripe may fire this event
+        // multiple times per billing cycle (once per failed retry attempt).
+        if ($user->grace_period_until !== null) {
+            return;
+        }
+
+        $user->forceFill(['grace_period_until' => Carbon::now()->addDays(5)])->save();
+
+        SendPaymentFailedReminderJob::dispatch($user->id, 3)->delay(Carbon::now()->addDays(3));
+        SendPaymentFailedReminderJob::dispatch($user->id, 5)->delay(Carbon::now()->addDays(5));
+
+        $this->bustPlanCache($user);
+    }
+
     private function bustPlanCache(User $user): void
     {
         Cache::tags(['plans'])->forget("plan_for_user_{$user->id}");