The best way to control Claude Code, Codex and more from any computer or phone

main
ts 260 lines 8.97 KB
Raw
1 import * as sesv2 from "@distilled.cloud/aws/sesv2";
2 import * as Provider from "alchemy/Provider";
3 import { Resource } from "alchemy/Resource";
4 import * as Effect from "effect/Effect";
5 import type { Providers } from "../Providers.ts";
6 import type { SuppressionListReason } from "./ConfigurationSet.ts";
7
8 /**
9 * Whether an SES account feature is `ENABLED` or `DISABLED`.
10 */
11 export type FeatureStatus = sesv2.FeatureStatus;
12
13 export interface AccountVdmSettings {
14 /**
15 * Whether Virtual Deliverability Manager (VDM) is enabled for the account.
16 */
17 enabled: FeatureStatus;
18 /**
19 * Whether the VDM dashboard's per-message engagement tracking (opens and
20 * clicks) is enabled.
21 */
22 dashboardEngagementMetrics?: FeatureStatus;
23 /**
24 * Whether VDM Guardian's optimized shared delivery is enabled.
25 */
26 guardianOptimizedSharedDelivery?: FeatureStatus;
27 }
28
29 export interface AccountSuppressionSettings {
30 /**
31 * The bounce/complaint reasons for which SES adds destinations to the
32 * account-level suppression list.
33 *
34 * Required: SES treats `putAccountSuppressionAttributes` with no reasons as
35 * "suppress nothing", so an optional member would let `suppression: {}`
36 * silently clear the account-wide list.
37 */
38 reasons: SuppressionListReason[];
39 }
40
41 export interface AccountSettingsProps {
42 /**
43 * Whether email sending is enabled for the whole account.
44 *
45 * :::caution
46 * Setting this to `false` **stops all sending for the entire account**, not
47 * just this stack's mail. Only manage it when you intend to pause account-wide
48 * sending.
49 * :::
50 */
51 sendingEnabled?: boolean;
52 /**
53 * Account-level suppression list configuration, applied via
54 * `putAccountSuppressionAttributes`.
55 */
56 suppression?: AccountSuppressionSettings;
57 /**
58 * Virtual Deliverability Manager configuration, applied via
59 * `putAccountVdmAttributes`.
60 */
61 vdm?: AccountVdmSettings;
62 }
63
64 export interface AccountSettings extends Resource<
65 "AWS.SES.AccountSettings",
66 AccountSettingsProps,
67 {
68 /** Whether email sending is enabled for the account. */
69 sendingEnabled: boolean;
70 /** Whether VDM is enabled for the account. */
71 vdmEnabled: FeatureStatus;
72 /** The account-level suppression reasons currently configured. */
73 suppressedReasons: SuppressionListReason[];
74 },
75 never,
76 Providers
77 > {}
78
79 /**
80 * Account-level Amazon SES v2 settings — an account/region singleton that
81 * manages account-wide sending status, the account suppression list, and
82 * Virtual Deliverability Manager (VDM) configuration.
83 *
84 * Only the aspects you specify are managed: omit `sendingEnabled`, `suppression`,
85 * or `vdm` to leave that setting untouched.
86 *
87 * Deleting this resource is a **no-op** — it leaves the account settings exactly
88 * as they are. Unlike a normal resource there is nothing to tear down: these are
89 * account-global toggles with no single safe default, and resetting them (e.g.
90 * disabling sending or clearing the suppression list) would affect live mail
91 * beyond this stack. Change the props and re-deploy to adjust them.
92 * ### Configuring the Account
93 * **Example:** Enable VDM with Engagement Tracking
94 * ```typescript
95 * import * as SES from "@alchemy.run/aws/SES";
96 *
97 * const settings = yield* SES.AccountSettings("Account", {
98 * vdm: {
99 * enabled: "ENABLED",
100 * dashboardEngagementMetrics: "ENABLED",
101 * },
102 * });
103 * ```
104 *
105 * **Example:** Configure the Suppression List
106 * ```typescript
107 * const settings = yield* SES.AccountSettings("Account", {
108 * suppression: { reasons: ["BOUNCE", "COMPLAINT"] },
109 * });
110 * ```
111 *
112 * **Example:** Enable Guardian Optimized Shared Delivery
113 * ```typescript
114 * const settings = yield* SES.AccountSettings("Account", {
115 * vdm: {
116 * enabled: "ENABLED",
117 * guardianOptimizedSharedDelivery: "ENABLED",
118 * },
119 * });
120 * ```
121 *
122 * ### Pausing Account-Wide Sending
123 * **Example:** Stop All Sending for the Account
124 * ```typescript
125 * // WARNING: this halts every outbound email in the account, including mail
126 * // sent by stacks and systems outside this one. Prefer a configuration
127 * // set's sendingEnabled to pause a single sending path.
128 * const settings = yield* SES.AccountSettings("Account", {
129 * sendingEnabled: false,
130 * });
131 * ```
132 *
133 * **Example:** Manage Only VDM and Leave Sending Alone
134 * ```typescript
135 * // Omitted aspects are never touched — this deploy will not read or write
136 * // the account's sending status or suppression list.
137 * const settings = yield* SES.AccountSettings("Account", {
138 * vdm: { enabled: "ENABLED" },
139 * });
140 * ```
141 *
142 * @resource
143 */
144 export const AccountSettings = Resource<AccountSettings>("AWS.SES.AccountSettings");
145
146 const sameReasons = (
147 a: ReadonlyArray<SuppressionListReason> | undefined,
148 b: ReadonlyArray<SuppressionListReason> | undefined,
149 ): boolean => {
150 const key = (reasons: ReadonlyArray<SuppressionListReason> | undefined) =>
151 JSON.stringify([...(reasons ?? [])].sort());
152 return key(a) === key(b);
153 };
154
155 export const AccountSettingsProvider = () =>
156 Provider.effect(
157 AccountSettings,
158 Effect.gen(function* () {
159 const observe = sesv2.getAccount({}).pipe(
160 Effect.map((response) => ({
161 sendingEnabled: response.SendingEnabled ?? false,
162 vdmEnabled: response.VdmAttributes?.VdmEnabled ?? "DISABLED",
163 // distilled types SuppressedReasons open (`| (string & {})`) so the
164 // SDK survives new SES reasons. Narrow to the closed union the props
165 // use, dropping anything we do not model, so attributes assign back
166 // into props.
167 suppressedReasons: (response.SuppressionAttributes?.SuppressedReasons ?? []).filter(
168 (reason): reason is SuppressionListReason =>
169 reason === "BOUNCE" || reason === "COMPLAINT",
170 ),
171 dashboardEngagementMetrics:
172 response.VdmAttributes?.DashboardAttributes?.EngagementMetrics,
173 guardianOptimizedSharedDelivery:
174 response.VdmAttributes?.GuardianAttributes?.OptimizedSharedDelivery,
175 })),
176 );
177
178 const toAttrs = (observed: {
179 sendingEnabled: boolean;
180 vdmEnabled: FeatureStatus;
181 suppressedReasons: SuppressionListReason[];
182 }) => ({
183 sendingEnabled: observed.sendingEnabled,
184 vdmEnabled: observed.vdmEnabled,
185 suppressedReasons: observed.suppressedReasons,
186 });
187
188 return AccountSettings.Provider.of({
189 // Account-global singleton: nuke must not reset it.
190 nuke: { singleton: true },
191 stables: [],
192
193 // The account settings always exist.
194 list: Effect.fn(function* () {
195 return [toAttrs(yield* observe)];
196 }),
197
198 read: Effect.fn(function* () {
199 return toAttrs(yield* observe);
200 }),
201
202 reconcile: Effect.fn(function* ({ news, session }) {
203 // OBSERVE the live account settings; only call each put on a real
204 // delta for the aspects the caller actually manages.
205 let observed = yield* observe;
206
207 if (
208 news.sendingEnabled !== undefined &&
209 observed.sendingEnabled !== news.sendingEnabled
210 ) {
211 yield* sesv2.putAccountSendingAttributes({
212 SendingEnabled: news.sendingEnabled,
213 });
214 }
215
216 if (
217 news.suppression !== undefined &&
218 !sameReasons(observed.suppressedReasons, news.suppression.reasons)
219 ) {
220 yield* sesv2.putAccountSuppressionAttributes({
221 SuppressedReasons: news.suppression.reasons,
222 });
223 }
224
225 if (
226 news.vdm !== undefined &&
227 (observed.vdmEnabled !== news.vdm.enabled ||
228 observed.dashboardEngagementMetrics !== news.vdm.dashboardEngagementMetrics ||
229 observed.guardianOptimizedSharedDelivery !== news.vdm.guardianOptimizedSharedDelivery)
230 ) {
231 yield* sesv2.putAccountVdmAttributes({
232 VdmAttributes: {
233 VdmEnabled: news.vdm.enabled,
234 DashboardAttributes:
235 news.vdm.dashboardEngagementMetrics !== undefined
236 ? { EngagementMetrics: news.vdm.dashboardEngagementMetrics }
237 : undefined,
238 GuardianAttributes:
239 news.vdm.guardianOptimizedSharedDelivery !== undefined
240 ? {
241 OptimizedSharedDelivery: news.vdm.guardianOptimizedSharedDelivery,
242 }
243 : undefined,
244 },
245 });
246 }
247
248 // Re-read so the returned attributes reflect the converged state.
249 observed = yield* observe;
250 yield* session.note(`sending=${observed.sendingEnabled} vdm=${observed.vdmEnabled}`);
251 return toAttrs(observed);
252 }),
253
254 // Account-global singleton: deleting only stops managing the settings.
255 // We deliberately leave them in place — there is no single safe default
256 // to reset to, and changing them would affect account-wide mail.
257 delete: Effect.fn(function* () {}),
258 });
259 }),
260 );