@clipboard-health/notifications 0.4.1 → 0.5.1

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@clipboard-health/notifications",
   "description": "Send notifications through third-party providers.",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "dependencies": {
-    "@clipboard-health/phone-number": "0.3.0",
-    "@clipboard-health/util-ts": "3.12.2",
+    "@clipboard-health/phone-number": "0.4.1",
+    "@clipboard-health/util-ts": "3.13.1",
     "@knocklabs/node": "1.16.0",
+    "fast-json-stable-stringify": "2.1.0",
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@clipboard-health/testing-core": "0.21.2"
+    "@clipboard-health/testing-core": "0.22.1"
   },
   "keywords": [],
   "license": "MIT",

package/src/lib/createIdempotencyKey.d.ts

@@ -1,15 +1,17 @@
+export declare 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.
+ * The function normalizes `value` (using a stable JSON.stringify for non-string values), generates
+ * a SHA-256 hash, prepends the workflow key, and truncates the result to MAX_IDEMPOTENCY_KEY_LENGTH
+ * maximum.
  *
  * @param params.key - Workflow key to prepend to the hash.
- * @param params.valuesToHash - Array of strings to hash.
+ * @param params.value - Value to hash (string, string[], object, etc.).
  *
  * @returns A hash string prefixed with the workflow key.
  */
 export declare function createIdempotencyKey(params: {
     key: string;
-    valuesToHash: string[];
+    value: unknown;
 }): string;

package/src/lib/createIdempotencyKey.js

@@ -1,26 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_IDEMPOTENCY_KEY_LENGTH = void 0;
 exports.createIdempotencyKey = createIdempotencyKey;
+const tslib_1 = require("tslib");
 const node_crypto_1 = require("node:crypto");
-const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+const fast_json_stable_stringify_1 = tslib_1.__importDefault(require("fast-json-stable-stringify"));
+exports.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.
+ * The function normalizes `value` (using a stable JSON.stringify for non-string values), generates
+ * a SHA-256 hash, prepends the workflow key, and truncates the result to MAX_IDEMPOTENCY_KEY_LENGTH
+ * maximum.
  *
  * @param params.key - Workflow key to prepend to the hash.
- * @param params.valuesToHash - Array of strings to hash.
+ * @param params.value - Value to hash (string, string[], object, etc.).
  *
  * @returns A hash string prefixed with the workflow key.
  */
 function createIdempotencyKey(params) {
-    const { key, valuesToHash } = params;
+    const { key, value } = 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()))
+        .update(typeof value === "string" ? value : (0, fast_json_stable_stringify_1.default)(value))
         .digest("hex");
-    const result = `${key}${hash}`;
-    return result.slice(0, MAX_IDEMPOTENCY_KEY_LENGTH);
+    return `${key}:${hash}`.slice(0, exports.MAX_IDEMPOTENCY_KEY_LENGTH);
 }
 //# sourceMappingURL=createIdempotencyKey.js.map

package/src/lib/createIdempotencyKey.js.map

@@ -1 +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"}
+{"version":3,"file":"createIdempotencyKey.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/createIdempotencyKey.ts"],"names":[],"mappings":";;;AAkBA,oDAQC;;AA1BD,6CAAyC;AAEzC,oGAAmD;AAEtC,QAAA,0BAA0B,GAAG,GAAG,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,SAAgB,oBAAoB,CAAC,MAAuC;IAC1E,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAE9B,MAAM,IAAI,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC;SAC9B,MAAM,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAA,oCAAS,EAAC,KAAK,CAAC,CAAC;SAC5D,MAAM,CAAC,KAAK,CAAC,CAAC;IAEjB,OAAO,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,kCAA0B,CAAC,CAAC;AAC/D,CAAC"}

package/src/lib/notificationClient.d.ts

@@ -4,8 +4,8 @@ import type { AppendPushTokenRequest, AppendPushTokenResponse, LogParams, Notifi
 export declare const MAXIMUM_RECIPIENTS_COUNT = 1000;
 export declare const ERROR_CODES: {
     readonly expired: "expired";
-    readonly recipientCountAboveMaximum: "recipientCountAboveMaximum";
     readonly recipientCountBelowMinimum: "recipientCountBelowMinimum";
+    readonly recipientCountAboveMaximum: "recipientCountAboveMaximum";
     readonly missingSigningKey: "missingSigningKey";
     readonly unknown: "unknown";
 };
@@ -30,7 +30,7 @@ export declare class NotificationClient {
      * Triggers a notification through third-party providers.
      *
      * This method handles:
-     * - Stale notifications prevention through expiration checks.
+     * - Stale notifications prevention through expiresAt.
      * - Logging with sensitive data redaction.
      * - Distributed tracing with notification metadata.
      * - Idempotency to prevent duplicate notifications.

package/src/lib/notificationClient.js

@@ -30,8 +30,8 @@ const LOG_PARAMS = {
 exports.MAXIMUM_RECIPIENTS_COUNT = 1000;
 exports.ERROR_CODES = {
     expired: "expired",
-    recipientCountAboveMaximum: "recipientCountAboveMaximum",
     recipientCountBelowMinimum: "recipientCountBelowMinimum",
+    recipientCountAboveMaximum: "recipientCountAboveMaximum",
     missingSigningKey: "missingSigningKey",
     unknown: "unknown",
 };
@@ -62,7 +62,7 @@ class NotificationClient {
      * Triggers a notification through third-party providers.
      *
      * This method handles:
-     * - Stale notifications prevention through expiration checks.
+     * - Stale notifications prevention through expiresAt.
      * - Logging with sensitive data redaction.
      * - Distributed tracing with notification metadata.
      * - Idempotency to prevent duplicate notifications.

package/src/lib/types.d.ts

@@ -129,7 +129,12 @@ export interface TriggerRequest {
     body: TriggerBody;
     /**
      * Key to prevent duplicate requests if provider supports it. It's important it is deterministic
-     * ({@link createIdempotencyKey}) and remains the same across any retry logic.
+     * ({@link createIdempotencyKey}) and remains the same across retry logic.
+     *
+     * If you retry a request with the same idempotency key within 24 hours from the original request,
+     * we will return the same response as the original request. Idempotent requests are expected to
+     * be identical. To prevent accidental misuse, the client throws an error when incoming parameters
+     * don't match those from the original request.
      *
      * 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
@@ -139,9 +144,17 @@ export interface TriggerRequest {
     idempotencyKey: string;
     /** Array of data keys to redact in logs for privacy. */
     keysToRedact?: string[];
-    /** Expiration timestamp after which the request is dropped. */
+    /**
+     * Expiration timestamp after which the request is dropped. Use this to prevent stale
+     * notifications. If, for example, you're notifying about an event that starts in one hour, you
+     * might set this to one hour from now.
+     *
+     * If you're triggering from a background job, don't set this at the call site! Set it when you
+     * enqueue the job. Otherwise, it gets updated each time the job retries, will always be in the
+     * future, and won't prevent stale notifications.
+     */
     expiresAt: Date;
-    /** Attempt number for tracking. */
+    /** Attempt number for tracing. */
     attempt: number;
 }
 /**