@kensio/yulin 1.21.0 → 1.21.2

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/docs/services/sqs/README.md

@@ -1049,8 +1049,39 @@ console.log(stack.output("OrdersQueueArn"));
 ```
 
 The properties applied to the queue are `VisibilityTimeout`, `DelaySeconds`,
-`MessageRetentionPeriod`, `MaximumMessageSize` and `ReceiveMessageWaitTimeSeconds`. Each is passed to
-`CreateQueue`, and a value outside the range real SQS accepts fails the resource.
+`MessageRetentionPeriod`, `MaximumMessageSize`, `ReceiveMessageWaitTimeSeconds` and
+`RedrivePolicy`. Each is passed to `CreateQueue`, and a value outside the range real SQS accepts
+fails the resource.
+
+`RedrivePolicy` is the same attribute [dead-letter queues](#dead-letter-queues) covers, and a
+template goes through the validation an SDK caller goes through. CloudFormation carries the policy
+as an object where SQS carries it as a JSON string, and both spellings arrive at `CreateQueue` the
+same way. The `deadLetterTargetArn` has to name a queue that already exists. Naming the dead-letter
+queue with `Fn::GetAtt` also puts the two queues in the order they have to be created in.
+
+```typescript
+{
+  OrdersDlq: {
+    Type: "AWS::SQS::Queue",
+    Properties: { QueueName: "orders-dlq" },
+  },
+  OrdersQueue: {
+    Type: "AWS::SQS::Queue",
+    Properties: {
+      QueueName: "orders",
+      RedrivePolicy: {
+        deadLetterTargetArn: { "Fn::GetAtt": ["OrdersDlq", "Arn"] },
+        maxReceiveCount: 3,
+      },
+    },
+  },
+}
+```
+
+A message the queue gives up on reaches `orders-dlq`, and `GetQueueAttributes` on `orders` reports
+the policy back. A policy real SQS would refuse fails the resource, in the words it refuses an SDK
+caller with. Terraform's `redrive_policy` and its `aws_sqs_queue_redrive_policy` resource both map
+onto this property. A plan carrying either deploys a working dead-letter queue.
 
 A queue with no `QueueName` is named from the stack name, the logical ID and a tail derived from
 both. The queue above with its name left out would be `orders-stack-OrdersQueue-` and twelve more
@@ -1065,10 +1096,16 @@ under the name the template gave it.
 The properties this simulation has no behaviour for are a different case. The queue is created without
 them and each one is recorded in
 [`stack.ignoredProperties`](https://yulinsim.dev/services/cloudformation/#properties-a-resource-was-created-without).
-A stack full of queues still deploys. Those properties are `RedrivePolicy`, `RedriveAllowPolicy`,
-`KmsMasterKeyId`, `KmsDataKeyReusePeriodSeconds`, `SqsManagedSseEnabled`,
-`ContentBasedDeduplication`, `DeduplicationScope`, `FifoThroughputLimit` and `Tags`. A property
-outside the `AWS::SQS::Queue` schema is recorded the same way.
+A stack full of queues still deploys. Those properties are `RedriveAllowPolicy`, `KmsMasterKeyId`,
+`KmsDataKeyReusePeriodSeconds`, `SqsManagedSseEnabled`, `ContentBasedDeduplication`,
+`DeduplicationScope`, `FifoThroughputLimit` and `Tags`. A property outside the `AWS::SQS::Queue`
+schema is recorded the same way.
+
+`KmsDataKeyReusePeriodSeconds` is read for one thing before being recorded. Real SQS takes a period
+between 60 seconds and 86,400, and answers anything else with `InvalidAttributeValue`, which fails
+the stack at `CreateQueue`. Nothing here encrypts a message either way, and a queue that deployed
+with a period outside that range would report a template CloudFormation rejects as working. A period
+inside it is recorded like any other skipped property.
 
 `AWS::SQS::QueuePolicy` deploys the policy it names onto each queue in its `Queues` list, through
 `SetQueueAttributes`. A policy declared in a template is therefore validated and enforced exactly as
@@ -1123,7 +1160,8 @@ Sim SQS currently supports:
 - Lambda event source mappings, delivering messages to a simulated function and deleting the batches
   it handles
 - `AWS::SQS::Queue` and `AWS::SQS::QueuePolicy` in a CloudFormation or CDK template, with `Ref`
-  giving the queue URL and `Fn::GetAtt` giving `Arn`, `QueueName` and `QueueUrl`
+  giving the queue URL and `Fn::GetAtt` giving `Arn`, `QueueName` and `QueueUrl`, and a
+  `RedrivePolicy` on a queue naming its dead-letter queue
 
 ## Limitations
 
@@ -1152,9 +1190,6 @@ Current documented limitations:
   reading of SQS, and AWS documents no answer either way. A receive count counts receives from one
   queue, and the moved message has not been received from the dead-letter queue yet. `SentTimestamp`
   being unchanged by the move is documented AWS behaviour, and is simulated as such.
-- The `RedrivePolicy` property on `AWS::SQS::Queue` is left out, and an SDK call is what configures a
-  dead-letter queue. The queue is created without the property and the omission is recorded in
-  `stack.ignoredProperties`.
 - A queue policy is set through the `Policy` attribute only. `AddPermission` and `RemovePermission`,
   shorthands for writing one statement of it, are absent.
 - `GetQueueAttributes` reports the `Policy` string that was set. Real SQS re-serialises the document
@@ -1165,6 +1200,8 @@ Current documented limitations:
 - Encryption is left out. `KmsMasterKeyId`, `KmsDataKeyReusePeriodSeconds` and
   `SqsManagedSseEnabled` are recorded on an `AWS::SQS::Queue` and applied to nothing, and message
   bodies are held in process memory as they were sent. Anything sharing the process can read them.
+  The one thing read off them is the range on `KmsDataKeyReusePeriodSeconds`, so a template real
+  SQS refuses does not deploy here.
 - Tags are left out. `TagQueue`, `UntagQueue` and `ListQueueTags` are absent, and `CreateQueue`
   refuses a `tags` parameter rather than dropping it.
 - `SenderId` is left out, because a simulated caller has no user or role id to report it as.

package/llms.txt

@@ -14,6 +14,7 @@ The same pages are on the web at https://yulinsim.dev/ for whichever release is
 - [API Gateway HTTP APIs](docs/services/apigatewayv2/README.md): Simulated API Gateway HTTP API usage docs
 - [API Gateway REST APIs](docs/services/apigateway/README.md): Simulated API Gateway REST API usage docs
 - [Athena](docs/services/athena/README.md): Simulated Amazon Athena usage docs
+- [AWS Backup](docs/services/backup/README.md): Simulated AWS Backup usage docs
 - [Bedrock](docs/services/bedrock/README.md): Simulated Amazon Bedrock usage docs
 - [CloudFormation](docs/services/cloudformation/README.md): Simulated CloudFormation usage docs
 - [CloudFront](docs/services/cloudfront/README.md): Simulated CloudFront usage docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.0",
+  "version": "1.21.2",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",
@@ -65,6 +65,10 @@
       "import": "./dist/service/bedrock/index.js",
       "types": "./dist/service/bedrock/index.d.ts"
     },
+    "./backup": {
+      "import": "./dist/service/backup/index.js",
+      "types": "./dist/service/backup/index.d.ts"
+    },
     "./cloudformation": {
       "import": "./dist/service/cloudformation/index.js",
       "types": "./dist/service/cloudformation/index.d.ts"
@@ -231,6 +235,7 @@
     "@aws-sdk/client-api-gateway": "^3.1112.0",
     "@aws-sdk/client-apigatewayv2": "^3.1101.0",
     "@aws-sdk/client-athena": "^3.1115.0",
+    "@aws-sdk/client-backup": "^3.1121.0",
     "@aws-sdk/client-bedrock-runtime": "^3.1115.0",
     "@aws-sdk/client-cloudformation": "^3.1101.0",
     "@aws-sdk/client-cloudfront": "^3.1101.0",
@@ -268,7 +273,7 @@
     "@aws-sdk/lib-storage": "^3.1112.0",
     "@aws-sdk/s3-request-presigner": "^3.1101.0",
     "@eslint/js": "^10.0.1",
-    "@kensio/smartass": "^1.37.0",
+    "@kensio/smartass": "^1.37.7",
     "@semantic-release/exec": "7.1.0",
     "@smithy/signature-v4": "^5.6.12",
     "@smithy/smithy-client": "^4.14.16",