@clipboard-health/notifications 0.5.1 → 0.7.0

package/README.md

@@ -6,7 +6,6 @@ Send notifications through third-party providers.
 
 - [Install](#install)
 - [Usage](#usage)
-  - [`NotificationClient`](#notificationclient)
 - [Local development commands](#local-development-commands)
 
 ## Install
@@ -17,49 +16,140 @@ npm install @clipboard-health/notifications
 
 ## Usage
 
-### `NotificationClient`
-
-<embedex source="packages/notifications/examples/notificationClient.ts">
-
-```ts
-import { NotificationClient, type Span } from "@clipboard-health/notifications";
-import { isSuccess } from "@clipboard-health/util-ts";
-
-const client = new NotificationClient({
-  apiKey: "test-api-key",
-  logger: {
-    info: console.log,
-    warn: console.warn,
-    error: console.error,
-  } as const,
-  tracer: {
-    trace: <T>(_name: string, _options: unknown, fun: (span?: Span | undefined) => T): T => fun(),
-  },
-});
-
-async function triggerNotification(job: { attemptsCount: number }) {
-  const result = await client.trigger({
-    attempt: (job?.attemptsCount ?? 0) + 1,
-    body: {
-      recipients: ["user-1"],
-      data: { favoriteColor: "blue", secret: "2" },
-    },
-    expiresAt: new Date(Date.now() + 300_000), // 5 minutes
-    idempotencyKey: "welcome-user-4",
-    key: "welcome-email",
-    keysToRedact: ["secret"],
-  });
-
-  if (isSuccess(result)) {
-    console.log("Notification sent:", result.value.id);
-  }
-}
-
-// eslint-disable-next-line unicorn/prefer-top-level-await
-void triggerNotification({ attemptsCount: 0 });
-```
+1. Export a `NotificationJobEnqueuer` instance:
+
+   <embedex source="packages/notifications/examples/notificationJobEnqueuer.ts">
+
+   ```ts
+   import { NotificationJobEnqueuer } from "@clipboard-health/notifications";
+
+   import { BackgroundJobsService } from "./setup";
+
+   // Provide this in your microservice.
+   export const notificationJobEnqueuer = new NotificationJobEnqueuer({
+     adapter: new BackgroundJobsService(),
+   });
+   ```
+
+   </embedex>
+
+1. Enqueue your job:
+
+   <embedex source="packages/notifications/examples/enqueueNotificationJob.ts">
+
+   ```ts
+   import { IdempotencyKey } from "@clipboard-health/notifications";
+
+   import { ExampleNotificationJob } from "./exampleNotification.job";
+   import { notificationJobEnqueuer } from "./notificationJobEnqueuer";
+
+   async function enqueueNotificationJob() {
+     await notificationJobEnqueuer.enqueueOneOrMore(ExampleNotificationJob, {
+       // Set expiresAt at enqueue-time so it remains stable across job retries.
+       expiresAt: minutesFromNow(60),
+       // Set idempotencyKey at enqueue-time so it remains stable across job retries.
+       idempotencyKey: new IdempotencyKey({
+         resourceId: "event-123",
+       }),
+       // Set recipients at enqueue-time so they respect our notification provider's limits.
+       recipients: ["user-1"],
+
+       workflowKey: "event-starting-reminder",
+
+       // Any additional enqueue-time data passed to the job:
+       workplaceId: "workplace-123",
+     });
+   }
+
+   // eslint-disable-next-line unicorn/prefer-top-level-await
+   void enqueueNotificationJob();
+
+   function minutesFromNow(minutes: number) {
+     return new Date(Date.now() + minutes * 60_000);
+   }
+   ```
+
+   </embedex>
+
+1. Implement your job, which should be minimal, calling off to a service to send the actual notification:
+
+   <embedex source="packages/notifications/examples/exampleNotification.job.ts">
+
+   ```ts
+   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
+   import {
+     errorsInResult,
+     type NotificationEnqueueData,
+     type NotificationJobData,
+     RETRYABLE_ERRORS,
+   } from "@clipboard-health/notifications";
+   import { toError } from "@clipboard-health/util-ts";
+
+   import { type ExampleNotificationService } from "./exampleNotification.service";
+
+   interface ExampleNotificationData {
+     workplaceId: string;
+   }
+
+   export type ExampleNotificationEnqueueData = NotificationEnqueueData & ExampleNotificationData;
+   export type ExampleNotificationJobData = NotificationJobData & ExampleNotificationData;
+
+   export class ExampleNotificationJob implements BaseHandler<ExampleNotificationJobData> {
+     constructor(private readonly service: ExampleNotificationService) {}
+
+     async perform(data: ExampleNotificationJobData, job: { attemptsCount: number }) {
+       const result = await this.service.sendNotification({
+         ...data,
+         // Include the job's attempts count for debugging, this is called `retryAttempts` in `background-jobs-postgres`.
+         attempt: job.attemptsCount + 1,
+       });
+
+       if (errorsInResult(result, RETRYABLE_ERRORS)) {
+         throw toError(result.error);
+       }
+     }
+   }
+   ```
+
+   </embedex>
+
+1. Trigger the job in your service:
+
+   <embedex source="packages/notifications/examples/exampleNotification.service.ts">
+
+   ```ts
+   import { type NotificationClient } from "@clipboard-health/notifications";
+
+   import { type ExampleNotificationJobData } from "./exampleNotification.job";
+
+   type ExampleNotificationDo = ExampleNotificationJobData & { attempt: number };
+
+   export class ExampleNotificationService {
+     constructor(private readonly client: NotificationClient) {}
+
+     async sendNotification(params: ExampleNotificationDo) {
+       const { attempt, expiresAt, idempotencyKey, recipients, workflowKey, workplaceId } = params;
+
+       // Assume this comes from a database and, for example, are used as template variables...
+       const data = { favoriteColor: "blue", secret: "2" };
+
+       return await this.client.trigger({
+         attempt,
+         body: {
+           recipients,
+           data,
+           workplaceId,
+         },
+         expiresAt,
+         idempotencyKey,
+         workflowKey,
+         keysToRedact: ["secret"],
+       });
+     }
+   }
+   ```
 
-</embedex>
+   </embedex>
 
 ## Local development commands
 

package/package.json

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

package/src/index.d.ts

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

package/src/index.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./lib/chunkRecipients"), exports);
-tslib_1.__exportStar(require("./lib/createIdempotencyKey"), exports);
 tslib_1.__exportStar(require("./lib/errorsInResult"), exports);
+tslib_1.__exportStar(require("./lib/idempotencyKey"), exports);
 tslib_1.__exportStar(require("./lib/notificationClient"), exports);
+tslib_1.__exportStar(require("./lib/notificationJobEnqueuer"), exports);
 tslib_1.__exportStar(require("./lib/types"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

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

package/src/lib/idempotencyKey.d.ts

@@ -0,0 +1,46 @@
+export interface IdempotencyKeyParams {
+    /**
+     * Prefer `resourceId` over `eventOccurredAt`; it's harder to misuse.
+     *
+     * If an event triggered your workflow and it doesn't have a unique ID, you may decide to use its
+     * occurrence timestamp. For example, if you have a daily CRON job, use the date it ran.
+     *
+     * Take care when using `Date.now()` or `new Date()`. These change each time your job runs, which
+     * means the idempotency key will always be different and doesn't prevent duplicate notifications.
+     */
+    eventOccurredAt?: Date | undefined;
+    /**
+     * If a resource triggered your workflow, include its unique ID.
+     *
+     * @note `recipients` (and `workplaceId` if it exists) are included in the idempotency key
+     * automatically from the trigger body.
+     *
+     * @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;
+}
+/**
+ * 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 `recipients` (and `workplaceId` if it exists) are included in the idempotency key
+ * automatically from the trigger body.
+ *
+ * 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.
+ */
+export declare class IdempotencyKey {
+    protected readonly eventOccurredAt: IdempotencyKeyParams["eventOccurredAt"];
+    protected readonly resourceId: IdempotencyKeyParams["resourceId"];
+    constructor(params: IdempotencyKeyParams);
+}

package/src/lib/idempotencyKey.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotencyKey = void 0;
+/**
+ * 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 `recipients` (and `workplaceId` if it exists) are included in the idempotency key
+ * automatically from the trigger body.
+ *
+ * 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.
+ */
+class IdempotencyKey {
+    eventOccurredAt;
+    resourceId;
+    constructor(params) {
+        const { eventOccurredAt, resourceId } = params;
+        this.eventOccurredAt = eventOccurredAt;
+        this.resourceId = resourceId;
+    }
+}
+exports.IdempotencyKey = IdempotencyKey;
+//# sourceMappingURL=idempotencyKey.js.map

package/src/lib/idempotencyKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotencyKey.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/idempotencyKey.ts"],"names":[],"mappings":";;;AAyBA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,cAAc;IACN,eAAe,CAA0C;IACzD,UAAU,CAAqC;IAElE,YAAmB,MAA4B;QAC7C,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;QAE/C,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAVD,wCAUC"}

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

@@ -0,0 +1,18 @@
+/**
+ * Chunks recipients into groups that don't exceed the maximum recipients count,
+ * assigning a unique chunk number to each group.
+ *
+ * This function is used to split large recipient lists into smaller batches that
+ * comply with notification provider limits. Each chunk is numbered sequentially
+ * starting from 1.
+ *
+ * @param params - The chunking parameters
+ * @param params.recipients - Array of recipient IDs to chunk
+ * @returns Array of chunks, each containing a chunk number and recipients array
+ */
+export declare function chunkRecipients(params: {
+    recipients: string[];
+}): Array<{
+    number: number;
+    recipients: string[];
+}>;

package/src/lib/internal/chunkRecipients.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunkRecipients = chunkRecipients;
+const util_ts_1 = require("@clipboard-health/util-ts");
+const notificationClient_1 = require("../notificationClient");
+/**
+ * Chunks recipients into groups that don't exceed the maximum recipients count,
+ * assigning a unique chunk number to each group.
+ *
+ * This function is used to split large recipient lists into smaller batches that
+ * comply with notification provider limits. Each chunk is numbered sequentially
+ * starting from 1.
+ *
+ * @param params - The chunking parameters
+ * @param params.recipients - Array of recipient IDs to chunk
+ * @returns Array of chunks, each containing a chunk number and recipients array
+ */
+function chunkRecipients(params) {
+    const { recipients } = params;
+    if (recipients.length === 0) {
+        return [{ number: 1, recipients: [] }];
+    }
+    return (0, util_ts_1.chunk)(recipients, notificationClient_1.MAXIMUM_RECIPIENTS_COUNT).map((recipientsChunk, index) => ({
+        number: index + 1,
+        recipients: recipientsChunk,
+    }));
+}
+//# sourceMappingURL=chunkRecipients.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunkRecipients.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/chunkRecipients.ts"],"names":[],"mappings":";;AAgBA,0CAaC;AA7BD,uDAAkD;AAElD,8DAAiE;AAEjE;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAAC,MAE/B;IACC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IAE9B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,IAAA,eAAK,EAAC,UAAU,EAAE,6CAAwB,CAAC,CAAC,GAAG,CAAC,CAAC,eAAe,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAClF,MAAM,EAAE,KAAK,GAAG,CAAC;QACjB,UAAU,EAAE,eAAe;KAC5B,CAAC,CAAC,CAAC;AACN,CAAC"}

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

@@ -0,0 +1,13 @@
+/**
+ * Creates a deterministic hash.
+ *
+ * Normalizes `value` using stable JSON serialization for non-string values and generates
+ * a SHA-256 hash.
+ *
+ * Note: Non-JSON-serializable values (undefined, Symbol, functions, circular refs) may be
+ * dropped or cause errors during serialization.
+ *
+ * @param value - Value to hash (string, string[], object, etc.).
+ * @returns A hex string representing the hash.
+ */
+export declare function createDeterministicHash(value: unknown): string;

package/src/lib/internal/createDeterministicHash.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeterministicHash = createDeterministicHash;
+const node_crypto_1 = require("node:crypto");
+const util_ts_1 = require("@clipboard-health/util-ts");
+/**
+ * Creates a deterministic hash.
+ *
+ * Normalizes `value` using stable JSON serialization for non-string values and generates
+ * a SHA-256 hash.
+ *
+ * Note: Non-JSON-serializable values (undefined, Symbol, functions, circular refs) may be
+ * dropped or cause errors during serialization.
+ *
+ * @param value - Value to hash (string, string[], object, etc.).
+ * @returns A hex string representing the hash.
+ */
+function createDeterministicHash(value) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(typeof value === "string" ? value : (0, util_ts_1.stringify)(value))
+        .digest("hex");
+}
+//# sourceMappingURL=createDeterministicHash.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createDeterministicHash.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/createDeterministicHash.ts"],"names":[],"mappings":";;AAgBA,0DAIC;AApBD,6CAAyC;AAEzC,uDAAsD;AAEtD;;;;;;;;;;;GAWG;AACH,SAAgB,uBAAuB,CAAC,KAAc;IACpD,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAA,mBAAS,EAAC,KAAK,CAAC,CAAC;SAC5D,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}

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

@@ -1,3 +1,3 @@
 import type { LogParams, TriggerRequest } from "../types";
-export type TriggerLogContext = LogParams & Pick<TriggerRequest, "attempt" | "idempotencyKey" | "key">;
+export type TriggerLogContext = LogParams & Pick<TriggerRequest, "attempt" | "idempotencyKey" | "workflowKey">;
 export declare function createTriggerLogParams(params: TriggerRequest & LogParams): TriggerLogContext;

package/src/lib/internal/createTriggerLogParams.js

@@ -2,12 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTriggerLogParams = createTriggerLogParams;
 function createTriggerLogParams(params) {
-    const { attempt, destination, idempotencyKey, key, traceName } = params;
+    const { attempt, destination, idempotencyKey, key, workflowKey, traceName } = params;
     return {
         attempt,
         destination,
         idempotencyKey,
-        key,
+        workflowKey: /* istanbul ignore next */ workflowKey ?? key,
         traceName,
     };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"createTriggerLogParams.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/createTriggerLogParams.ts"],"names":[],"mappings":";;AAKA,wDAUC;AAVD,SAAgB,sBAAsB,CAAC,MAAkC;IACvE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAExE,OAAO;QACL,OAAO;QACP,WAAW;QACX,cAAc;QACd,GAAG;QACH,SAAS;KACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"createTriggerLogParams.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/createTriggerLogParams.ts"],"names":[],"mappings":";;AAKA,wDAUC;AAVD,SAAgB,sBAAsB,CAAC,MAAkC;IACvE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAErF,OAAO;QACL,OAAO;QACP,WAAW;QACX,cAAc;QACd,WAAW,EAAE,0BAA0B,CAAC,WAAW,IAAI,GAAG;QAC1D,SAAS;KACV,CAAC;AACJ,CAAC"}

package/src/lib/internal/createTriggerTraceOptions.js

@@ -2,10 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTriggerTraceOptions = createTriggerTraceOptions;
 function createTriggerTraceOptions(params) {
-    const { key, attempt, destination } = params;
+    const { workflowKey, attempt, destination } = params;
     return {
-        resource: `notification.${key}`,
-        // Don't include high cardinality tags like expiresAt and idempotencyKey.
+        resource: `notification.${workflowKey}`,
+        /**
+         * Don't include high cardinality tags like expiresAt and idempotencyKey to reduce Datadog
+         * costs.
+         */
         tags: {
             "span.kind": "producer",
             component: "customer-notifications",

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

@@ -1 +1 @@
-{"version":3,"file":"createTriggerTraceOptions.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/createTriggerTraceOptions.ts"],"names":[],"mappings":";;AAGA,8DAeC;AAfD,SAAgB,yBAAyB,CAAC,MAAyB;IACjE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IAE7C,OAAO;QACL,QAAQ,EAAE,gBAAgB,GAAG,EAAE;QAC/B,yEAAyE;QACzE,IAAI,EAAE;YACJ,WAAW,EAAE,UAAU;YACvB,SAAS,EAAE,wBAAwB;YACnC,kBAAkB,EAAE,WAAW;YAC/B,qBAAqB,EAAE,SAAS;YAChC,uBAAuB,EAAE,WAAW;YACpC,sBAAsB,EAAE,OAAO,CAAC,QAAQ,EAAE;SAC3C;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"createTriggerTraceOptions.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/createTriggerTraceOptions.ts"],"names":[],"mappings":";;AAGA,8DAkBC;AAlBD,SAAgB,yBAAyB,CAAC,MAAyB;IACjE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IAErD,OAAO;QACL,QAAQ,EAAE,gBAAgB,WAAW,EAAE;QACvC;;;WAGG;QACH,IAAI,EAAE;YACJ,WAAW,EAAE,UAAU;YACvB,SAAS,EAAE,wBAAwB;YACnC,kBAAkB,EAAE,WAAW;YAC/B,qBAAqB,EAAE,SAAS;YAChC,uBAAuB,EAAE,WAAW;YACpC,sBAAsB,EAAE,OAAO,CAAC,QAAQ,EAAE;SAC3C;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,35 @@
+import { IdempotencyKey, type IdempotencyKeyParams } from "../idempotencyKey";
+interface IdempotencyKeyDoNotImportOutsideNotificationsLibraryParams extends IdempotencyKeyParams {
+    /**
+     * The recipient chunk number.
+     */
+    chunk: number;
+    /**
+     * The recipients in the chunk; maximum of MAXIMUM_RECIPIENTS_COUNT.
+     */
+    recipients: string[];
+    /**
+     * The workflow key.
+     */
+    workflowKey: string;
+}
+/**
+ * Idempotency keys prevent duplicate notifications. `NotificationClient.trigger` should be called
+ * after properly enqueuing a job using `NotificationJobEnqueuer.enqueueOneOrMore` to help ensure
+ * we're following best practices so customers don't receive duplicate or stale notifications.
+ *
+ * Yes, you could import this class into your service and call `NotificationClient.trigger`
+ * directly. We're using the honor system in hopes that enforcement is unnecessary.
+ *
+ * @see {@link NotificationJobEnqueuer.enqueueOneOrMore}.
+ */
+export declare class IdempotencyKeyDoNotImportOutsideNotificationsLibrary extends IdempotencyKey {
+    private readonly chunk;
+    private readonly recipients;
+    private readonly workflowKey;
+    constructor(params: IdempotencyKeyDoNotImportOutsideNotificationsLibraryParams);
+    toHash(params: {
+        workplaceId?: string | undefined;
+    }): string;
+}
+export {};

package/src/lib/internal/idempotencyKeyDoNotImportOutsideNotificationsLibrary.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotencyKeyDoNotImportOutsideNotificationsLibrary = void 0;
+const util_ts_1 = require("@clipboard-health/util-ts");
+const idempotencyKey_1 = require("../idempotencyKey");
+const createDeterministicHash_1 = require("./createDeterministicHash");
+/**
+ * Idempotency keys prevent duplicate notifications. `NotificationClient.trigger` should be called
+ * after properly enqueuing a job using `NotificationJobEnqueuer.enqueueOneOrMore` to help ensure
+ * we're following best practices so customers don't receive duplicate or stale notifications.
+ *
+ * Yes, you could import this class into your service and call `NotificationClient.trigger`
+ * directly. We're using the honor system in hopes that enforcement is unnecessary.
+ *
+ * @see {@link NotificationJobEnqueuer.enqueueOneOrMore}.
+ */
+class IdempotencyKeyDoNotImportOutsideNotificationsLibrary extends idempotencyKey_1.IdempotencyKey {
+    chunk;
+    recipients;
+    workflowKey;
+    constructor(params) {
+        const { chunk, recipients, workflowKey, ...rest } = params;
+        super(rest);
+        this.chunk = chunk;
+        this.recipients = recipients;
+        this.workflowKey = workflowKey;
+    }
+    toHash(params) {
+        const { workplaceId } = params;
+        return (0, createDeterministicHash_1.createDeterministicHash)([
+            this.workflowKey,
+            this.chunk,
+            this.resourceId,
+            this.eventOccurredAt?.toISOString(),
+            this.recipients.join(","),
+            workplaceId,
+        ]
+            .filter(util_ts_1.isDefined)
+            .join(","));
+    }
+}
+exports.IdempotencyKeyDoNotImportOutsideNotificationsLibrary = IdempotencyKeyDoNotImportOutsideNotificationsLibrary;
+//# sourceMappingURL=idempotencyKeyDoNotImportOutsideNotificationsLibrary.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idempotencyKeyDoNotImportOutsideNotificationsLibrary.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/idempotencyKeyDoNotImportOutsideNotificationsLibrary.ts"],"names":[],"mappings":";;;AAAA,uDAAsD;AAEtD,sDAA8E;AAK9E,uEAAoE;AAmBpE;;;;;;;;;GASG;AACH,MAAa,oDAAqD,SAAQ,+BAAc;IACrE,KAAK,CAAsE;IAC3E,UAAU,CAA2E;IACrF,WAAW,CAA4E;IAExG,YAAY,MAAkE;QAC5E,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAE3D,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED,MAAM,CAAC,MAA4C;QACjD,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;QAE/B,OAAO,IAAA,iDAAuB,EAC5B;YACE,IAAI,CAAC,WAAW;YAChB,IAAI,CAAC,KAAK;YACV,IAAI,CAAC,UAAU;YACf,IAAI,CAAC,eAAe,EAAE,WAAW,EAAE;YACnC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC;YACzB,WAAW;SACZ;aACE,MAAM,CAAC,mBAAS,CAAC;aACjB,IAAI,CAAC,GAAG,CAAC,CACb,CAAC;IACJ,CAAC;CACF;AA9BD,oHA8BC"}

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

@@ -1,5 +1,10 @@
 import { type Logger } from "@clipboard-health/util-ts";
 import { Knock } from "@knocklabs/node";
+/**
+ * Extended Knock client with custom configuration for idempotent operations.
+ *
+ * @see {@link https://docs.knock.app/api-reference/overview/idempotent-requests}
+ */
 export declare class IdempotentKnock extends Knock {
     logLevel: "warn";
     maxRetries: number;

package/src/lib/internal/idempotentKnock.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IdempotentKnock = void 0;
 const node_1 = require("@knocklabs/node");
+/**
+ * Extended Knock client with custom configuration for idempotent operations.
+ *
+ * @see {@link https://docs.knock.app/api-reference/overview/idempotent-requests}
+ */
 class IdempotentKnock extends node_1.Knock {
     logLevel = "warn"; // Knock's default.
     maxRetries = 1; // Knock's default is 2, but we rely on background job retries.

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

@@ -1 +1 @@
-{"version":3,"file":"idempotentKnock.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/idempotentKnock.ts"],"names":[],"mappings":";;;AACA,0CAAwC;AAExC,MAAa,eAAgB,SAAQ,YAAK;IACxB,QAAQ,GAAG,MAAe,CAAC,CAAC,mBAAmB;IAC/C,UAAU,GAAG,CAAC,CAAC,CAAC,+DAA+D;IAC/E,OAAO,GAAG,MAAM,CAAC,CAAC,mBAAmB;IAElC,iBAAiB,GAAG,iBAAiB,CAAC;IAEzD,YAAY,MAA0C;QACpD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAElC,KAAK,CAAC;YACJ,MAAM;YACN,MAAM,EAAE;gBACN,GAAG,MAAM;gBACT,KAAK,EAAE,MAAM,CAAC,IAAI;aACnB;SACF,CAAC,CAAC;IACL,CAAC;CACF;AAlBD,0CAkBC"}
+{"version":3,"file":"idempotentKnock.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/idempotentKnock.ts"],"names":[],"mappings":";;;AACA,0CAAwC;AAExC;;;;GAIG;AACH,MAAa,eAAgB,SAAQ,YAAK;IACxB,QAAQ,GAAG,MAAe,CAAC,CAAC,mBAAmB;IAC/C,UAAU,GAAG,CAAC,CAAC,CAAC,+DAA+D;IAC/E,OAAO,GAAG,MAAM,CAAC,CAAC,mBAAmB;IAElC,iBAAiB,GAAG,iBAAiB,CAAC;IAEzD,YAAY,MAA0C;QACpD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAElC,KAAK,CAAC;YACJ,MAAM;YACN,MAAM,EAAE;gBACN,GAAG,MAAM;gBACT,KAAK,EAAE,MAAM,CAAC,IAAI;aACnB;SACF,CAAC,CAAC;IACL,CAAC;CACF;AAlBD,0CAkBC"}

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

@@ -0,0 +1,3 @@
+import { type Knock } from "@knocklabs/node";
+import { type InlineIdentifyUserRequest } from "../types";
+export declare function toInlineIdentifyUserRequest(recipient: InlineIdentifyUserRequest): Knock.Users.InlineIdentifyUserRequest;

package/src/lib/internal/toInlineIdentifyUserRequest.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toInlineIdentifyUserRequest = toInlineIdentifyUserRequest;
+const toInlineIdentifyUserRequestWithoutUserId_1 = require("./toInlineIdentifyUserRequestWithoutUserId");
+function toInlineIdentifyUserRequest(recipient) {
+    const { userId, ...rest } = recipient;
+    return {
+        ...(0, toInlineIdentifyUserRequestWithoutUserId_1.toInlineIdentifyUserRequestWithoutUserId)(rest),
+        id: userId,
+    };
+}
+//# sourceMappingURL=toInlineIdentifyUserRequest.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toInlineIdentifyUserRequest.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/toInlineIdentifyUserRequest.ts"],"names":[],"mappings":";;AAKA,kEASC;AAXD,yGAAsG;AAEtG,SAAgB,2BAA2B,CACzC,SAAoC;IAEpC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,CAAC;IAEtC,OAAO;QACL,GAAG,IAAA,mFAAwC,EAAC,IAAI,CAAC;QACjD,EAAE,EAAE,MAAM;KACX,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,3 @@
+import { type Knock } from "@knocklabs/node";
+import type { InlineIdentifyUserRequest } from "../types";
+export declare function toInlineIdentifyUserRequestWithoutUserId(recipient: Omit<InlineIdentifyUserRequest, "userId">): Omit<Knock.Users.InlineIdentifyUserRequest, "id">;

package/src/lib/internal/toInlineIdentifyUserRequestWithoutUserId.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toInlineIdentifyUserRequestWithoutUserId = toInlineIdentifyUserRequestWithoutUserId;
+const formatPhoneNumber_1 = require("./formatPhoneNumber");
+function toInlineIdentifyUserRequestWithoutUserId(recipient) {
+    const { channelData, createdAt, email, name, phoneNumber, timeZone, customProperties, ...rest } = recipient;
+    return {
+        ...rest,
+        ...customProperties,
+        ...(channelData ? { channel_data: channelData } : {}),
+        ...(createdAt ? { created_at: createdAt.toISOString() } : {}),
+        ...(email ? { email } : {}),
+        ...(name ? { name } : {}),
+        ...(phoneNumber ? { phone_number: (0, formatPhoneNumber_1.formatPhoneNumber)({ phoneNumber }) } : {}),
+        ...(timeZone ? { timezone: timeZone } : {}),
+    };
+}
+//# sourceMappingURL=toInlineIdentifyUserRequestWithoutUserId.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toInlineIdentifyUserRequestWithoutUserId.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/toInlineIdentifyUserRequestWithoutUserId.ts"],"names":[],"mappings":";;AAKA,4FAgBC;AAlBD,2DAAwD;AAExD,SAAgB,wCAAwC,CACtD,SAAoD;IAEpD,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAC7F,SAAS,CAAC;IAEZ,OAAO;QACL,GAAG,IAAI;QACP,GAAG,gBAAgB;QACnB,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzB,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAA,qCAAiB,EAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC;AACJ,CAAC"}