@trycourier/courier 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -5,6 +5,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][unreleased]
 
+- adds support for granular timeouts for channel and providers
+- adds support for change and provider utm metadata (`channels.metadata.utm` and `providers.metadata.utm`) that augments action blocks links
+
 ## [3.12.0] - 2022-03-31
 
 - adds support for message trace id (`message.metadata.trace_id`)

package/README.md

@@ -240,6 +240,70 @@ async function run() {
   });
   console.log(requestId);
 
+  // Example: send message with utm metadata
+  const { requestId } = await courier.send({
+    message: {
+      template: "<TEMPLATE_OR_EVENT_ID>",
+      to: {...},
+      routing: {
+        method: "single",
+        channels: ["email"],
+      },
+      channels: {
+        email: {
+          routing_method: "all",
+          providers: ["sendgrid", "sns"],
+          metadata: {
+            utm: {
+              medium: "f",
+              campaign: "g",
+            },
+          },
+        },
+      },
+      providers: {
+        sns: {
+          metadata: {
+            utm: {
+              medium: "h",
+            },
+          },
+        },
+      }, // optional
+      metadata: {
+        utm: {
+          source: "a",
+          medium: "b",
+          campaign: "c",
+        },
+      },
+      timeout: {
+        message: 300000,
+        channel: {
+          email: 1000 // 1 second
+        }
+      }
+    },
+  });
+
+/**
+ * If the template or content contains any action blocks, the hyperlinks will be augmented with utm compliant query parameters.
+ *
+ * The resulting link of an action block sent through sendgrid would be:
+ * www.example.com?utm_source=a&utm_medium=f&utm_campaign=g
+ *
+ * While the resulting link of an action block sent through sns would be:
+ * www.example.com?utm_source=a&utm_medium=h&utm_campaign=g
+ *
+ * Notice that provider metadata supersedes channel metadata and channel metadata supersedes message metadata
+ *
+ **/
+
+/**
+ * If the message includes a timeout property we will start timing out messages after the first attempt.
+ * We are able to timeout complete channels or specific providers.
+ **/
+
   // Example: get a message status
   const messageStatus = await courier.getMessage(requestId);
   console.log(messageStatus);
@@ -651,9 +715,9 @@ Audiences APIs are used to create, get, update, and delete audiences. A Courier
 const { audienceId } = await courier.audiences.put({
   id: "<AUDIENCE_ID>",
   filter: {
-    "operator": "EQ",
-    "path": "title",
-    "value": "Software Engineer",
+    operator: "EQ",
+    path: "title",
+    value: "Software Engineer",
   },
 });
 

package/lib/send/types.d.ts

@@ -241,8 +241,12 @@ export interface ElementalContentSugar {
     title?: string;
 }
 export interface Timeout {
-    provider?: number;
-    channel?: number;
+    provider?: {
+        [provider: string]: number;
+    };
+    channel?: {
+        [channel: string]: number;
+    };
     message?: number;
     escalation?: number;
     criteria?: "no-escalation" | "delivered" | "viewed" | "engaged";
@@ -311,6 +315,9 @@ export interface MessageChannels {
             channel?: number;
         };
         override?: MessageChannelEmailOverride | MessageChannelPushOverride;
+        metadata?: {
+            utm?: UTM;
+        };
     };
 }
 export interface Routing {
@@ -329,17 +336,21 @@ export interface RoutingStrategyProvider<T = Record<string, any>> {
     name: string;
     config?: T;
     if?: string;
+    metadata?: {
+        utm?: UTM;
+    };
+}
+export interface UTM {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
 }
 export interface MessageMetadata {
     event?: string;
     tags?: string[];
-    utm?: {
-        source?: string;
-        medium?: string;
-        campaign?: string;
-        term?: string;
-        content?: string;
-    };
+    utm?: UTM;
     trace_id?: string;
 }
 export interface ContentMessage extends BaseMessage {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycourier/courier",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "A node.js module for communicating with the Courier REST API.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",