@allthings/cloud-toolkit 5.2.1 → 5.3.0

package/README.md

@@ -13,9 +13,54 @@ Standardizes the setup of aws, Datadog and other things
 
 ### ses
 
-| function | parameters | description                                    |
-| -------- | ---------- | ---------------------------------------------- |
-| sendMail | options    | Sends an email via SES or provided SMTP config |
+| function     | parameters | description                                                              |
+| ------------ | ---------- | ------------------------------------------------------------------------ |
+| sendMail     | options    | Sends an email via SES or provided SMTP config                           |
+| emailHeaders | options    | Builds the deliverability headers for one message, for `options.headers` |
+
+`emailHeaders` is opt-in and pure: a message only carries these headers when a
+caller builds them. Every header is omitted when the value it needs is not given.
+
+| header                                     | from                                                    |
+| ------------------------------------------ | ------------------------------------------------------- |
+| `Auto-Submitted: auto-generated`           | `suppressAutoResponses` (default true)                  |
+| `X-Auto-Response-Suppress: OOF, AutoReply` | `suppressAutoResponses` (default true)                  |
+| `Content-Language`                         | `contentLanguage`                                       |
+| `Feedback-ID`                              | `feedbackId`                                            |
+| `List-Id`                                  | `listId`                                                |
+| `List-Unsubscribe`                         | `unsubscribeUrl`                                        |
+| `List-Unsubscribe-Post`                    | `oneClickUnsubscribe` (default true, https target only) |
+| `Precedence: bulk`                         | `bulk` (default false)                                  |
+| `X-Entity-Ref-ID`                          | `entityReferenceId`                                     |
+
+```ts
+import { emailHeaders, ses } from '@allthings/cloud-toolkit/ses'
+
+await ses({}).sendMail({
+  from: 'noreply@allthings.me',
+  headers: emailHeaders({
+    contentLanguage: 'de-DE',
+    entityReferenceId: notificationId,
+    listId: 'AppNotificationDigest.notifications.allthings.me',
+    unsubscribeUrl: `${siteUrl}/settings`,
+    // the URL cannot answer an unauthenticated POST yet
+    oneClickUnsubscribe: false,
+  }),
+  html,
+  subject,
+  text,
+  to,
+})
+```
+
+The two suppression headers stop out of office autoresponders from replying to a
+`noreply@` address. `X-Auto-Response-Suppress` is deliberately `OOF, AutoReply`
+rather than `All`, so delivery status notifications keep reaching SES and its
+suppression list stays accurate.
+
+`Precedence: bulk` is off by default. Only legacy `vacation(1)` style responders
+act on it, Gmail and Microsoft ignore it, and some filters read it as a mild
+negative — so leave it off for anything that has to arrive.
 
 ### lambda
 
@@ -37,11 +82,11 @@ Standardizes the setup of aws, Datadog and other things
 
 ### sqs
 
-| function        | parameters                                                                      | description                                              |
-| --------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| deleteQueueItem | queueUrl<br/>receiptHandle                                                      | Deletes item from queue                                  |
-| getQueueItems   | queueUrl<br/>maxNumberOfMessages (optional)                                     | Retrieves items from queue                               |
-| getQueueUrl     | queueName                                                                       | Returns queue url which is needed for all other requests |
+| function        | parameters                                                                                                 | description                                              |
+| --------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| deleteQueueItem | queueUrl<br/>receiptHandle                                                                                 | Deletes item from queue                                  |
+| getQueueItems   | queueUrl<br/>maxNumberOfMessages (optional)                                                                | Retrieves items from queue                               |
+| getQueueUrl     | queueName                                                                                                  | Returns queue url which is needed for all other requests |
 | sendMessage     | queueUrl<br/>message<br/>fifoSettings(optional)<br/>messageAttributes(optional)<br/>messageDelay(optional) | Creates an item in the queue                             |
 
 ### logger

package/dist/lib.cjs.js

@@ -904,6 +904,25 @@ const dynamodb = (userConfig) => {
     };
 };
 
+const AUTO_RESPONSE_SUPPRESSION_HEADERS = {
+    'Auto-Submitted': 'auto-generated',
+    'X-Auto-Response-Suppress': 'OOF, AutoReply',
+};
+const emailHeaders = ({ bulk = false, contentLanguage, entityReferenceId, feedbackId, listId, oneClickUnsubscribe = true, suppressAutoResponses = true, unsubscribeUrl, } = {}) => Object.fromEntries(Object.entries({
+    ...(suppressAutoResponses ? AUTO_RESPONSE_SUPPRESSION_HEADERS : {}),
+    'Content-Language': contentLanguage?.trim(),
+    'Feedback-ID': feedbackId?.trim(),
+    'List-Id': listId?.trim().replace(/^<*([^<>].*?)>*$/, '<$1>'),
+    'List-Unsubscribe': unsubscribeUrl
+        ?.trim()
+        .replace(/^<*([^<>].*?)>*$/, '<$1>'),
+    'List-Unsubscribe-Post': oneClickUnsubscribe &&
+        /^<?https:/i.test(unsubscribeUrl?.trim() ?? '') &&
+        'List-Unsubscribe=One-Click',
+    Precedence: bulk && 'bulk',
+    'X-Entity-Ref-ID': entityReferenceId?.trim(),
+}).filter(([, value]) => value));
+
 const invokeLambda = async (lambdaClient, config, invocationType, payload) => {
     try {
         const invokeCommand = new clientLambda.InvokeCommand({
@@ -1190,6 +1209,7 @@ Object.defineProperty(exports, "Logger", {
     enumerable: true,
     get: function () { return winston.Logger; }
 });
+exports.AUTO_RESPONSE_SUPPRESSION_HEADERS = AUTO_RESPONSE_SUPPRESSION_HEADERS;
 exports.ClientError = ClientError;
 exports.DEFAULT_PARAMETER_STORE_CLIENT_CONFIG = DEFAULT_CLIENT_CONFIG$1;
 exports.DEFAULT_SES_CLIENT_CONFIG = DEFAULT_CLIENT_CONFIG;
@@ -1200,6 +1220,7 @@ exports.atob = atob;
 exports.btoa = btoa;
 exports.deepFlatten = deepFlatten;
 exports.dynamodb = dynamodb;
+exports.emailHeaders = emailHeaders;
 exports.flatten = flatten;
 exports.lambda = lambda;
 exports.logger = logger;

package/dist/lib.esm.mjs

@@ -882,6 +882,25 @@ const dynamodb = (userConfig) => {
     };
 };
 
+const AUTO_RESPONSE_SUPPRESSION_HEADERS = {
+    'Auto-Submitted': 'auto-generated',
+    'X-Auto-Response-Suppress': 'OOF, AutoReply',
+};
+const emailHeaders = ({ bulk = false, contentLanguage, entityReferenceId, feedbackId, listId, oneClickUnsubscribe = true, suppressAutoResponses = true, unsubscribeUrl, } = {}) => Object.fromEntries(Object.entries({
+    ...(suppressAutoResponses ? AUTO_RESPONSE_SUPPRESSION_HEADERS : {}),
+    'Content-Language': contentLanguage?.trim(),
+    'Feedback-ID': feedbackId?.trim(),
+    'List-Id': listId?.trim().replace(/^<*([^<>].*?)>*$/, '<$1>'),
+    'List-Unsubscribe': unsubscribeUrl
+        ?.trim()
+        .replace(/^<*([^<>].*?)>*$/, '<$1>'),
+    'List-Unsubscribe-Post': oneClickUnsubscribe &&
+        /^<?https:/i.test(unsubscribeUrl?.trim() ?? '') &&
+        'List-Unsubscribe=One-Click',
+    Precedence: bulk && 'bulk',
+    'X-Entity-Ref-ID': entityReferenceId?.trim(),
+}).filter(([, value]) => value));
+
 const invokeLambda = async (lambdaClient, config, invocationType, payload) => {
     try {
         const invokeCommand = new InvokeCommand({
@@ -1164,4 +1183,4 @@ const logger = (config) => {
     });
 };
 
-export { ClientError, DEFAULT_CLIENT_CONFIG$1 as DEFAULT_PARAMETER_STORE_CLIENT_CONFIG, DEFAULT_CLIENT_CONFIG as DEFAULT_SES_CLIENT_CONFIG, ServerError, alagarr, asyncReduce, atob, btoa, deepFlatten, dynamodb, flatten, lambda, logger, parameterStore, partial, ses, splitEvery, sqs, times, until };
+export { AUTO_RESPONSE_SUPPRESSION_HEADERS, ClientError, DEFAULT_CLIENT_CONFIG$1 as DEFAULT_PARAMETER_STORE_CLIENT_CONFIG, DEFAULT_CLIENT_CONFIG as DEFAULT_SES_CLIENT_CONFIG, ServerError, alagarr, asyncReduce, atob, btoa, deepFlatten, dynamodb, emailHeaders, flatten, lambda, logger, parameterStore, partial, ses, splitEvery, sqs, times, until };

package/dist/ses.cjs.js

@@ -3,6 +3,25 @@
 var clientSesv2 = require('@aws-sdk/client-sesv2');
 var nodemailer = require('nodemailer');
 
+const AUTO_RESPONSE_SUPPRESSION_HEADERS = {
+    'Auto-Submitted': 'auto-generated',
+    'X-Auto-Response-Suppress': 'OOF, AutoReply',
+};
+const emailHeaders = ({ bulk = false, contentLanguage, entityReferenceId, feedbackId, listId, oneClickUnsubscribe = true, suppressAutoResponses = true, unsubscribeUrl, } = {}) => Object.fromEntries(Object.entries({
+    ...(suppressAutoResponses ? AUTO_RESPONSE_SUPPRESSION_HEADERS : {}),
+    'Content-Language': contentLanguage?.trim(),
+    'Feedback-ID': feedbackId?.trim(),
+    'List-Id': listId?.trim().replace(/^<*([^<>].*?)>*$/, '<$1>'),
+    'List-Unsubscribe': unsubscribeUrl
+        ?.trim()
+        .replace(/^<*([^<>].*?)>*$/, '<$1>'),
+    'List-Unsubscribe-Post': oneClickUnsubscribe &&
+        /^<?https:/i.test(unsubscribeUrl?.trim() ?? '') &&
+        'List-Unsubscribe=One-Click',
+    Precedence: bulk && 'bulk',
+    'X-Entity-Ref-ID': entityReferenceId?.trim(),
+}).filter(([, value]) => value));
+
 const DEFAULT_CLIENT_CONFIG = {
     clientConfig: { region: 'eu-west-1' },
 };
@@ -56,5 +75,7 @@ const ses = (userConfig) => {
     };
 };
 
+exports.AUTO_RESPONSE_SUPPRESSION_HEADERS = AUTO_RESPONSE_SUPPRESSION_HEADERS;
 exports.DEFAULT_CLIENT_CONFIG = DEFAULT_CLIENT_CONFIG;
+exports.emailHeaders = emailHeaders;
 exports.ses = ses;

package/dist/ses.esm.mjs

@@ -1,6 +1,25 @@
 import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2';
 import { createTransport } from 'nodemailer';
 
+const AUTO_RESPONSE_SUPPRESSION_HEADERS = {
+    'Auto-Submitted': 'auto-generated',
+    'X-Auto-Response-Suppress': 'OOF, AutoReply',
+};
+const emailHeaders = ({ bulk = false, contentLanguage, entityReferenceId, feedbackId, listId, oneClickUnsubscribe = true, suppressAutoResponses = true, unsubscribeUrl, } = {}) => Object.fromEntries(Object.entries({
+    ...(suppressAutoResponses ? AUTO_RESPONSE_SUPPRESSION_HEADERS : {}),
+    'Content-Language': contentLanguage?.trim(),
+    'Feedback-ID': feedbackId?.trim(),
+    'List-Id': listId?.trim().replace(/^<*([^<>].*?)>*$/, '<$1>'),
+    'List-Unsubscribe': unsubscribeUrl
+        ?.trim()
+        .replace(/^<*([^<>].*?)>*$/, '<$1>'),
+    'List-Unsubscribe-Post': oneClickUnsubscribe &&
+        /^<?https:/i.test(unsubscribeUrl?.trim() ?? '') &&
+        'List-Unsubscribe=One-Click',
+    Precedence: bulk && 'bulk',
+    'X-Entity-Ref-ID': entityReferenceId?.trim(),
+}).filter(([, value]) => value));
+
 const DEFAULT_CLIENT_CONFIG = {
     clientConfig: { region: 'eu-west-1' },
 };
@@ -54,4 +73,4 @@ const ses = (userConfig) => {
     };
 };
 
-export { DEFAULT_CLIENT_CONFIG, ses };
+export { AUTO_RESPONSE_SUPPRESSION_HEADERS, DEFAULT_CLIENT_CONFIG, emailHeaders, ses };

package/dist/src/aws/emailHeaders.d.ts

@@ -0,0 +1,16 @@
+import { Headers } from 'nodemailer/lib/mailer';
+export declare const AUTO_RESPONSE_SUPPRESSION_HEADERS: {
+    readonly 'Auto-Submitted': "auto-generated";
+    readonly 'X-Auto-Response-Suppress': "OOF, AutoReply";
+};
+export interface IEmailHeaderOptions {
+    readonly bulk?: boolean;
+    readonly contentLanguage?: string;
+    readonly entityReferenceId?: string;
+    readonly feedbackId?: string;
+    readonly listId?: string;
+    readonly oneClickUnsubscribe?: boolean;
+    readonly suppressAutoResponses?: boolean;
+    readonly unsubscribeUrl?: string;
+}
+export declare const emailHeaders: ({ bulk, contentLanguage, entityReferenceId, feedbackId, listId, oneClickUnsubscribe, suppressAutoResponses, unsubscribeUrl, }?: IEmailHeaderOptions) => Headers;

package/dist/src/aws/index.d.ts

@@ -1,4 +1,5 @@
 export { dynamodb, IDynamoDBConfig, IDynamoDBInstance, IUnprocessedItems, TBatchWriteItems, TDeleteItem, TGetItem, TPutItem, TQueryTable, TScanTable, TUpdateItem, } from './dynamodb';
+export { AUTO_RESPONSE_SUPPRESSION_HEADERS, emailHeaders, IEmailHeaderOptions, } from './emailHeaders';
 export { ILambda, ILambdaInstance, lambda, TInvokeLambda } from './lambda';
 export { DEFAULT_CLIENT_CONFIG as DEFAULT_PARAMETER_STORE_CLIENT_CONFIG, IParameterStore, IParameterStoreInstance, parameterStore, TGetSecret, TGetSecrets, } from './parameterStore';
 export { DEFAULT_CLIENT_CONFIG as DEFAULT_SES_CLIENT_CONFIG, IEmailAttachment, IEmailOptions, ISES, ISESInstance, ses, TSendMail, } from './ses';

package/dist/src/aws/ses.d.ts

@@ -33,3 +33,4 @@ export interface ISESInstance {
     sendMail: TSendMail;
 }
 export declare const ses: (userConfig: ISES) => ISESInstance;
+export { AUTO_RESPONSE_SUPPRESSION_HEADERS, emailHeaders, IEmailHeaderOptions, } from './emailHeaders';

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 export { Alagarr, alagarr, ClientError, HandlerFunction, IInterfaceAlagarrOptions, IInterfaceHeaders, IInterfaceQueryParameters, IInterfaceRequest, IInterfaceResponse, ServerError, } from './alagarr';
-export { DEFAULT_PARAMETER_STORE_CLIENT_CONFIG, DEFAULT_SES_CLIENT_CONFIG, dynamodb, IDynamoDBConfig, IDynamoDBInstance, IEmailAttachment, IEmailOptions, ILambda, ILambdaInstance, IParameterStore, IParameterStoreInstance, ISES, ISESInstance, ISQS, ISQSInstance, IUnprocessedItems, lambda, parameterStore, ses, sqs, TBatchWriteItems, TDeleteItem, TDeleteQueueItem, TGetItem, TGetQueueItems, TGetQueueUrl, TGetSecret, TGetSecrets, TInvokeLambda, TPutItem, TQueryTable, TScanTable, TSendMail, TSendMessage, TUpdateItem, } from './aws';
+export { AUTO_RESPONSE_SUPPRESSION_HEADERS, DEFAULT_PARAMETER_STORE_CLIENT_CONFIG, DEFAULT_SES_CLIENT_CONFIG, dynamodb, emailHeaders, IDynamoDBConfig, IDynamoDBInstance, IEmailAttachment, IEmailHeaderOptions, IEmailOptions, ILambda, ILambdaInstance, IParameterStore, IParameterStoreInstance, ISES, ISESInstance, ISQS, ISQSInstance, IUnprocessedItems, lambda, parameterStore, ses, sqs, TBatchWriteItems, TDeleteItem, TDeleteQueueItem, TGetItem, TGetQueueItems, TGetQueueUrl, TGetSecret, TGetSecrets, TInvokeLambda, TPutItem, TQueryTable, TScanTable, TSendMail, TSendMessage, TUpdateItem, } from './aws';
 export { atob, btoa } from './base64';
 export { logger } from './logger/logger';
 export { asyncReduce, deepFlatten, flatten, List, partial, splitEvery, times, until, } from './utils';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allthings/cloud-toolkit",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "",
   "author": "Allthings GmbH",
   "keywords": [