alchemy 2.0.0-beta.65 → 2.0.0-beta.66

package/src/AWS/SES/ReceiptFilter.ts

@@ -0,0 +1,169 @@
+import * as ses from "@distilled.cloud/aws/ses";
+import * as Effect from "effect/Effect";
+import { isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+
+/**
+ * Whether the filter permits (`Allow`) or blocks (`Block`) mail from the
+ * matching IP range.
+ */
+export type ReceiptFilterPolicy = ses.ReceiptFilterPolicy;
+
+export interface ReceiptIpFilter {
+  /**
+   * Whether to allow or block mail from the CIDR range.
+   */
+  policy: ReceiptFilterPolicy;
+  /**
+   * A single IPv4 address (e.g. `1.2.3.4`) or CIDR range (e.g. `1.2.3.0/24`)
+   * the filter applies to.
+   */
+  cidr: string;
+}
+
+export interface ReceiptFilterProps {
+  /**
+   * Name of the IP address filter. May contain letters, numbers, dashes and
+   * underscores, up to 64 characters, and must start and end with a letter or
+   * number. If omitted, a deterministic physical name is generated from the
+   * app, stage, and logical ID. Changing the name replaces the filter.
+   */
+  filterName?: string;
+  /**
+   * The IP filtering rule — an allow or block decision for a CIDR range.
+   * Changing it replaces the filter (SES has no update operation for filters).
+   */
+  ipFilter: ReceiptIpFilter;
+}
+
+export interface ReceiptFilter extends Resource<
+  "AWS.SES.ReceiptFilter",
+  ReceiptFilterProps,
+  {
+    /** Name of the IP address filter. */
+    filterName: string;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * An Amazon SES receipt IP address filter — an account-level allow/block rule
+ * for the source IP of inbound mail. Block filters take precedence over allow
+ * filters.
+ *
+ * Filters are immutable: there is no update API, so any change to the name or
+ * the IP rule replaces the filter.
+ * @resource
+ * @section Creating Filters
+ * @example Block a CIDR Range
+ * ```typescript
+ * import * as SES from "alchemy/AWS/SES";
+ *
+ * const filter = yield* SES.ReceiptFilter("BlockBadActors", {
+ *   ipFilter: { policy: "Block", cidr: "10.0.0.0/24" },
+ * });
+ * ```
+ *
+ * @example Allow a Single Address
+ * ```typescript
+ * const filter = yield* SES.ReceiptFilter("AllowPartner", {
+ *   ipFilter: { policy: "Allow", cidr: "192.0.2.10" },
+ * });
+ * ```
+ */
+export const ReceiptFilter = Resource<ReceiptFilter>("AWS.SES.ReceiptFilter");
+
+export const ReceiptFilterProvider = () =>
+  Provider.effect(
+    ReceiptFilter,
+    Effect.gen(function* () {
+      const createName = Effect.fn(function* (
+        id: string,
+        props: Pick<ReceiptFilterProps, "filterName">,
+      ) {
+        return (
+          props.filterName ?? (yield* createPhysicalName({ id, maxLength: 64 }))
+        );
+      });
+
+      const findFilter = Effect.fn(function* (name: string) {
+        const filters = yield* ses
+          .listReceiptFilters({})
+          .pipe(Effect.map((response) => response.Filters ?? []));
+        return filters.find((filter) => filter.Name === name);
+      });
+
+      return ReceiptFilter.Provider.of({
+        stables: ["filterName"],
+
+        // Account/region-scoped: enumerate every filter so leaked test
+        // resources are cleaned by nuke. Receipt filters carry no tags.
+        list: () =>
+          ses
+            .listReceiptFilters({})
+            .pipe(
+              Effect.map((response) =>
+                (response.Filters ?? []).flatMap((filter) =>
+                  filter.Name ? [{ filterName: filter.Name }] : [],
+                ),
+              ),
+            ),
+
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const name = output?.filterName ?? (yield* createName(id, olds));
+          const found = yield* findFilter(name);
+          return found ? { filterName: name } : undefined;
+        }),
+
+        diff: Effect.fn(function* ({ id, news, olds }) {
+          if (!isResolved(news)) return undefined;
+          const oldName = yield* createName(id, olds);
+          const newName = yield* createName(id, news);
+          if (
+            oldName !== newName ||
+            olds.ipFilter.policy !== news.ipFilter.policy ||
+            olds.ipFilter.cidr !== news.ipFilter.cidr
+          ) {
+            return { action: "replace" } as const;
+          }
+        }),
+
+        reconcile: Effect.fn(function* ({ id, news, output }) {
+          const name = output?.filterName ?? (yield* createName(id, news));
+
+          // OBSERVE — filters have no update API, so reconcile is create-only.
+          const observed = yield* findFilter(name);
+
+          // ENSURE — create if missing; AlreadyExists is a race, not a failure.
+          if (observed === undefined) {
+            yield* ses
+              .createReceiptFilter({
+                Filter: {
+                  Name: name,
+                  IpFilter: {
+                    Policy: news.ipFilter.policy,
+                    Cidr: news.ipFilter.cidr,
+                  },
+                },
+              })
+              .pipe(
+                Effect.catchTag("AlreadyExistsException", () =>
+                  Effect.succeed({}),
+                ),
+              );
+          }
+
+          return { filterName: name };
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          // deleteReceiptFilter is idempotent for a missing filter.
+          yield* ses.deleteReceiptFilter({ FilterName: output.filterName });
+        }),
+      });
+    }),
+  );

package/src/AWS/SES/ReceiptRule.ts

@@ -0,0 +1,300 @@
+import * as ses from "@distilled.cloud/aws/ses";
+import * as Effect from "effect/Effect";
+import { isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+
+/**
+ * Whether SES requires (`Require`) or merely prefers (`Optional`) a TLS
+ * connection from the sending mail server before accepting a message that
+ * matches this rule.
+ */
+export type ReceiptRuleTlsPolicy = ses.TlsPolicy;
+
+/**
+ * A single receipt-rule action. Pass the distilled action shape directly — one
+ * of `S3Action`, `SNSAction`, `LambdaAction`, `BounceAction`, `AddHeaderAction`,
+ * `StopAction`, `WorkmailAction`, or `ConnectAction`. Actions run in array
+ * order; resource ARNs (bucket, topic, function) are supplied by the caller.
+ */
+export type ReceiptRuleAction = ses.ReceiptAction;
+
+export interface ReceiptRuleProps {
+  /**
+   * Name of the receipt rule set this rule belongs to. Typically the
+   * `ruleSetName` output of a `SES.ReceiptRuleSet`. Changing it replaces the
+   * rule.
+   */
+  ruleSetName: string;
+  /**
+   * Name of the receipt rule. May contain letters, numbers, dashes,
+   * underscores and periods, up to 64 characters. If omitted, a deterministic
+   * physical name is generated from the app, stage, and logical ID. Changing
+   * the name replaces the rule.
+   */
+  ruleName?: string;
+  /**
+   * Whether the rule is enabled. Disabled rules are skipped during receipt
+   * processing.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Whether SES scans incoming messages that match this rule for spam and
+   * viruses.
+   * @default true
+   */
+  scanEnabled?: boolean;
+  /**
+   * Whether SES accepts email over a clear text connection (`Optional`) or
+   * requires TLS (`Require`) before applying this rule.
+   * @default "Optional"
+   */
+  tlsPolicy?: ReceiptRuleTlsPolicy;
+  /**
+   * Recipient email addresses or domains this rule applies to. An empty or
+   * omitted list matches all recipients.
+   */
+  recipients?: string[];
+  /**
+   * Name of an existing rule in the same rule set after which this rule should
+   * be placed. Omit to place the rule at the top of the rule set. Rules are
+   * evaluated in order.
+   */
+  after?: string;
+  /**
+   * Ordered list of actions SES performs when a message matches this rule
+   * (deliver to S3, publish to SNS, invoke Lambda, bounce, add a header, stop
+   * processing, etc.).
+   */
+  actions?: ReceiptRuleAction[];
+}
+
+export interface ReceiptRule extends Resource<
+  "AWS.SES.ReceiptRule",
+  ReceiptRuleProps,
+  {
+    /** Name of the rule set this rule belongs to. */
+    ruleSetName: string;
+    /** Name of the receipt rule. */
+    ruleName: string;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * An Amazon SES receipt rule — a matcher plus an ordered list of actions that
+ * SES applies to inbound email received through the parent
+ * `SES.ReceiptRuleSet`.
+ *
+ * Actions are passed as the raw distilled action shapes (no marshalling): the
+ * caller supplies bucket names, topic ARNs, and function ARNs directly.
+ * @resource
+ * @section Creating Rules
+ * @example Deliver Matching Mail to S3
+ * ```typescript
+ * import * as SES from "alchemy/AWS/SES";
+ *
+ * const ruleSet = yield* SES.ReceiptRuleSet("Inbound", {});
+ * const rule = yield* SES.ReceiptRule("ToBucket", {
+ *   ruleSetName: ruleSet.ruleSetName,
+ *   recipients: ["support@example.com"],
+ *   actions: [
+ *     { S3Action: { BucketName: "my-inbound-mail" } },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Invoke a Lambda and Add a Header
+ * ```typescript
+ * const rule = yield* SES.ReceiptRule("Process", {
+ *   ruleSetName: ruleSet.ruleSetName,
+ *   tlsPolicy: "Require",
+ *   scanEnabled: true,
+ *   actions: [
+ *     { AddHeaderAction: { HeaderName: "X-Inbound", HeaderValue: "ses" } },
+ *     { LambdaAction: { FunctionArn: fn.functionArn, InvocationType: "Event" } },
+ *   ],
+ * });
+ * ```
+ *
+ * @section Ordering Rules
+ * @example Place a Rule After Another
+ * ```typescript
+ * // A BounceAction's Sender must be a verified SES identity — SES rejects the
+ * // rule with IdentityNotVerified at create/update time otherwise.
+ * const first = yield* SES.ReceiptRule("First", {
+ *   ruleSetName: ruleSet.ruleSetName,
+ *   actions: [{ StopAction: { Scope: "RuleSet" } }],
+ * });
+ * const second = yield* SES.ReceiptRule("Second", {
+ *   ruleSetName: ruleSet.ruleSetName,
+ *   after: first.ruleName,
+ *   actions: [{ BounceAction: {
+ *     SmtpReplyCode: "550",
+ *     Message: "Mailbox does not exist",
+ *     Sender: "mailer-daemon@example.com",
+ *   } }],
+ * });
+ * ```
+ */
+export const ReceiptRule = Resource<ReceiptRule>("AWS.SES.ReceiptRule");
+
+/**
+ * The name of the rule immediately preceding `ruleName` in the rule set's
+ * ordered rule list, or `undefined` when the rule is first (or absent). This is
+ * the observed value of the `after` position.
+ */
+const observedPredecessor = (
+  rules: ReadonlyArray<ses.ReceiptRule>,
+  ruleName: string,
+): string | undefined => {
+  const index = rules.findIndex((rule) => rule.Name === ruleName);
+  if (index <= 0) return undefined;
+  return rules[index - 1]?.Name;
+};
+
+export const ReceiptRuleProvider = () =>
+  Provider.effect(
+    ReceiptRule,
+    Effect.gen(function* () {
+      const createName = Effect.fn(function* (
+        id: string,
+        props: Pick<ReceiptRuleProps, "ruleName">,
+      ) {
+        return (
+          props.ruleName ?? (yield* createPhysicalName({ id, maxLength: 64 }))
+        );
+      });
+
+      const describeRule = Effect.fn(function* (
+        ruleSetName: string,
+        ruleName: string,
+      ) {
+        return yield* ses
+          .describeReceiptRule({ RuleSetName: ruleSetName, RuleName: ruleName })
+          .pipe(
+            Effect.catchTags({
+              RuleDoesNotExistException: () => Effect.succeed(undefined),
+              RuleSetDoesNotExistException: () => Effect.succeed(undefined),
+            }),
+          );
+      });
+
+      const buildRule = (
+        ruleName: string,
+        props: ReceiptRuleProps,
+      ): ses.ReceiptRule => ({
+        Name: ruleName,
+        // The classic API defaults an omitted Enabled/ScanEnabled to FALSE —
+        // apply the documented defaults explicitly so an undeclared rule is
+        // enabled (a silently disabled rule bounces all inbound mail).
+        Enabled: props.enabled ?? true,
+        TlsPolicy: props.tlsPolicy,
+        Recipients: props.recipients,
+        Actions: props.actions,
+        ScanEnabled: props.scanEnabled ?? true,
+      });
+
+      return ReceiptRule.Provider.of({
+        stables: ["ruleSetName", "ruleName"],
+
+        // Rules are sub-resources keyed entirely by their parent rule set;
+        // there is no flat account-level enumeration, so nuke handles them via
+        // the parent rule set's deletion.
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const ruleSetName = output?.ruleSetName ?? olds.ruleSetName;
+          if (!ruleSetName) return undefined;
+          const ruleName = output?.ruleName ?? (yield* createName(id, olds));
+          const found = yield* describeRule(ruleSetName, ruleName);
+          return found?.Rule ? { ruleSetName, ruleName } : undefined;
+        }),
+
+        diff: Effect.fn(function* ({ id, news, olds }) {
+          if (!isResolved(news)) return undefined;
+          if (news.ruleSetName !== olds.ruleSetName) {
+            return { action: "replace" } as const;
+          }
+          const oldName = yield* createName(id, olds);
+          const newName = yield* createName(id, news);
+          if (oldName !== newName) {
+            return { action: "replace" } as const;
+          }
+        }),
+
+        reconcile: Effect.fn(function* ({ id, news, output }) {
+          const ruleSetName = news.ruleSetName;
+          const ruleName = output?.ruleName ?? (yield* createName(id, news));
+          const rule = buildRule(ruleName, news);
+
+          // OBSERVE — cloud state is authoritative.
+          const observed = yield* describeRule(ruleSetName, ruleName);
+
+          // ENSURE / SYNC — a single full-replace call converges the rule's
+          // matcher and actions whether it is missing or already present.
+          if (observed?.Rule === undefined) {
+            yield* ses
+              .createReceiptRule({
+                RuleSetName: ruleSetName,
+                After: news.after,
+                Rule: rule,
+              })
+              .pipe(
+                Effect.catchTag("AlreadyExistsException", () =>
+                  ses.updateReceiptRule({
+                    RuleSetName: ruleSetName,
+                    Rule: rule,
+                  }),
+                ),
+              );
+          } else {
+            yield* ses.updateReceiptRule({
+              RuleSetName: ruleSetName,
+              Rule: rule,
+            });
+          }
+
+          // SYNC POSITION — updateReceiptRule never moves the rule, so diff the
+          // observed predecessor against the desired `after` and reposition
+          // only on a mismatch.
+          const ruleSet = yield* ses.describeReceiptRuleSet({
+            RuleSetName: ruleSetName,
+          });
+          const predecessor = observedPredecessor(
+            ruleSet.Rules ?? [],
+            ruleName,
+          );
+          if (predecessor !== news.after) {
+            yield* ses.setReceiptRulePosition({
+              RuleSetName: ruleSetName,
+              RuleName: ruleName,
+              After: news.after,
+            });
+          }
+
+          return { ruleSetName, ruleName };
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          // deleteReceiptRule is idempotent for a missing rule; a missing rule
+          // set means the rule is already gone.
+          yield* ses
+            .deleteReceiptRule({
+              RuleSetName: output.ruleSetName,
+              RuleName: output.ruleName,
+            })
+            .pipe(
+              Effect.catchTag(
+                "RuleSetDoesNotExistException",
+                () => Effect.void,
+              ),
+            );
+        }),
+      });
+    }),
+  );

package/src/AWS/SES/ReceiptRuleSet.ts

@@ -0,0 +1,164 @@
+import * as ses from "@distilled.cloud/aws/ses";
+import * as Effect from "effect/Effect";
+import { isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+
+export interface ReceiptRuleSetProps {
+  /**
+   * Name of the receipt rule set. May contain letters, numbers, dashes,
+   * underscores and periods, up to 64 characters, and must start and end with
+   * a letter or number. If omitted, a deterministic physical name is generated
+   * from the app, stage, and logical ID. Changing the name replaces the rule
+   * set.
+   */
+  ruleSetName?: string;
+}
+
+export interface ReceiptRuleSet extends Resource<
+  "AWS.SES.ReceiptRuleSet",
+  ReceiptRuleSetProps,
+  {
+    /** Name of the receipt rule set. */
+    ruleSetName: string;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * An Amazon SES receipt rule set — the ordered container for the receipt rules
+ * that decide what happens to inbound email (deliver to S3, invoke a Lambda,
+ * publish to SNS, bounce, etc.).
+ *
+ * A rule set is an empty container on creation; add `SES.ReceiptRule`s to it
+ * and point the account at it with `SES.ActiveReceiptRuleSet` to start
+ * processing mail. Email receiving is only available in a subset of regions
+ * (e.g. `us-east-1`, `us-west-2`, `eu-west-1`).
+ * @resource
+ * @section Creating Rule Sets
+ * @example Basic Rule Set
+ * ```typescript
+ * import * as SES from "alchemy/AWS/SES";
+ *
+ * const ruleSet = yield* SES.ReceiptRuleSet("Inbound", {});
+ * ```
+ *
+ * @example Named Rule Set
+ * ```typescript
+ * const ruleSet = yield* SES.ReceiptRuleSet("Inbound", {
+ *   ruleSetName: "my-inbound-rules",
+ * });
+ * ```
+ *
+ * @section Activating a Rule Set
+ * @example Point the Account at a Rule Set
+ * ```typescript
+ * const ruleSet = yield* SES.ReceiptRuleSet("Inbound", {});
+ * yield* SES.ActiveReceiptRuleSet("Active", {
+ *   ruleSetName: ruleSet.ruleSetName,
+ * });
+ * ```
+ */
+export const ReceiptRuleSet = Resource<ReceiptRuleSet>(
+  "AWS.SES.ReceiptRuleSet",
+);
+
+export const ReceiptRuleSetProvider = () =>
+  Provider.effect(
+    ReceiptRuleSet,
+    Effect.gen(function* () {
+      const createName = Effect.fn(function* (
+        id: string,
+        props: Pick<ReceiptRuleSetProps, "ruleSetName">,
+      ) {
+        return (
+          props.ruleSetName ??
+          (yield* createPhysicalName({ id, maxLength: 64 }))
+        );
+      });
+
+      const describe = Effect.fn(function* (name: string) {
+        return yield* ses
+          .describeReceiptRuleSet({ RuleSetName: name })
+          .pipe(
+            Effect.catchTag("RuleSetDoesNotExistException", () =>
+              Effect.succeed(undefined),
+            ),
+          );
+      });
+
+      return ReceiptRuleSet.Provider.of({
+        stables: ["ruleSetName"],
+
+        // Account/region-scoped: enumerate every rule set so leaked test
+        // resources are cleaned by nuke. Classic receipt rule sets carry no
+        // tags, so there is no ownership signal to filter on.
+        list: () =>
+          Effect.gen(function* () {
+            const rows: { ruleSetName: string }[] = [];
+            let nextToken: string | undefined;
+            do {
+              const page = yield* ses.listReceiptRuleSets({
+                NextToken: nextToken,
+              });
+              for (const set of page.RuleSets ?? []) {
+                if (set.Name) rows.push({ ruleSetName: set.Name });
+              }
+              nextToken = page.NextToken;
+            } while (nextToken);
+            return rows;
+          }),
+
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const name = output?.ruleSetName ?? (yield* createName(id, olds));
+          const found = yield* describe(name);
+          // Receipt rule sets are untagged in the classic API, so there is no
+          // way to distinguish a foreign rule set from one we own. Existence
+          // at our deterministic name is treated as ownership.
+          return found ? { ruleSetName: name } : undefined;
+        }),
+
+        diff: Effect.fn(function* ({ id, news, olds }) {
+          if (!isResolved(news)) return undefined;
+          const oldName = yield* createName(id, olds);
+          const newName = yield* createName(id, news);
+          if (oldName !== newName) {
+            return { action: "replace" } as const;
+          }
+        }),
+
+        reconcile: Effect.fn(function* ({ id, news, output }) {
+          const name = output?.ruleSetName ?? (yield* createName(id, news));
+
+          // OBSERVE — cloud state is authoritative.
+          const observed = yield* describe(name);
+
+          // ENSURE — create if missing; AlreadyExists is a race, not a failure.
+          if (observed === undefined) {
+            yield* ses
+              .createReceiptRuleSet({ RuleSetName: name })
+              .pipe(
+                Effect.catchTag("AlreadyExistsException", () =>
+                  Effect.succeed({}),
+                ),
+              );
+          }
+
+          // A rule set has no mutable aspects of its own; rules are separate
+          // `SES.ReceiptRule` resources.
+          return { ruleSetName: name };
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          // deleteReceiptRuleSet is idempotent for a missing set; the active
+          // set cannot be deleted and surfaces as a typed CannotDeleteException.
+          yield* ses.deleteReceiptRuleSet({
+            RuleSetName: output.ruleSetName,
+          });
+        }),
+      });
+    }),
+  );

package/src/AWS/SES/SendBounce.ts

@@ -0,0 +1,44 @@
+import type * as ses from "@distilled.cloud/aws/ses";
+import type * as Effect from "effect/Effect";
+import * as Binding from "../../Binding.ts";
+
+/**
+ * Runtime binding for `ses:SendBounce` (classic SES).
+ *
+ * Generates and sends a bounce message to the sender of an email you received
+ * through SES receiving — the data-plane counterpart to `SES.ReceiptRule`
+ * inbound processing. You can only bounce a message within 24 hours of
+ * receiving it, and only for mail SES actually received.
+ *
+ * Account-level operation with no resource-level IAM scoping. Provide the
+ * implementation with `Effect.provide(AWS.SES.SendBounceHttp)`.
+ * @binding
+ * @section Bouncing Inbound Mail
+ * @example Bounce a Received Message
+ * ```typescript
+ * // init — account-level binding, no resource argument
+ * const sendBounce = yield* SES.SendBounce();
+ *
+ * // runtime — inside the Lambda that a ReceiptRule invokes
+ * yield* sendBounce({
+ *   OriginalMessageId: messageId,
+ *   BounceSender: "mailer-daemon@example.com",
+ *   BouncedRecipientInfoList: [
+ *     {
+ *       Recipient: "nobody@example.com",
+ *       BounceType: "DoesNotExist",
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export interface SendBounce extends Binding.Service<
+  SendBounce,
+  "AWS.SES.SendBounce",
+  () => Effect.Effect<
+    (
+      request: ses.SendBounceRequest,
+    ) => Effect.Effect<ses.SendBounceResponse, ses.SendBounceError>
+  >
+> {}
+export const SendBounce = Binding.Service<SendBounce>("AWS.SES.SendBounce");

package/src/AWS/SES/SendBounceHttp.ts

@@ -0,0 +1,13 @@
+import * as ses from "@distilled.cloud/aws/ses";
+import * as Layer from "effect/Layer";
+import { makeSESHttpBinding } from "./BindingHttp.ts";
+import { SendBounce } from "./SendBounce.ts";
+
+export const SendBounceHttp = Layer.effect(
+  SendBounce,
+  makeSESHttpBinding({
+    tag: "AWS.SES.SendBounce",
+    operation: ses.sendBounce,
+    actions: ["ses:SendBounce"],
+  }),
+);