@clipboard-health/notifications 2.4.15 → 2.4.19

package/README.md

@@ -86,9 +86,12 @@ Send notifications through third-party providers.
           * service instead of this manual calculation.
           */
          expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
-         // Set idempotencyKey at enqueue-time so it remains stable across job retries.
-         idempotencyKey: {
-           resourceId: "event-123",
+         // Set idempotencyKeyParts at enqueue-time so it remains stable across job retries.
+         idempotencyKeyParts: {
+           resource: {
+             type: "account",
+             id: "4e3ffeec-1426-4e54-ad28-83246f8f4e7c",
+           },
          },
          // Set recipients at enqueue-time so they respect our notification provider's limits.
          recipients: ["userId-1"],

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@clipboard-health/notifications",
   "description": "Send notifications through third-party providers.",
-  "version": "2.4.15",
+  "version": "2.4.19",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "dependencies": {
-    "@clipboard-health/background-jobs-adapter": "1.4.15",
-    "@clipboard-health/phone-number": "1.4.15",
-    "@clipboard-health/util-ts": "4.4.15",
+    "@clipboard-health/background-jobs-adapter": "1.4.19",
+    "@clipboard-health/phone-number": "1.4.19",
+    "@clipboard-health/util-ts": "4.4.19",
     "@knocklabs/node": "1.24.0",
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@clipboard-health/testing-core": "1.4.15",
+    "@clipboard-health/testing-core": "1.4.19",
     "type-fest": "5.2.0"
   },
   "keywords": [],

package/src/lib/internal/triggerIdempotencyKeyParamsToHash.d.ts

@@ -1,6 +1,6 @@
 import { type TriggerIdempotencyKeyParams } from "../triggerIdempotencyKey";
-interface HashParams extends TriggerIdempotencyKeyParams {
+type HashParams = TriggerIdempotencyKeyParams & {
     workplaceId?: string | undefined;
-}
+};
 export declare function triggerIdempotencyKeyParamsToHash(params: HashParams): string;
 export {};

package/src/lib/internal/triggerIdempotencyKeyParamsToHash.js

@@ -10,7 +10,11 @@ function toSorted(params) {
         chunk: params.chunk,
         eventOccurredAt: params.eventOccurredAt,
         recipients: [...params.recipients].sort(),
-        resourceId: params.resourceId,
+        resourceId: "resourceId" in params
+            ? params.resourceId
+            : "resource" in params && params.resource && "id" in params.resource
+                ? params.resource.id
+                : undefined,
         workflowKey: params.workflowKey,
         workplaceId: params.workplaceId,
     };

package/src/lib/internal/triggerIdempotencyKeyParamsToHash.js.map

@@ -1 +1 @@
-{"version":3,"file":"triggerIdempotencyKeyParamsToHash.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/triggerIdempotencyKeyParamsToHash.ts"],"names":[],"mappings":";;AAOA,8EAEC;AARD,uEAAoE;AAMpE,SAAgB,iCAAiC,CAAC,MAAkB;IAClE,OAAO,IAAA,iDAAuB,EAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,QAAQ,CAAC,MAAkB;IAClC,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,UAAU,EAAE,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE;QACzC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"triggerIdempotencyKeyParamsToHash.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/triggerIdempotencyKeyParamsToHash.ts"],"names":[],"mappings":";;AAOA,8EAEC;AARD,uEAAoE;AAMpE,SAAgB,iCAAiC,CAAC,MAAkB;IAClE,OAAO,IAAA,iDAAuB,EAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,QAAQ,CAAC,MAAkB;IAClC,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,UAAU,EAAE,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE;QACzC,UAAU,EACR,YAAY,IAAI,MAAM;YACpB,CAAC,CAAC,MAAM,CAAC,UAAU;YACnB,CAAC,CAAC,UAAU,IAAI,MAAM,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ;gBAClE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE;gBACpB,CAAC,CAAC,SAAS;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC;AACJ,CAAC"}

package/src/lib/notificationJobEnqueuer.d.ts

@@ -1,7 +1,14 @@
 import { type BackgroundJobsAdapter, type EnqueueOptions, type MongoEnqueueOptions, type PostgresEnqueueOptions } from "@clipboard-health/background-jobs-adapter";
 import { type TriggerIdempotencyKey } from "./triggerIdempotencyKey";
 type EnqueueParameters = Parameters<BackgroundJobsAdapter["enqueue"]>;
+/**
+ * @deprecated Use `IdempotencyKeyParts` instead.
+ */
 export interface IdempotencyKey {
+    eventOccurredAt?: string | undefined;
+    resourceId?: string | undefined;
+}
+export type IdempotencyKeyParts = {
     /**
      * Prefer `resourceId` over `eventOccurredAt`; it's harder to misuse.
      *
@@ -10,39 +17,49 @@ export interface IdempotencyKey {
      *
      * Use `.toISOString()`.
      */
-    eventOccurredAt?: string | undefined;
+    eventOccurredAt: string;
+    resource?: undefined;
+} | {
+    eventOccurredAt?: undefined;
     /**
-     * If a resource triggered your workflow, include its unique ID.
+     * Do not include `workflowKey`, `recipients`, or `workplaceId`; they are included
+     * automatically.
      *
-     * Note: `workflowKey`, `recipients`, and `workplaceId` (if it exists in the trigger body) are
-     * included in the idempotency key automatically.
+     * If a resource triggered your workflow, include its unique ID.
      *
      * @example
      * 1. For a "meeting starts in one hour" notification, set resourceId to the meeting ID.
      * 2. For a payout notification, set resourceId to the payment ID.
      */
-    resourceId?: string | undefined;
-}
+    resource: {
+        type: string;
+        id: string;
+    };
+};
 export interface NotificationEnqueueData {
     /**
+     * @deprecated Use `idempotencyKeyParts` instead.
+     */
+    idempotencyKey?: IdempotencyKey;
+    /**
+     * Do not include `workflowKey`, `recipients`, or `workplaceId`; they are included
+     * automatically.
+     *
      * Idempotency keys prevent duplicate notifications. They should be deterministic and remain the
      * same across retry logic.
      *
-     * If you retry a request with the same idempotency key within 24 hours, the client returns the same
-     * response as the original request.
-     *
-     * Note: `workflowKey`, `recipients`, and `workplaceId` (if it exists in the trigger body) are
-     * included in the idempotency key automatically.
+     * If you retry a request with the same idempotency key within 24 hours, the client returns the
+     * same response as the original request.
      *
      * We provide this class because idempotency keys can be difficult to use correctly. If the key
-     * changes on each retry (e.g., Date.now() or uuid.v4()), it won't prevent duplicate notifications.
-     * Conversely, if you don't provide enough information, you prevent recipients from receiving
-     * notifications they otherwise should have. For example, if you use the trigger key and the
-     * recipient's ID as the idempotency key, but it's possible the recipient could receive the same
-     * notification multiple times within the idempotency key's validity window, the recipient will only
-     * receive the first notification.
+     * changes on each retry (e.g., Date.now() or uuid.v4()), it won't prevent duplicate
+     * notifications. Conversely, if you don't provide enough information, you prevent recipients from
+     * receiving notifications they otherwise should have. For example, if you use the trigger key and
+     * the recipient's ID as the idempotency key, but it's possible the recipient could receive the
+     * same notification multiple times within the idempotency key's validity window, the recipient
+     * will only receive the first notification.
      */
-    idempotencyKey: IdempotencyKey;
+    idempotencyKeyParts?: IdempotencyKeyParts;
     /** @see {@link TriggerRequest.expiresAt} */
     expiresAt: string;
     /** @see {@link TriggerBody.recipients} */
@@ -141,9 +158,12 @@ export declare class NotificationJobEnqueuer {
      *        * service instead of this manual calculation.
      *        *\/
      *       expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
-     *       // Set idempotencyKey at enqueue-time so it remains stable across job retries.
-     *       idempotencyKey: {
-     *         resourceId: "event-123",
+     *       // Set idempotencyKeyParts at enqueue-time so it remains stable across job retries.
+     *       idempotencyKeyParts: {
+     *         resource: {
+     *           type: "account",
+     *           id: "4e3ffeec-1426-4e54-ad28-83246f8f4e7c",
+     *         },
      *       },
      *       // Set recipients at enqueue-time so they respect our notification provider's limits.
      *       recipients: ["userId-1"],

package/src/lib/notificationJobEnqueuer.js

@@ -59,9 +59,12 @@ class NotificationJobEnqueuer {
      *        * service instead of this manual calculation.
      *        *\/
      *       expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
-     *       // Set idempotencyKey at enqueue-time so it remains stable across job retries.
-     *       idempotencyKey: {
-     *         resourceId: "event-123",
+     *       // Set idempotencyKeyParts at enqueue-time so it remains stable across job retries.
+     *       idempotencyKeyParts: {
+     *         resource: {
+     *           type: "account",
+     *           id: "4e3ffeec-1426-4e54-ad28-83246f8f4e7c",
+     *         },
      *       },
      *       // Set recipients at enqueue-time so they respect our notification provider's limits.
      *       recipients: ["userId-1"],
@@ -84,6 +87,7 @@ class NotificationJobEnqueuer {
         await Promise.all((0, chunkRecipients_1.chunkRecipients)({ recipients: data.recipients }).map(async ({ number, recipients }) => {
             const idempotencyKeyParams = {
                 ...data.idempotencyKey,
+                ...data.idempotencyKeyParts,
                 chunk: number,
                 recipients,
                 workflowKey: data.workflowKey,

package/src/lib/notificationJobEnqueuer.js.map

@@ -1 +1 @@
-{"version":3,"file":"notificationJobEnqueuer.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/notificationJobEnqueuer.ts"],"names":[],"mappings":";;;AAAA,uFAMmD;AAEnD,gEAA6D;AAC7D,oGAAiG;AACjG,mEAIiC;AAiHjC,MAAa,uBAAuB;IACjB,OAAO,CAA2C;IAEnE,YAAY,MAAqC;QAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAE3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoEG;IACH,KAAK,CAAC,gBAAgB,CACpB,sBAA4C,EAC5C,IAAkB,EAClB,OAAiC;QAEjC,MAAM,OAAO,CAAC,GAAG,CACf,IAAA,iCAAe,EAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE;YACpF,MAAM,oBAAoB,GAAgC;gBACxD,GAAG,IAAI,CAAC,cAAc;gBACtB,KAAK,EAAE,MAAM;gBACb,UAAU;gBACV,WAAW,EAAE,IAAI,CAAC,WAAW;aAC9B,CAAC;YAEF,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CACxB,sBAAsB,EACtB;gBACE,GAAG,IAAI;gBACP,UAAU;gBACV,cAAc,EAAE,IAAA,yDAAiC,EAAC,oBAAoB,CAAC;aACxE,EACD;gBACE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClC,CAAC,6CAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,cAAc,CAAC,EAC/D,IAAA,qEAAiC,EAAC,oBAAoB,CAAC;aAC1D,CACF,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF;AA5GD,0DA4GC"}
+{"version":3,"file":"notificationJobEnqueuer.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/notificationJobEnqueuer.ts"],"names":[],"mappings":";;;AAAA,uFAMmD;AAEnD,gEAA6D;AAC7D,oGAAiG;AACjG,mEAIiC;AAoIjC,MAAa,uBAAuB;IACjB,OAAO,CAA2C;IAEnE,YAAY,MAAqC;QAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAE3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuEG;IACH,KAAK,CAAC,gBAAgB,CACpB,sBAA4C,EAC5C,IAAkB,EAClB,OAAiC;QAEjC,MAAM,OAAO,CAAC,GAAG,CACf,IAAA,iCAAe,EAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE;YACpF,MAAM,oBAAoB,GAAgC;gBACxD,GAAG,IAAI,CAAC,cAAc;gBACtB,GAAG,IAAI,CAAC,mBAAmB;gBAC3B,KAAK,EAAE,MAAM;gBACb,UAAU;gBACV,WAAW,EAAE,IAAI,CAAC,WAAW;aAC9B,CAAC;YAEF,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CACxB,sBAAsB,EACtB;gBACE,GAAG,IAAI;gBACP,UAAU;gBACV,cAAc,EAAE,IAAA,yDAAiC,EAAC,oBAAoB,CAAC;aACxE,EACD;gBACE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClC,CAAC,6CAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,cAAc,CAAC,EAC/D,IAAA,qEAAiC,EAAC,oBAAoB,CAAC;aAC1D,CACF,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF;AAhHD,0DAgHC"}

package/src/lib/triggerIdempotencyKey.d.ts

@@ -1,5 +1,5 @@
 import { type Tagged } from "type-fest";
-import { type IdempotencyKey } from "./notificationJobEnqueuer";
+import { type IdempotencyKey, type IdempotencyKeyParts } from "./notificationJobEnqueuer";
 /**
  * Idempotency keys prevent duplicate notifications. `NotificationClient.trigger` should be called
  * after properly enqueuing a job using `NotificationJobEnqueuer.enqueueOneOrMore` to help ensure
@@ -10,7 +10,7 @@ import { type IdempotencyKey } from "./notificationJobEnqueuer";
  * unnecessary.
  */
 export type TriggerIdempotencyKey = Tagged<string, "TriggerIdempotencyKey">;
-export interface TriggerIdempotencyKeyParams extends IdempotencyKey {
+export type TriggerIdempotencyKeyParams = (IdempotencyKey | IdempotencyKeyParts) & {
     /**
      * The recipient chunk number.
      */
@@ -23,7 +23,7 @@ export interface TriggerIdempotencyKeyParams extends IdempotencyKey {
      * The workflow key.
      */
     workflowKey: string;
-}
+};
 /**
  * Type guard to check if a value is a valid TriggerIdempotencyKeyParams object.
  */

package/src/lib/triggerIdempotencyKey.js.map

@@ -1 +1 @@
-{"version":3,"file":"triggerIdempotencyKey.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/triggerIdempotencyKey.ts"],"names":[],"mappings":";;AAwCA,sEAeC;AAMD,8EAKC;AAlED,uDAAkD;AAqClD;;GAEG;AACH,SAAgB,6BAA6B,CAC3C,KAAc;IAEd,IAAI,IAAA,eAAK,EAAC,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAG,KAAoC,CAAC;IACpD,OAAO,CACL,OAAO,IAAI,MAAM;QACjB,aAAa,IAAI,MAAM;QACvB,YAAY,IAAI,MAAM;QACtB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC;QAChC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,SAAS,KAAK,QAAQ,CAAC,CACtE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,iCAAiC,CAC/C,MAAmC;IAEnC,oEAAoE;IACpE,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAA0B,CAAC;AACzD,CAAC"}
+{"version":3,"file":"triggerIdempotencyKey.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/triggerIdempotencyKey.ts"],"names":[],"mappings":";;AAyCA,sEAeC;AAMD,8EAKC;AAnED,uDAAkD;AAsClD;;GAEG;AACH,SAAgB,6BAA6B,CAC3C,KAAc;IAEd,IAAI,IAAA,eAAK,EAAC,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAG,KAAoC,CAAC;IACpD,OAAO,CACL,OAAO,IAAI,MAAM;QACjB,aAAa,IAAI,MAAM;QACvB,YAAY,IAAI,MAAM;QACtB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC;QAChC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,SAAS,KAAK,QAAQ,CAAC,CACtE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,iCAAiC,CAC/C,MAAmC;IAEnC,oEAAoE;IACpE,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAA0B,CAAC;AACzD,CAAC"}