@clipboard-health/notifications 0.3.1 → 0.3.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clipboard-health/notifications",
   "description": "Send notifications through third-party providers.",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "dependencies": {
     "@clipboard-health/phone-number": "0.2.2",

package/src/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./lib/chunkRecipients";
-export * from "./lib/createDeterministicHash";
+export * from "./lib/createIdempotencyKey";
 export * from "./lib/errorsInResult";
 export * from "./lib/notificationClient";
 export * from "./lib/types";

package/src/index.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./lib/chunkRecipients"), exports);
-tslib_1.__exportStar(require("./lib/createDeterministicHash"), exports);
+tslib_1.__exportStar(require("./lib/createIdempotencyKey"), exports);
 tslib_1.__exportStar(require("./lib/errorsInResult"), exports);
 tslib_1.__exportStar(require("./lib/notificationClient"), exports);
 tslib_1.__exportStar(require("./lib/types"), exports);

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/notifications/src/index.ts"],"names":[],"mappings":";;;AAAA,gEAAsC;AACtC,wEAA8C;AAC9C,+DAAqC;AACrC,mEAAyC;AACzC,sDAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/notifications/src/index.ts"],"names":[],"mappings":";;;AAAA,gEAAsC;AACtC,qEAA2C;AAC3C,+DAAqC;AACrC,mEAAyC;AACzC,sDAA4B"}

package/src/lib/createIdempotencyKey.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Creates a deterministic hash for use as an idempotency key.
+ *
+ * The function sorts `valuesToHash`, generates a SHA-256 hash, prepends the workflow key, and
+ * truncates the result to 255 characters maximum.
+ *
+ * @param params.key - Workflow key to prepend to the hash.
+ * @param params.valuesToHash - Array of strings to hash.
+ *
+ * @returns A hash string prefixed with the workflow key.
+ */
+export declare function createIdempotencyKey(params: {
+    key: string;
+    valuesToHash: string[];
+}): string;

package/src/lib/createIdempotencyKey.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIdempotencyKey = createIdempotencyKey;
+const node_crypto_1 = require("node:crypto");
+const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/**
+ * Creates a deterministic hash for use as an idempotency key.
+ *
+ * The function sorts `valuesToHash`, generates a SHA-256 hash, prepends the workflow key, and
+ * truncates the result to 255 characters maximum.
+ *
+ * @param params.key - Workflow key to prepend to the hash.
+ * @param params.valuesToHash - Array of strings to hash.
+ *
+ * @returns A hash string prefixed with the workflow key.
+ */
+function createIdempotencyKey(params) {
+    const { key, valuesToHash } = params;
+    const hash = (0, node_crypto_1.createHash)("sha256")
+        // Unicode code-points for deterministic, locale-independent sorting; don't mutate input array.
+        .update(JSON.stringify([...valuesToHash].sort()))
+        .digest("hex");
+    const result = `${key}${hash}`;
+    return result.slice(0, MAX_IDEMPOTENCY_KEY_LENGTH);
+}
+//# sourceMappingURL=createIdempotencyKey.js.map

package/src/lib/createIdempotencyKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createIdempotencyKey.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/createIdempotencyKey.ts"],"names":[],"mappings":";;AAeA,oDAUC;AAzBD,6CAAyC;AAEzC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,SAAgB,oBAAoB,CAAC,MAA+C;IAClF,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IAErC,MAAM,IAAI,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC;QAC/B,+FAA+F;SAC9F,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;SAChD,MAAM,CAAC,KAAK,CAAC,CAAC;IAEjB,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,IAAI,EAAE,CAAC;IAC/B,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,0BAA0B,CAAC,CAAC;AACrD,CAAC"}

package/src/lib/types.d.ts

@@ -125,7 +125,12 @@ export interface TriggerRequest {
     body: TriggerBody;
     /**
      * Key to prevent duplicate requests if provider supports it. It's important it is deterministic
-     * and remains the same across any retry logic.
+     * ({@link createIdempotencyKey}) and remains the same across any retry logic.
+     *
+     * Ensure your idempotency key doesn't prevent recipients from receiving notifications. For
+     * example, if you use the workflow key and the recipient's ID as the idempotency key, but it's
+     * possible the recipient could receive the notification multiple times within the idempotency
+     * key's validity window, the recipient will only receive the first notification.
      */
     idempotencyKey: string;
     /** Array of data keys to redact in logs for privacy. */

package/src/lib/createDeterministicHash.d.ts

@@ -1,17 +0,0 @@
-/**
- * Creates a deterministic hash from `items`.
- *
- * The function sorts the strings, then generates a SHA-256 hash truncated to the specified number
- * of characters.
- *
- * @param params.items - Array of strings or objects with id property to hash.
- * @param params.characters - Number of characters in the resulting hash (default: 32).
- *
- * @returns A hash string of the specified length.
- */
-export declare function createDeterministicHash(params: {
-    items: string[] | Array<{
-        id: string;
-    }>;
-    characters?: number;
-}): string;

package/src/lib/createDeterministicHash.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDeterministicHash = createDeterministicHash;
-const node_crypto_1 = require("node:crypto");
-/**
- * Creates a deterministic hash from `items`.
- *
- * The function sorts the strings, then generates a SHA-256 hash truncated to the specified number
- * of characters.
- *
- * @param params.items - Array of strings or objects with id property to hash.
- * @param params.characters - Number of characters in the resulting hash (default: 32).
- *
- * @returns A hash string of the specified length.
- */
-function createDeterministicHash(params) {
-    const { items, characters = 32 } = params;
-    const hash = (0, node_crypto_1.createHash)("sha256")
-        // Unicode code-points for deterministic, locale-independent sorting.
-        .update(JSON.stringify(items.map((item) => (typeof item === "string" ? item : item.id)).sort()))
-        .digest("hex");
-    const length = Math.max(1, Math.min(characters, hash.length));
-    return hash.slice(0, length);
-}
-//# sourceMappingURL=createDeterministicHash.js.map

package/src/lib/createDeterministicHash.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"createDeterministicHash.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/createDeterministicHash.ts"],"names":[],"mappings":";;AAaA,0DAaC;AA1BD,6CAAyC;AAEzC;;;;;;;;;;GAUG;AACH,SAAgB,uBAAuB,CAAC,MAGvC;IACC,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,EAAE,EAAE,GAAG,MAAM,CAAC;IAE1C,MAAM,IAAI,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC;QAC/B,qEAAqE;SACpE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;SAC/F,MAAM,CAAC,KAAK,CAAC,CAAC;IAEjB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAC/B,CAAC"}