@kensio/yulin 1.21.1 → 1.21.3

package/docs/services/ses/README.md

@@ -14,7 +14,7 @@ SES specific types are imported from the `@kensio/yulin/ses` subpath.
 ## Asserting on a message that was sent
 
 `sentEmails()` hands over the record. Each message carries who it was from, the three recipient
-lists, the subject, the body and the message id SES answered with.
+lists, the subject, the body, its attachments and the message id SES answered with.
 
 ```typescript sim-ses-send-and-assert
 /**
@@ -59,6 +59,60 @@ read. The three recipient lists stay apart, leaving a test free to assert that a
 `body` keeps `text` and `html` apart too. A message sent with only an HTML body reports `undefined`
 for its text, and never the markup.
 
+### Asserting on an attachment
+
+A simple message may carry structured attachments. The record keeps them in request order.
+`rawContent` contains a copy of the bytes from the request, and the other fields contain the supplied
+SES attachment metadata.
+
+```typescript sim-ses-attachments
+/**
+ * Sending a generated CSV and reading it from the simulated SES record.
+ */
+
+import { SendEmailCommand } from "@aws-sdk/client-sesv2";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const ses = simAws.sesV2();
+
+ses.verifyIdentity("hello@example.com");
+ses.verifyIdentity("someone@example.org");
+
+const csv = new TextEncoder().encode("word,meaning\n你好,hello\n");
+
+await ses.sendEmail(
+  new SendEmailCommand({
+    FromEmailAddress: "hello@example.com",
+    Destination: { ToAddresses: ["someone@example.org"] },
+    Content: {
+      Simple: {
+        Subject: { Data: "Your vocabulary backup" },
+        Body: { Text: { Data: "Your backup is attached." } },
+        Attachments: [
+          {
+            RawContent: csv,
+            FileName: "vocabulary.csv",
+            ContentType: "text/csv; charset=utf-8",
+            ContentDisposition: "ATTACHMENT",
+          },
+        ],
+      },
+    },
+  }),
+);
+
+const [email] = ses.sentEmails();
+const [attachment] = email?.attachments ?? [];
+
+// vocabulary.csv "word,meaning\n你好,hello\n"
+console.log(
+  attachment?.fileName,
+  new TextDecoder().decode(attachment?.rawContent),
+);
+```
+
 ## Verifying identities
 
 Real SES verifies an email address by emailing it a link and a domain by looking for DNS records.
@@ -303,8 +357,9 @@ sending switch, the delivery options and the reputation switch are all declared
 SES holds a set as state. A test can then assert what a stack declared, with no AWS account to read
 it back from.
 
-A set is attached to an identity, or named on a send. `SendingEnabled` is the one option a send acts
-on. The rest are held for a test to read back.
+A set is attached to an identity, or named on a send. `SendingEnabled` acts during acceptance.
+Suppression options decide whether explicit bounce or complaint feedback adds the recipient to the
+account suppression list. The rest are held for a test to read back.
 
 ```typescript sim-ses-configuration-sets
 /**
@@ -350,8 +405,13 @@ console.log(ses.allConfigurationSets().map((set) => set.configurationSetName));
 ```
 
 A set declaring only its name gets the defaults real SES applies. Sending is on, TLS is optional,
-reputation metrics are off and no reason is suppressed. `GetConfigurationSet` reports those defaults
-back rather than leaving the groups out of the answer.
+reputation metrics are off and suppression falls back to the account reasons.
+`GetConfigurationSet` reports the sending, delivery and reputation defaults. It leaves suppression
+options absent where the set has no override.
+
+An explicit empty override is different. `SuppressionOptions: { SuppressedReasons: [] }` disables
+suppression for feedback on messages sent through that set. Simulated SES retains the empty list so
+it does not fall back to the account reasons.
 
 `findConfigurationSet` reaches one set by name and `allConfigurationSets` hands over every set in
 the scope, oldest first.
@@ -436,9 +496,9 @@ set at a time.
 domain and the events that report a click. The Virtual Deliverability Manager reports on engagement,
 which this simulation never measures.
 
-A set's suppression reasons are held and read back, and that is all they do. On real SES they decide
-what a bounce or a complaint would add to the account suppression list. Both are absent here. The
-list itself is a separate thing, filled by hand.
+A set's suppression reasons override the account reasons when `recordFeedback` records a hard bounce
+or complaint for a message sent through it. A set with no suppression options falls back to the
+account reasons. The feedback entry goes onto the account suppression list.
 
 `TlsPolicy` accepts `REQUIRE` and `OPTIONAL` and refuses anything else, and a `SuppressedReasons`
 entry that is neither `BOUNCE` nor `COMPLAINT` is refused too. `MaxDeliverySeconds` takes whole
@@ -644,9 +704,9 @@ review is beyond what a test can assert on anyway.
 ## The suppression list
 
 Real SES holds an account-level suppression list and fills it from hard bounces and complaints.
-Nothing bounces here, so every address on this one was put there by a caller. That is what makes it
-worth having in a test. The support tool that lists suppressed addresses, the form that removes one
-and the script that seeds the list all have somewhere to run.
+Tests supply that feedback explicitly with `recordFeedback`. Suppression commands manage the same
+list. The support tool that lists suppressed addresses, the form that removes one and the script
+that seeds the list all have somewhere to run.
 
 `PutSuppressedDestination`, `GetSuppressedDestination`, `ListSuppressedDestinations` and
 `DeleteSuppressedDestination` manage it.
@@ -705,6 +765,70 @@ carries the answer. `suppressedRecipients` names who was held back and why,
 and `isFullySuppressed` is the narrower question of whether the message reached nobody. A message to
 two recipients with one of them suppressed went to the other.
 
+### Recording a hard bounce or complaint
+
+`recordFeedback` takes the message id of an accepted message, one of its recipient addresses and a
+`BOUNCE` or `COMPLAINT` reason. Active feedback adds or updates the account suppression entry at the
+current simulated time. The existing suppression commands and `suppressedDestinations()` read the
+result.
+
+```typescript sim-ses-feedback-suppression
+/**
+ * Recording a hard bounce and observing the next send being suppressed.
+ */
+
+import { SendEmailCommand } from "@aws-sdk/client-sesv2";
+
+import { SimAws, SimFixedClock } from "@kensio/yulin";
+
+const simAws = new SimAws({
+  clock: new SimFixedClock(new Date("2026-08-31T09:00:00.000Z")),
+});
+const ses = simAws.sesV2();
+
+ses.verifyIdentity("hello@example.com");
+ses.verifyIdentity("someone@example.org");
+
+const message = new SendEmailCommand({
+  FromEmailAddress: "hello@example.com",
+  Destination: { ToAddresses: ["someone@example.org"] },
+  Content: {
+    Simple: {
+      Subject: { Data: "Welcome" },
+      Body: { Text: { Data: "Hi there" } },
+    },
+  },
+});
+
+const accepted = await ses.sendEmail(message);
+
+ses.recordFeedback({
+  messageId: accepted.MessageId!,
+  emailAddress: "someone@example.org",
+  reason: "BOUNCE",
+});
+
+await ses.sendEmail(message);
+
+const suppressed = ses.suppressedDestinations()[0];
+const later = ses.sentEmails()[1];
+
+// "BOUNCE" "2026-08-31T09:00:00.000Z" true
+console.log(
+  suppressed?.reason,
+  suppressed?.lastUpdateTime.toISOString(),
+  later?.isFullySuppressed,
+);
+```
+
+The operation refuses a message id this SES scope did not issue and an address that was not a
+recipient of that message. Recipient matching ignores case and a display name, while the suppression
+entry keeps the address spelling from the accepted message.
+
+Without a configuration-set override, the account's `SuppressedReasons` decide whether feedback is
+active. A configuration set with suppression options replaces those reasons for messages sent
+through it. An empty override leaves the suppression list unchanged.
+
 `ListSuppressedDestinations` pages with `PageSize` and `NextToken`, and narrows with `Reasons`,
 `StartDate` and `EndDate`. Removing an address that was never on the list succeeds, so a form that
 removes one twice has no failure to handle.
@@ -938,29 +1062,29 @@ time forward past the window sees the count fall the way an account's would.
 
 ## Simulated commands
 
-| Command                           | Notes                                                                                                     |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `SendEmail`                       | `Content.Simple` and `Content.Template`. Recorded rather than delivered.                                  |
-| `CreateEmailIdentity`             | Starts unverified. `Tags`, `DkimSigningAttributes` and `ConfigurationSetName` are held and reported back. |
-| `GetEmailIdentity`                | Reports the DKIM, MAIL FROM, feedback, configuration set and tag settings the identity holds.             |
-| `ListEmailIdentities`             | Paged with `PageSize` and `NextToken`.                                                                    |
-| `DeleteEmailIdentity`             |                                                                                                           |
-| `CreateEmailTemplate`             | Substitution only. `Tags` are refused.                                                                    |
-| `GetEmailTemplate`                | Reports the wording with its placeholders unrendered.                                                     |
-| `UpdateEmailTemplate`             | Replaces the wording outright, keeping the creation time.                                                 |
-| `ListEmailTemplates`              | Names and creation times only, paged.                                                                     |
-| `DeleteEmailTemplate`             |                                                                                                           |
-| `CreateConfigurationSet`          | `TrackingOptions`, `VdmOptions` and `Tags` are refused.                                                   |
-| `GetConfigurationSet`             | Reports the defaults it applied as well as what was declared.                                             |
-| `ListConfigurationSets`           | Names only, paged with `PageSize` and `NextToken`.                                                        |
-| `DeleteConfigurationSet`          |                                                                                                           |
-| `GetAccount`                      | Reports `SuppressionAttributes` alongside the quota.                                                      |
-| `PutAccountDetails`               | `MailType` and `WebsiteURL` are required, as on real SES.                                                 |
-| `PutAccountSuppressionAttributes` | No reasons at all turns the suppression list off.                                                         |
-| `PutSuppressedDestination`        | Accepted in the sandbox, which real SES refuses.                                                          |
-| `GetSuppressedDestination`        |                                                                                                           |
-| `ListSuppressedDestinations`      | Paged, and narrowed by `Reasons`, `StartDate` and `EndDate`.                                              |
-| `DeleteSuppressedDestination`     | Removing an address that is not on the list succeeds.                                                     |
+| Command                           | Notes                                                                                                       |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `SendEmail`                       | `Content.Simple`, including structured attachments, and `Content.Template`. Recorded rather than delivered. |
+| `CreateEmailIdentity`             | Starts unverified. `Tags`, `DkimSigningAttributes` and `ConfigurationSetName` are held and reported back.   |
+| `GetEmailIdentity`                | Reports the DKIM, MAIL FROM, feedback, configuration set and tag settings the identity holds.               |
+| `ListEmailIdentities`             | Paged with `PageSize` and `NextToken`.                                                                      |
+| `DeleteEmailIdentity`             |                                                                                                             |
+| `CreateEmailTemplate`             | Substitution only. `Tags` are refused.                                                                      |
+| `GetEmailTemplate`                | Reports the wording with its placeholders unrendered.                                                       |
+| `UpdateEmailTemplate`             | Replaces the wording outright, keeping the creation time.                                                   |
+| `ListEmailTemplates`              | Names and creation times only, paged.                                                                       |
+| `DeleteEmailTemplate`             |                                                                                                             |
+| `CreateConfigurationSet`          | `TrackingOptions`, `VdmOptions` and `Tags` are refused.                                                     |
+| `GetConfigurationSet`             | Reports applied defaults and preserves whether suppression options were absent.                             |
+| `ListConfigurationSets`           | Names only, paged with `PageSize` and `NextToken`.                                                          |
+| `DeleteConfigurationSet`          |                                                                                                             |
+| `GetAccount`                      | Reports `SuppressionAttributes` alongside the quota.                                                        |
+| `PutAccountDetails`               | `MailType` and `WebsiteURL` are required, as on real SES.                                                   |
+| `PutAccountSuppressionAttributes` | No reasons at all turns the suppression list off.                                                           |
+| `PutSuppressedDestination`        | Accepted in the sandbox, which real SES refuses.                                                            |
+| `GetSuppressedDestination`        |                                                                                                             |
+| `ListSuppressedDestinations`      | Paged, and narrowed by `Reasons`, `StartDate` and `EndDate`.                                                |
+| `DeleteSuppressedDestination`     | Removing an address that is not on the list succeeds.                                                       |
 
 Anything else refuses on send with `SimSdkUnsupportedCommandError`.
 
@@ -978,19 +1102,18 @@ Anything else refuses on send with `SimSdkUnsupportedCommandError`.
   the template. Template data holding an object where the template wants a value is refused too,
   where real Handlebars would render `[object Object]`.
 - **`SendBulkEmail` is absent**, along with its per-recipient replacement data.
-- **Nothing is delivered, and nothing bounces.** There are no bounce or complaint events and no
-  event destinations.
+- **Nothing is delivered.** A test supplies a hard bounce or complaint through `recordFeedback`.
+  Feedback is never generated automatically, and there are no event destinations.
 - **A configuration set acts on one send.** `SendingEnabled` refuses a send made through the set.
-  The suppression reasons, delivery options and reputation switch are held and read back, and
-  nothing acts on those.
+  Suppression reasons act on explicit feedback. Delivery options and the reputation switch are held
+  and read back.
 - **A set name nothing created is still accepted.** Real SES refuses one on an identity and on a
   send. Both stand here and the name is recorded, because a test failing over a set missing from a
   local setup fails for a reason unrelated to what it asserts.
 - **A configuration set holds what it was created with.** The `Put` commands that change one group
   of options are absent. A set cannot be changed once it exists.
-- **The suppression list fills only by hand.** Every address on it was put there by a caller,
-  because no message here ever bounces. A configuration set's `SuppressedReasons` name what a bounce
-  or a complaint would suppress for, and both are absent.
+- **Feedback is explicit.** Hard bounces and complaints update the suppression list only when a test
+  calls `recordFeedback`. Soft bounces are absent.
 - **Tenant-level suppression lists are left out.** A suppression command carrying `TenantName` is
   refused rather than answered from the account-level list.
 - **`PutSuppressedDestination` works in the sandbox.** Real SES refuses it until an account has

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.1",
+  "version": "1.21.3",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",
@@ -297,7 +297,7 @@
     "execa": "^10.0.0",
     "fta-cli": "^3.0.0",
     "node-sql-parser": "^5.4.0",
-    "oxfmt": "^0.64.0",
+    "oxfmt": "^0.65.0",
     "oxlint": "^1.77.0",
     "oxlint-tsgolint": "^7.0.2001",
     "semantic-release": "25.0.9",