Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
77.55% covered (warning)
77.55%
38 / 49
25.00% covered (danger)
25.00%
1 / 4
CRAP
0.00% covered (danger)
0.00%
0 / 1
SendgridDispatcher
77.55% covered (warning)
77.55%
38 / 49
25.00% covered (danger)
25.00%
1 / 4
16.22
0.00% covered (danger)
0.00%
0 / 1
 send
30.00% covered (danger)
30.00%
3 / 10
0.00% covered (danger)
0.00%
0 / 1
6.09
 isAllowed
100.00% covered (success)
100.00%
10 / 10
100.00% covered (success)
100.00%
1 / 1
4
 allowedCompanyIds
83.33% covered (warning)
83.33%
5 / 6
0.00% covered (danger)
0.00%
0 / 1
2.02
 logGated
86.96% covered (warning)
86.96%
20 / 23
0.00% covered (danger)
0.00%
0 / 1
5.06
1<?php
2
3namespace App\Services;
4
5use App\Models\TblCompanies;
6use App\Models\TblSendgridOutboundLog;
7use Illuminate\Support\Facades\Log;
8use SendGrid\Mail\Mail;
9use SendGrid\Response;
10use Throwable;
11
12/**
13 * FIRE-1930 — single choke-point for every SendGrid send in Titan.
14 *
15 * Two responsibilities in one place:
16 *   1. Consult the per-region / per-bucket kill switch stored on
17 *      tbl_companies (four *_active columns added by the FIRE-1930
18 *      migration) and skip the send when the target region is off.
19 *   2. Instantiate the SendGrid client, call ->send(), and route the
20 *      response through SendgridLogger — the same three lines that used
21 *      to be copy-pasted at ~30 sites across the codebase.
22 *
23 * Return value:
24 *   - Response  → send happened (statusCode() tells success/failure).
25 *   - null      → send was gated by the kill switch. Callers that do
26 *                 post-send bookkeeping (setting x_status='Processing',
27 *                 writing tbl_sendgrid_webhook rows, etc.) MUST treat
28 *                 null the same as a failed send and skip that work.
29 *
30 * A bucket is "on" only when the company's flag is exactly 1 — NULL,
31 * a missing company or a missing companyId all block (see isAllowed).
32 *
33 * The dispatcher never throws for a gated send — that would defeat the
34 * point of a kill switch. It DOES rethrow SendGrid SDK exceptions so
35 * the existing try/catch structures at each caller keep working.
36 */
37class SendgridDispatcher
38{
39    public const BUCKET_FOLLOW_UP = 'follow_up_notifications_active';
40
41    public const BUCKET_APPROVAL = 'approval_notifications_active';
42
43    public const BUCKET_COMMERCIAL = 'commercial_notifications_active';
44
45    public const BUCKET_CLIENT = 'client_emails_active';
46
47    /**
48     * All buckets the switch can gate. Keep in sync with the migration
49     * columns; used by the controller to iterate flags.
50     */
51    public const ALL_BUCKETS = [
52        self::BUCKET_FOLLOW_UP,
53        self::BUCKET_APPROVAL,
54        self::BUCKET_COMMERCIAL,
55        self::BUCKET_CLIENT,
56    ];
57
58    public static function send(
59        Mail $email,
60        string $bucket = self::BUCKET_COMMERCIAL,
61        ?int $companyId = null,
62        ?string $functionName = null,
63    ): ?Response {
64        if (! self::isAllowed($bucket, $companyId)) {
65            self::logGated($email, $bucket, $companyId, $functionName);
66
67            return null;
68        }
69
70        $sendgrid = new \SendGrid(config('services.sendgrid.api_key'));
71
72        try {
73            $response = $sendgrid->send($email);
74            SendgridLogger::log($email, $response, $functionName);
75
76            return $response;
77        } catch (Throwable $e) {
78            SendgridLogger::logException($email, $e, $functionName);
79            throw $e;
80        }
81    }
82
83    /**
84     * True only when the bucket is explicitly enabled (= 1) for the
85     * target company.
86     *
87     * Fail-closed: a NULL flag, a missing companyId, an unmapped company
88     * or an unknown bucket all mean "not enabled" and the send is
89     * skipped. The original fail-open rule let every company whose
90     * column was NULL on prod keep sending while the settings page
91     * showed the switch as off.
92     */
93    public static function isAllowed(string $bucket, ?int $companyId): bool
94    {
95        if (! in_array($bucket, self::ALL_BUCKETS, true)) {
96            Log::channel('email_log')->warning('SendgridDispatcher: unknown bucket, blocking send', [
97                'bucket' => $bucket,
98                'company_id' => $companyId,
99            ]);
100
101            return false;
102        }
103
104        if ($companyId === null) {
105            return false;
106        }
107
108        $flag = TblCompanies::where('company_id', $companyId)->value($bucket);
109
110        // value() returns null both for a NULL column and for a company
111        // row that doesn't exist — neither counts as enabled.
112        return $flag !== null && (int) $flag === 1;
113    }
114
115    /**
116     * Company ids that have the bucket enabled. For digests that mix
117     * several companies in one email (G3W / Cofrai reminders), where the
118     * gate has to filter rows rather than skip a single send.
119     *
120     * @return int[]
121     */
122    public static function allowedCompanyIds(string $bucket): array
123    {
124        if (! in_array($bucket, self::ALL_BUCKETS, true)) {
125            return [];
126        }
127
128        return TblCompanies::query()->where($bucket, 1)
129            ->pluck('company_id')
130            ->map(fn ($id) => (int) $id)
131            ->all();
132    }
133
134    private static function logGated(Mail $email, string $bucket, ?int $companyId, ?string $functionName): void
135    {
136        try {
137            $region = $companyId !== null
138                ? TblCompanies::where('company_id', $companyId)->value('region')
139                : null;
140
141            TblSendgridOutboundLog::create([
142                'function_name' => 'GATED:'.$bucket.($functionName !== null ? ' ('.$functionName.')' : ''),
143                'x_message_id' => null,
144                'request_json' => (array) json_decode(json_encode($email->jsonSerialize()), true),
145                'response_json' => [
146                    'gated' => true,
147                    'bucket' => $bucket,
148                    'company_id' => $companyId,
149                    'region' => $region,
150                ],
151            ]);
152
153            Log::channel('email_log')->warning('SendgridDispatcher: send gated by region kill switch', [
154                'bucket' => $bucket,
155                'company_id' => $companyId,
156                'region' => $region,
157                'function_name' => $functionName,
158            ]);
159        } catch (Throwable $e) {
160            // Never let logging failures prevent the gate itself from
161            // working — the gate is what protects the customer. A
162            // failed log write is a smaller problem than a rogue send.
163            try {
164                Log::channel('email_log')->warning('SendgridDispatcher: gated-send logging failed: '.$e->getMessage());
165            } catch (Throwable) {
166                // truly nothing we can do
167            }
168        }
169    }
170}