@trycourier/courier 3.10.1 → 3.13.1

package/CHANGELOG.md

@@ -5,10 +5,24 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][unreleased]
 
+## [3.13.1] - 2022-06-03
+
+- adds provider and channel timeout
+
+## [3.12.0] - 2022-03-31
+
+- adds support for message trace id (`message.metadata.trace_id`)
+
+## [3.11.0] - 2022-03-23
+
+- adds support for `audiences`
+
 ## [3.10.1] - 2022-03-20
+
 - adds support for messages timeout (`message.timeout`)
 
 ## [3.10.0] - 2020-03-24
+
 - adds support for messages brand_id (`message.brand_id`)
 
 ## [3.9.0] - 2022-03-17
@@ -224,7 +238,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## v1.0.1 - 2019-07-12
 
-[unreleased]: https://github.com/trycourier/courier-node/compare/v3.9.0...HEAD
+[unreleased]: https://github.com/trycourier/courier-node/compare/v3.11.0...HEAD
+[v3.11.0]: https://github.com/trycourier/courier-node/compare/v3.10.0...v3.11.0
+[v3.10.0]: https://github.com/trycourier/courier-node/compare/v3.9.0...v3.10.0
 [v3.9.0]: https://github.com/trycourier/courier-node/compare/v3.8.0...v3.9.0
 [v3.8.0]: https://github.com/trycourier/courier-node/compare/v3.7.0...v3.8.0
 [v3.7.0]: https://github.com/trycourier/courier-node/compare/v3.6.0...v3.7.0

package/README.md

@@ -183,6 +183,29 @@ const { requestId } = await courier.send({
     },
   },
 });
+
+// Example: send a basic message with a trace id
+const { requestId } = await courier.send({
+  message: {
+    to: {
+      data: {
+        name: "Marty",
+      },
+      email: "marty_mcfly@email.com",
+    },
+    content: {
+      title: "Back to the Future",
+      body: "Oh my {{name}}, we need 1.21 Gigawatts!",
+    },
+    routing: {
+      method: "single",
+      channels: ["email"],
+    },
+    metadata: {
+      trace_id: "ravenclaw-for-the-win"
+    },
+  },
+});
 ```
 
 ## Environment Variables
@@ -217,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);
@@ -619,6 +706,42 @@ async function run() {
 run();
 ```
 
+### Audiences
+
+Audiences APIs are used to create, get, update, and delete audiences. A Courier Audience is a dynamic group of users (created using Courier's Profile API) that matches a set of criteria. Audience is reactive to changes in the user's profile. As you change user profile using `profiles` API, the audience will be updated accordingly. You will not have to maintain a list of users in your audience. Courier takes care of that for you. If you have potentially large set of users, you first create an audience and then use the audience's id to retrieve the list of users. Once you satified with the calculated list of users, you can use the `audienceId` to send notification using `send` API.
+
+```ts
+// Example: create audience which would allow sending notification to all users that match the given filter criteria
+const { audienceId } = await courier.audiences.put({
+  id: "<AUDIENCE_ID>",
+  filter: {
+    operator: "EQ",
+    path: "title",
+    value: "Software Engineer",
+  },
+});
+
+// To retrieve list of members in a given audience, you can use the following:
+const { items: audienceMembers } = await courier.audiences.listMembers(
+  audienceId
+);
+
+// To send a notification to all users that match the given filter criteria, you can use the following:
+const { requestId } = await courier.send({
+  message: {
+    template: "<TEMPLATE_OR_EVENT_ID>", // This can be inline content as well
+    to: {
+      audience_id: audienceId,
+    },
+    data: {}, // optional
+    brand_id: "<BRAND_ID>", //optional
+    routing: {},
+    channels: {}, // optional
+    providers: {}, // optional
+  },
+});
+```
+
 ## License
 
 [MIT License](http://www.opensource.org/licenses/mit-license.php)

package/lib/audiences/index.d.ts

@@ -0,0 +1,9 @@
+import { ICourierClientConfiguration } from "../types";
+import * as AudienceTypes from "./types";
+export declare const audiences: (options: ICourierClientConfiguration) => {
+    delete: (audienceId: string) => Promise<void>;
+    get: (audienceId: string) => Promise<AudienceTypes.IAudience>;
+    listAudiences: () => Promise<AudienceTypes.IAudienceListResponse>;
+    listMembers: (audienceId: string) => Promise<AudienceTypes.IAudienceMemberListResponse>;
+    put: (audience: Omit<AudienceTypes.IAudience, "created_at" | "updated_at">) => Promise<AudienceTypes.IAudience>;
+};

package/lib/audiences/index.js

@@ -0,0 +1,108 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.audiences = void 0;
+var deleteAudience = function (options) { return function (audienceId) { return __awaiter(void 0, void 0, void 0, function () {
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0: return [4 /*yield*/, options.httpClient.delete("/audiences/" + audienceId)];
+            case 1:
+                _a.sent();
+                return [2 /*return*/];
+        }
+    });
+}); }; };
+var getAudience = function (options) {
+    return function (audienceId) { return __awaiter(void 0, void 0, void 0, function () {
+        var response;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, options.httpClient.get("/audiences/" + audienceId)];
+                case 1:
+                    response = _a.sent();
+                    return [2 /*return*/, response.data.audience];
+            }
+        });
+    }); };
+};
+var listAudiences = function (options) {
+    return function () { return __awaiter(void 0, void 0, void 0, function () {
+        var response;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, options.httpClient.get("/audiences")];
+                case 1:
+                    response = _a.sent();
+                    return [2 /*return*/, response.data];
+            }
+        });
+    }); };
+};
+var listMembers = function (options) {
+    return function (audienceId) { return __awaiter(void 0, void 0, void 0, function () {
+        var response;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, options.httpClient.get("/audiences/" + audienceId + "/members")];
+                case 1:
+                    response = _a.sent();
+                    return [2 /*return*/, response.data];
+            }
+        });
+    }); };
+};
+var putAudience = function (options) {
+    return function (audience) { return __awaiter(void 0, void 0, void 0, function () {
+        var response;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, options.httpClient.get("/audiences/" + audience.id)];
+                case 1:
+                    response = _a.sent();
+                    return [2 /*return*/, response.data.audience];
+            }
+        });
+    }); };
+};
+exports.audiences = function (options) { return ({
+    delete: deleteAudience(options),
+    get: getAudience(options),
+    listAudiences: listAudiences(options),
+    listMembers: listMembers(options),
+    put: putAudience(options),
+}); };

package/lib/audiences/types.d.ts

@@ -0,0 +1,61 @@
+export declare type ComparisonOperator = "EQ" | "GT" | "GTE" | "INCLUDES" | "LT" | "LTE" | "NEQ" | "OMIT";
+export declare type LogicalOperator = "AND" | "OR";
+export declare type Operator = ComparisonOperator | LogicalOperator;
+declare type Without<T, U> = {
+    [P in Exclude<keyof T, keyof U>]?: never;
+};
+declare type XOR<T, U> = T | U extends object ? (Without<T, U> & U) | (Without<U, T> & T) : T | U;
+interface IBaseFilterConfig {
+    operator: Operator;
+}
+interface ISingleFilterConfig extends IBaseFilterConfig {
+    path: string;
+    value: string;
+}
+interface INestedFilterConfig extends IBaseFilterConfig {
+    rules: FilterConfig[];
+}
+export declare type FilterConfig = XOR<ISingleFilterConfig, INestedFilterConfig>;
+export interface IAudience {
+    created_at: string;
+    description?: string;
+    id: string;
+    name?: string;
+    filter: FilterConfig;
+    updated_at: string;
+}
+export interface IAudienceMember {
+    added_at: string;
+    audience_id: string;
+    audience_version: number;
+    member_id: string;
+    reason: string;
+}
+export interface IAudienceListResponse {
+    items: IAudience[];
+    paging: {
+        cursor: string;
+        more: boolean;
+    };
+}
+export interface IAudienceMemberGetResponse {
+    audienceMember: IAudienceMember;
+}
+export interface IAudienceMemberListResponse {
+    items: IAudienceMember[];
+    paging: {
+        cursor: string;
+        more: boolean;
+    };
+}
+export interface IAudiencePutResponse {
+    audience: IAudience;
+}
+export interface ICourierClientAudiences {
+    delete: (id: string) => Promise<void>;
+    get: (id: string) => Promise<IAudience>;
+    listAudiences: () => Promise<IAudienceListResponse>;
+    listMembers: (id: string) => Promise<IAudienceMemberListResponse>;
+    put: (audience: Omit<IAudience, "created_at" | "updated_at">) => Promise<IAudience>;
+}
+export {};

package/lib/audiences/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/client.js

@@ -37,6 +37,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.client = void 0;
+var audiences_1 = require("./audiences");
 var automations_1 = require("./automations");
 var brands_1 = require("./brands");
 var bulk_1 = require("./bulk");
@@ -98,8 +99,8 @@ var getMessages = function (options) {
                             notification: params === null || params === void 0 ? void 0 : params.notificationId,
                             recipient: params === null || params === void 0 ? void 0 : params.recipientId,
                             status: params === null || params === void 0 ? void 0 : params.status,
-                            tags: params === null || params === void 0 ? void 0 : params.tags
-                        }
+                            tags: params === null || params === void 0 ? void 0 : params.tags,
+                        },
                     })];
                 case 1:
                     res = _a.sent();
@@ -111,6 +112,7 @@ var getMessages = function (options) {
 exports.client = function (options) {
     return {
         addRecipientToLists: profile_1.addRecipientToLists(options),
+        audiences: audiences_1.audiences(options),
         automations: automations_1.automations(options),
         bulk: bulk_1.bulk(options),
         createBrand: brands_1.createBrand(options),
@@ -131,6 +133,6 @@ exports.client = function (options) {
         removeRecipientFromAllLists: profile_1.removeRecipientFromAllLists(options),
         replaceBrand: brands_1.replaceBrand(options),
         replaceProfile: profile_1.replaceProfile(options),
-        send: send_1.send(options)
+        send: send_1.send(options),
     };
 };

package/lib/send/types.d.ts

@@ -222,6 +222,10 @@ interface InvalidUserRecipient {
 declare type UserRecipientType = Record<string, unknown> & {
     [key in keyof InvalidUserRecipient]?: never;
 };
+export interface AudienceRecipient {
+    audience_id: string;
+    data?: MessageData;
+}
 export interface UserRecipient extends UserRecipientType {
     data?: MessageData;
     email?: string;
@@ -230,15 +234,19 @@ export interface UserRecipient extends UserRecipientType {
     phone_number?: string;
     preferences?: IProfilePreferences;
 }
-export declare type Recipient = ListRecipient | ListPatternRecipient | UserRecipient;
+export declare type Recipient = AudienceRecipient | ListRecipient | ListPatternRecipient | UserRecipient;
 export declare type MessageRecipient = Recipient | Recipient[];
 export interface ElementalContentSugar {
     body?: string;
     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";
@@ -307,6 +315,9 @@ export interface MessageChannels {
             channel?: number;
         };
         override?: MessageChannelEmailOverride | MessageChannelPushOverride;
+        metadata?: {
+            utm?: UTM;
+        };
     };
 }
 export interface Routing {
@@ -325,17 +336,22 @@ 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 {
     content: Content;

package/lib/types.d.ts

@@ -1,4 +1,5 @@
 import { AxiosRequestConfig } from "axios";
+import { ICourierClientAudiences } from "./audiences/types";
 import { ICourierClientAutomations } from "./automations/types";
 import { ICourierClientBulk } from "./bulk/types";
 import { ICourierClientLists, ICourierList, ICourierRecipientSubscriptionsResponse } from "./lists/types";
@@ -286,6 +287,7 @@ export interface ICourierBrandGetAllResponse {
 export declare type SendResponse<T extends ICourierSendParameters | ICourierSendMessageParameters> = T extends ICourierSendParameters ? ICourierSendResponse : ICourierSendMessageResponse;
 export interface ICourierClient {
     addRecipientToLists: (params: ICourierProfileListsPostParameters) => Promise<ICourierProfilePostResponse>;
+    audiences: ICourierClientAudiences;
     automations: ICourierClientAutomations;
     bulk: ICourierClientBulk;
     createBrand: (params: ICourierBrandParameters, config?: ICourierBrandPostConfig) => Promise<ICourierBrand>;

package/package.json

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