@clipboard-health/notifications 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @clipboard-health/notifications <!-- omit from toc -->
+
+Send notifications through third-party providers.
+
+## Table of contents <!-- omit from toc -->
+
+- [Install](#install)
+- [Usage](#usage)
+  - [`NotificationClient`](#notificationclient)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+```bash
+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 });
+```
+
+</embedex>
+
+## Local development commands
+
+See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@clipboard-health/notifications",
+  "description": "Send notifications through third-party providers.",
+  "version": "0.1.0",
+  "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
+  "dependencies": {
+    "@clipboard-health/phone-number": "0.2.0",
+    "@clipboard-health/util-ts": "3.12.0",
+    "@knocklabs/node": "1.16.0",
+    "tslib": "2.8.1"
+  },
+  "devDependencies": {
+    "@clipboard-health/testing-core": "0.21.0"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/notifications",
+    "type": "git",
+    "url": "git+https://github.com/ClipboardHealth/core-utils.git"
+  },
+  "type": "commonjs",
+  "typings": "./src/index.d.ts",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

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

package/src/index.js

@@ -0,0 +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/createDeterministicHash"), exports);
+tslib_1.__exportStar(require("./lib/errorsInResult"), exports);
+tslib_1.__exportStar(require("./lib/notificationClient"), exports);
+tslib_1.__exportStar(require("./lib/types"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +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"}

package/src/lib/chunk.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates an `array` of elements split into groups the length of `size`. If `array` can't be split
+ * evenly, the final chunk will be the remaining elements.
+ *
+ * @param array - The array to chunk.
+ * @param size - The length of each chunk.
+ * @returns the new 2D array of chunks.
+ */
+export declare function chunk<T>(array: T[], size: number): T[][];

package/src/lib/chunk.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunk = chunk;
+/**
+ * Creates an `array` of elements split into groups the length of `size`. If `array` can't be split
+ * evenly, the final chunk will be the remaining elements.
+ *
+ * @param array - The array to chunk.
+ * @param size - The length of each chunk.
+ * @returns the new 2D array of chunks.
+ */
+function chunk(array, size) {
+    if (!Number.isInteger(size) || size <= 0) {
+        throw new RangeError("size must be a positive integer");
+    }
+    if (array.length === 0) {
+        return [];
+    }
+    return Array.from({ length: Math.ceil(array.length / size) }, (_, index) => array.slice(index * size, (index + 1) * size));
+}
+//# sourceMappingURL=chunk.js.map

package/src/lib/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/chunk.ts"],"names":[],"mappings":";;AAQA,sBAYC;AApBD;;;;;;;GAOG;AACH,SAAgB,KAAK,CAAI,KAAU,EAAE,IAAY;IAC/C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,UAAU,CAAC,iCAAiC,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CACzE,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAC9C,CAAC;AACJ,CAAC"}

package/src/lib/chunkRecipients.d.ts

@@ -0,0 +1,7 @@
+export declare function chunkRecipients(params: {
+    idempotencyKey: string;
+    recipientIds: string[];
+}): Array<{
+    idempotencyKey: string;
+    recipientIds: string[];
+}>;

package/src/lib/chunkRecipients.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunkRecipients = chunkRecipients;
+const chunk_1 = require("./chunk");
+const notificationClient_1 = require("./notificationClient");
+function chunkRecipients(params) {
+    const { recipientIds, idempotencyKey } = params;
+    if (recipientIds.length === 0) {
+        return [{ idempotencyKey, recipientIds: [] }];
+    }
+    const idChunks = (0, chunk_1.chunk)(recipientIds, notificationClient_1.MAXIMUM_RECIPIENTS_COUNT);
+    const singleChunk = idChunks.length === 1;
+    return idChunks.map((ids, index) => ({
+        idempotencyKey: singleChunk ? idempotencyKey : `${idempotencyKey}-chunk-${index + 1}`,
+        recipientIds: ids,
+    }));
+}
+//# sourceMappingURL=chunkRecipients.js.map

package/src/lib/chunkRecipients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkRecipients.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/chunkRecipients.ts"],"names":[],"mappings":";;AAGA,0CAgBC;AAnBD,mCAAgC;AAChC,6DAAgE;AAEhE,SAAgB,eAAe,CAAC,MAG/B;IACC,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC;IAEhD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,EAAE,cAAc,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,QAAQ,GAAG,IAAA,aAAK,EAAC,YAAY,EAAE,6CAAwB,CAAC,CAAC;IAC/D,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC;IAC1C,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACnC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,UAAU,KAAK,GAAG,CAAC,EAAE;QACrF,YAAY,EAAE,GAAG;KAClB,CAAC,CAAC,CAAC;AACN,CAAC"}

package/src/lib/createDeterministicHash.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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

@@ -0,0 +1,25 @@
+"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

@@ -0,0 +1 @@
+{"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"}

package/src/lib/errorsInResult.d.ts

@@ -0,0 +1,9 @@
+import { type ErrorCode, type FailureResult, type ServiceResult } from "@clipboard-health/util-ts";
+import { type TriggerResponse } from "./types";
+/**
+ * Checks if a result contains specific error codes and is a failure result.
+ *
+ * @param result - ServiceResult containing an error or T.
+ * @param errorCodes - Array of error codes to check for. If empty, any error will match.
+ */
+export declare function errorsInResult<T = TriggerResponse>(result: ServiceResult<T>, errorCodes?: ErrorCode[]): result is FailureResult;

package/src/lib/errorsInResult.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorsInResult = errorsInResult;
+const util_ts_1 = require("@clipboard-health/util-ts");
+/**
+ * Checks if a result contains specific error codes and is a failure result.
+ *
+ * @param result - ServiceResult containing an error or T.
+ * @param errorCodes - Array of error codes to check for. If empty, any error will match.
+ */
+function errorsInResult(result, errorCodes = []) {
+    if ((0, util_ts_1.isSuccess)(result)) {
+        return false;
+    }
+    return (errorCodes.length === 0 || result.error.issues.some((issue) => errorCodes.includes(issue.code)));
+}
+//# sourceMappingURL=errorsInResult.js.map

package/src/lib/errorsInResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorsInResult.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/errorsInResult.ts"],"names":[],"mappings":";;AAeA,wCAWC;AA1BD,uDAKmC;AAInC;;;;;GAKG;AACH,SAAgB,cAAc,CAC5B,MAAwB,EACxB,aAA0B,EAAE;IAE5B,IAAI,IAAA,mBAAS,EAAC,MAAM,CAAC,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CACL,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAChG,CAAC;AACJ,CAAC"}

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

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

package/src/lib/internal/createTriggerLogParams.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTriggerLogParams = createTriggerLogParams;
+function createTriggerLogParams(params) {
+    const { attempt, destination, idempotencyKey, key, traceName } = params;
+    return {
+        attempt,
+        destination,
+        idempotencyKey,
+        key,
+        traceName,
+    };
+}
+//# sourceMappingURL=createTriggerLogParams.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,3 @@
+import type { TraceOptions } from "../types";
+import type { TriggerLogContext } from "./createTriggerLogParams";
+export declare function createTriggerTraceOptions(params: TriggerLogContext): TraceOptions;

package/src/lib/internal/createTriggerTraceOptions.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTriggerTraceOptions = createTriggerTraceOptions;
+function createTriggerTraceOptions(params) {
+    const { key, attempt, destination } = params;
+    return {
+        resource: `notification.${key}`,
+        // Don't include high cardinality tags like expiresAt and idempotencyKey.
+        tags: {
+            "span.kind": "producer",
+            component: "customer-notifications",
+            "messaging.system": "knock.app",
+            "messaging.operation": "publish",
+            "messaging.destination": destination,
+            "notification.attempt": attempt.toString(),
+        },
+    };
+}
+//# sourceMappingURL=createTriggerTraceOptions.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,9 @@
+/**
+ * Formats a phone number to E.164 format.
+ *
+ * If the phone number cannot be formatted (invalid format, missing country code, etc.),
+ * returns the original phone number unchanged.
+ */
+export declare function formatPhoneNumber(params: {
+    phoneNumber: string;
+}): string;

package/src/lib/internal/formatPhoneNumber.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPhoneNumber = formatPhoneNumber;
+const phone_number_1 = require("@clipboard-health/phone-number");
+const util_ts_1 = require("@clipboard-health/util-ts");
+/**
+ * Formats a phone number to E.164 format.
+ *
+ * If the phone number cannot be formatted (invalid format, missing country code, etc.),
+ * returns the original phone number unchanged.
+ */
+function formatPhoneNumber(params) {
+    const { phoneNumber } = params;
+    return (0, util_ts_1.pipe)((0, phone_number_1.formatPhoneNumber)({ phoneNumber, format: "E.164" }), util_ts_1.either.getOrElse(() => phoneNumber));
+}
+//# sourceMappingURL=formatPhoneNumber.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"formatPhoneNumber.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/formatPhoneNumber.ts"],"names":[],"mappings":";;AASA,8CAOC;AAhBD,iEAAyF;AACzF,uDAA8D;AAE9D;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,MAA+B;IAC/D,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IAE/B,OAAO,IAAA,cAAI,EACT,IAAA,gCAAkB,EAAC,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EACpD,gBAAC,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,CAC/B,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,12 @@
+import { type Logger } from "@clipboard-health/util-ts";
+import { Knock } from "@knocklabs/node";
+export declare class IdempotentKnock extends Knock {
+    logLevel: "warn";
+    maxRetries: number;
+    timeout: number;
+    protected idempotencyHeader: string;
+    constructor(params: {
+        apiKey: string;
+        logger: Logger;
+    });
+}

package/src/lib/internal/idempotentKnock.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotentKnock = void 0;
+const node_1 = require("@knocklabs/node");
+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.
+    timeout = 60_000; // Knock's default.
+    idempotencyHeader = "Idempotency-Key";
+    constructor(params) {
+        const { apiKey, logger } = params;
+        super({
+            apiKey,
+            logger: {
+                ...logger,
+                debug: logger.info,
+            },
+        });
+    }
+}
+exports.IdempotentKnock = IdempotentKnock;
+//# sourceMappingURL=idempotentKnock.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,4 @@
+export declare function redact(params: {
+    data: Record<string, unknown> | undefined;
+    keysToRedact: string[];
+}): Record<string, unknown> | undefined;

package/src/lib/internal/redact.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redact = redact;
+function redact(params) {
+    const { data, keysToRedact } = params;
+    if (!data) {
+        return data;
+    }
+    const redactedObject = {};
+    for (const [key, value] of Object.entries(data)) {
+        redactedObject[key] = redactValue({ keysToRedact, key, value });
+    }
+    return redactedObject;
+}
+function redactValue(params) {
+    const { value, key, keysToRedact } = params;
+    if (key && keysToRedact.includes(key)) {
+        return "[REDACTED]";
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((aValue) => redactValue({ keysToRedact, value: aValue }));
+    }
+    if (isPlainObject(value)) {
+        const redactedObject = {};
+        for (const [oKey, oValue] of Object.entries(value)) {
+            redactedObject[oKey] = redactValue({ keysToRedact, key: oKey, value: oValue });
+        }
+        return redactedObject;
+    }
+    return value;
+}
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+//# sourceMappingURL=redact.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/redact.ts"],"names":[],"mappings":";;AAAA,wBAgBC;AAhBD,SAAgB,MAAM,CAAC,MAGtB;IACC,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IAEtC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,cAAc,GAA4B,EAAE,CAAC;IACnD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,cAAc,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,WAAW,CAAC,MAAgE;IACnF,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IAE5C,IAAI,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,cAAc,GAA4B,EAAE,CAAC;QACnD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACnD,cAAc,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QACjF,CAAC;QAED,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,CAAC;AACrE,CAAC"}

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

@@ -0,0 +1,3 @@
+import { type Knock } from "@knocklabs/node";
+import type { TriggerBody } from "../types";
+export declare function toKnockBody(body: TriggerBody): Knock.Workflows.WorkflowTriggerParams;

package/src/lib/internal/toKnockBody.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toKnockBody = toKnockBody;
+const formatPhoneNumber_1 = require("./formatPhoneNumber");
+function toKnockBody(body) {
+    const { actor, cancellationKey, recipients, workplaceId, ...rest } = body;
+    return {
+        ...(actor ? { actor: toKnockRecipient(actor) } : {}),
+        ...(cancellationKey ? { cancellation_key: cancellationKey } : {}),
+        ...(workplaceId ? { tenant: workplaceId } : {}),
+        recipients: recipients.map(toKnockRecipient),
+        ...rest,
+    };
+}
+function toKnockRecipient(recipient) {
+    if (typeof recipient === "string") {
+        return recipient;
+    }
+    return toKnockInlineIdentifyUserRequest(recipient);
+}
+function toKnockInlineIdentifyUserRequest(recipient) {
+    const { channelData, createdAt, email, name, phoneNumber, timeZone, userId, ...rest } = recipient;
+    return {
+        id: userId,
+        ...(channelData ? { channel_data: channelData } : {}),
+        ...(createdAt ? { created_at: createdAt.toISOString() } : {}),
+        ...(email ? { email } : {}),
+        ...(name ? { name } : {}),
+        ...(phoneNumber ? { phone_number: (0, formatPhoneNumber_1.formatPhoneNumber)({ phoneNumber }) } : {}),
+        ...(timeZone ? { timezone: timeZone } : {}),
+        ...rest,
+    };
+}
+//# sourceMappingURL=toKnockBody.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toKnockBody.js","sourceRoot":"","sources":["../../../../../../packages/notifications/src/lib/internal/toKnockBody.ts"],"names":[],"mappings":";;AAKA,kCAUC;AAZD,2DAAwD;AAExD,SAAgB,WAAW,CAAC,IAAiB;IAC3C,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAE1E,OAAO;QACL,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAC5C,GAAG,IAAI;KACR,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,SAA2B;IACnD,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,gCAAgC,CAAC,SAAS,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,gCAAgC,CACvC,SAAoC;IAEpC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,CAAC;IAElG,OAAO;QACL,EAAE,EAAE,MAAM;QACV,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;QAC3C,GAAG,IAAI;KACR,CAAC;AACJ,CAAC"}

package/src/lib/notificationClient.d.ts

@@ -0,0 +1,109 @@
+import { type Logger, type ServiceResult } from "@clipboard-health/util-ts";
+import { IdempotentKnock } from "./internal/idempotentKnock";
+import type { AppendPushTokenRequest, AppendPushTokenResponse, Tracer, TriggerRequest, TriggerResponse, UpsertWorkplaceRequest, UpsertWorkplaceResponse } from "./types";
+export declare const MAXIMUM_RECIPIENTS_COUNT = 1000;
+export declare const ERROR_CODES: {
+    readonly recipientCountBelowMinimum: "recipientCountBelowMinimum";
+    readonly recipientCountAboveMaximum: "recipientCountAboveMaximum";
+    readonly expired: "expired";
+    readonly unknown: "unknown";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Client for sending notifications through third-party providers.
+ */
+export declare class NotificationClient {
+    private readonly logger;
+    private readonly provider;
+    private readonly tracer;
+    /**
+     * Creates a new NotificationClient instance.
+     *
+     * @param params.apiKey - API key for the third-party provider.
+     * @param params.logger - Logger instance for structured logging.
+     * @param params.tracer - Tracer instance for distributed tracing.
+     */
+    constructor(params: {
+        logger: Logger;
+        tracer: Tracer;
+    } & ({
+        provider?: never;
+        apiKey: string;
+    } | {
+        provider: IdempotentKnock;
+        apiKey?: never;
+    }));
+    /**
+     * Triggers a notification through third-party providers.
+     *
+     * This method handles:
+     * - Stale notifications prevention through expiration checks.
+     * - Logging with sensitive data redaction.
+     * - Distributed tracing with notification metadata.
+     * - Idempotency to prevent duplicate notifications.
+     * - Comprehensive error handling and logging.
+     *
+     * @returns Promise resolving to either an error or successful response.
+     *
+     * @example
+     * <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 });
+     * ```
+     *
+     * </embedex>
+     */
+    trigger(params: TriggerRequest): Promise<ServiceResult<TriggerResponse>>;
+    /**
+     * Append to a user's push tokens.
+     *
+     * @returns Promise resolving to either an error or successful response.
+     */
+    appendPushToken(params: AppendPushTokenRequest): Promise<ServiceResult<AppendPushTokenResponse>>;
+    /**
+     * Updates or creates a workplace (tenant) in Knock.
+     *
+     * @returns Promise resolving to either an error or successful response.
+     */
+    upsertWorkplace(params: UpsertWorkplaceRequest): Promise<ServiceResult<UpsertWorkplaceResponse>>;
+    private validateTriggerRequest;
+    private getExistingTokens;
+    private logTriggerRequest;
+    private logTriggerResponse;
+    private createAndLogError;
+}

package/src/lib/notificationClient.js

@@ -0,0 +1,307 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationClient = exports.ERROR_CODES = exports.MAXIMUM_RECIPIENTS_COUNT = void 0;
+const util_ts_1 = require("@clipboard-health/util-ts");
+const createTriggerLogParams_1 = require("./internal/createTriggerLogParams");
+const createTriggerTraceOptions_1 = require("./internal/createTriggerTraceOptions");
+const formatPhoneNumber_1 = require("./internal/formatPhoneNumber");
+const idempotentKnock_1 = require("./internal/idempotentKnock");
+const redact_1 = require("./internal/redact");
+const toKnockBody_1 = require("./internal/toKnockBody");
+const LOG_PARAMS = {
+    trigger: {
+        traceName: "notifications.trigger",
+        destination: "knock.workflows.trigger",
+    },
+    appendPushToken: {
+        traceName: "notifications.appendPushToken",
+        destination: "knock.users.setChannelData",
+    },
+    upsertWorkplace: {
+        traceName: "notifications.upsertWorkplace",
+        destination: "knock.tenants.set",
+    },
+};
+exports.MAXIMUM_RECIPIENTS_COUNT = 1000;
+exports.ERROR_CODES = {
+    recipientCountBelowMinimum: "recipientCountBelowMinimum",
+    recipientCountAboveMaximum: "recipientCountAboveMaximum",
+    expired: "expired",
+    unknown: "unknown",
+};
+/**
+ * Client for sending notifications through third-party providers.
+ */
+class NotificationClient {
+    logger;
+    provider;
+    tracer;
+    /**
+     * Creates a new NotificationClient instance.
+     *
+     * @param params.apiKey - API key for the third-party provider.
+     * @param params.logger - Logger instance for structured logging.
+     * @param params.tracer - Tracer instance for distributed tracing.
+     */
+    constructor(params) {
+        const { logger, tracer } = params;
+        this.logger = logger;
+        this.tracer = tracer;
+        this.provider =
+            "provider" in params
+                ? // eslint-disable-next-line unicorn/consistent-destructuring
+                    params.provider
+                : // eslint-disable-next-line unicorn/consistent-destructuring
+                    new idempotentKnock_1.IdempotentKnock({ apiKey: params.apiKey, logger });
+    }
+    /**
+     * Triggers a notification through third-party providers.
+     *
+     * This method handles:
+     * - Stale notifications prevention through expiration checks.
+     * - Logging with sensitive data redaction.
+     * - Distributed tracing with notification metadata.
+     * - Idempotency to prevent duplicate notifications.
+     * - Comprehensive error handling and logging.
+     *
+     * @returns Promise resolving to either an error or successful response.
+     *
+     * @example
+     * <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 });
+     * ```
+     *
+     * </embedex>
+     */
+    async trigger(params) {
+        const logParams = (0, createTriggerLogParams_1.createTriggerLogParams)({ ...params, ...LOG_PARAMS.trigger });
+        return await this.tracer.trace(logParams.traceName, (0, createTriggerTraceOptions_1.createTriggerTraceOptions)(logParams), async (span) => {
+            const validated = this.validateTriggerRequest({ ...params, span, logParams });
+            if ((0, util_ts_1.isFailure)(validated)) {
+                return validated;
+            }
+            try {
+                const { key, body, idempotencyKey, keysToRedact = [] } = validated.value;
+                this.logTriggerRequest({ logParams, body, keysToRedact });
+                const response = await this.provider.workflows.trigger(key, (0, toKnockBody_1.toKnockBody)(body), {
+                    idempotencyKey,
+                });
+                const id = response.workflow_run_id;
+                this.logTriggerResponse({ span, response, id, logParams });
+                return (0, util_ts_1.success)({ id });
+            }
+            catch (maybeError) {
+                const error = (0, util_ts_1.toError)(maybeError);
+                return this.createAndLogError({
+                    notificationError: {
+                        code: exports.ERROR_CODES.unknown,
+                        message: error.message,
+                    },
+                    span,
+                    logFunction: this.logger.error,
+                    logParams,
+                    metadata: { error },
+                });
+            }
+        });
+    }
+    /**
+     * Append to a user's push tokens.
+     *
+     * @returns Promise resolving to either an error or successful response.
+     */
+    async appendPushToken(params) {
+        const { channelId, userId, token } = params;
+        const logParams = { ...LOG_PARAMS.appendPushToken, userId, channelId };
+        try {
+            // Don't log the push token, it is sensitive.
+            this.logger.info(`${logParams.traceName} request`, logParams);
+            const existingTokens = await this.getExistingTokens({ userId, channelId, logParams });
+            this.logger.info(`${logParams.traceName} existing tokens`, {
+                ...logParams,
+                existingTokenCount: existingTokens.length,
+            });
+            const response = await this.provider.users.setChannelData(userId, channelId, {
+                data: { tokens: [...new Set([...existingTokens, token])] },
+            });
+            this.logger.info(`${logParams.traceName} response`, {
+                ...logParams,
+                // Don't log the actual response; push tokens are sensitive.
+                response: { tokenCount: "tokens" in response.data ? response.data.tokens.length : 0 },
+            });
+            return (0, util_ts_1.success)({ success: true });
+        }
+        catch (maybeError) {
+            const error = (0, util_ts_1.toError)(maybeError);
+            return this.createAndLogError({
+                notificationError: {
+                    code: exports.ERROR_CODES.unknown,
+                    message: error.message,
+                },
+                logFunction: this.logger.error,
+                logParams,
+                metadata: { error },
+            });
+        }
+    }
+    /**
+     * Updates or creates a workplace (tenant) in Knock.
+     *
+     * @returns Promise resolving to either an error or successful response.
+     */
+    async upsertWorkplace(params) {
+        const { workplaceId, ...body } = params;
+        const logParams = { ...LOG_PARAMS.upsertWorkplace, workplaceId, ...body };
+        try {
+            this.logger.info(`${logParams.traceName} request`, logParams);
+            body.phoneNumber &&= (0, formatPhoneNumber_1.formatPhoneNumber)({ phoneNumber: body.phoneNumber });
+            const response = await this.provider.tenants.set(workplaceId, body);
+            this.logger.info(`${logParams.traceName} response`, {
+                ...logParams,
+                response: { workplaceId: response.id, name: response.name },
+            });
+            return (0, util_ts_1.success)({
+                workplaceId: response.id,
+            });
+        }
+        catch (maybeError) {
+            const error = (0, util_ts_1.toError)(maybeError);
+            return this.createAndLogError({
+                notificationError: {
+                    code: exports.ERROR_CODES.unknown,
+                    message: error.message,
+                },
+                logFunction: this.logger.error,
+                logParams,
+                metadata: { error },
+            });
+        }
+    }
+    validateTriggerRequest(params) {
+        const { body, expiresAt, span, logParams } = params;
+        if (body.recipients.length <= 0) {
+            return this.createAndLogError({
+                notificationError: {
+                    code: exports.ERROR_CODES.recipientCountBelowMinimum,
+                    message: `Got ${body.recipients.length} recipients; must be > 0.`,
+                },
+                span,
+                logParams,
+            });
+        }
+        if (body.recipients.length > exports.MAXIMUM_RECIPIENTS_COUNT) {
+            const recipientsCount = body.recipients.length;
+            return this.createAndLogError({
+                notificationError: {
+                    code: exports.ERROR_CODES.recipientCountAboveMaximum,
+                    message: `Got ${recipientsCount} recipients; must be <= ${exports.MAXIMUM_RECIPIENTS_COUNT}.`,
+                },
+                span,
+                logParams,
+                metadata: { recipientsCount },
+            });
+        }
+        const now = new Date();
+        if (now > expiresAt) {
+            return this.createAndLogError({
+                notificationError: {
+                    code: exports.ERROR_CODES.expired,
+                    message: `Got ${now.toISOString()}; notification expires at ${expiresAt.toISOString()}.`,
+                },
+                span,
+                logParams,
+                metadata: { currentTime: now.toISOString(), expiresAt: expiresAt.toISOString() },
+            });
+        }
+        return (0, util_ts_1.success)(params);
+    }
+    async getExistingTokens(params) {
+        const { userId, channelId, logParams } = params;
+        // If existing tokens, use them; otherwise, start with empty array
+        try {
+            const response = await this.provider.users.getChannelData(userId, channelId);
+            return "tokens" in response.data ? response.data.tokens : [];
+        }
+        catch (maybeError) {
+            const error = (0, util_ts_1.toError)(maybeError);
+            if ("status" in error && error.status === 404) {
+                this.logger.info(`${logParams.traceName} no existing channel data`, logParams);
+                return [];
+            }
+            throw error;
+        }
+    }
+    logTriggerRequest(params) {
+        const { logParams, body, keysToRedact } = params;
+        this.logger.info(`${logParams.traceName} request`, {
+            ...logParams,
+            redactedBody: {
+                ...body,
+                // Don't log potentially sensitive recipient data.
+                recipients: body.recipients.length,
+                data: (0, redact_1.redact)({ data: body.data ?? undefined, keysToRedact }),
+            },
+        });
+    }
+    logTriggerResponse(params) {
+        const { span, response, id, logParams } = params;
+        span?.addTags({
+            "response.id": id,
+            success: true,
+        });
+        this.logger.info(`${logParams.traceName} response`, { ...logParams, id, response });
+        return id;
+    }
+    createAndLogError(params) {
+        const { logParams, notificationError, span, metadata, logFunction = this.logger.warn } = params;
+        const { code, message } = notificationError;
+        span?.addTags({
+            error: true,
+            "error.type": code,
+            "error.message": message,
+        });
+        logFunction(`${logParams.traceName} [${code}] ${message}`, {
+            ...logParams,
+            ...metadata,
+        });
+        return (0, util_ts_1.failure)(new util_ts_1.ServiceError({ issues: [{ code, message }] }));
+    }
+}
+exports.NotificationClient = NotificationClient;
+//# sourceMappingURL=notificationClient.js.map

package/src/lib/notificationClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notificationClient.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/notificationClient.ts"],"names":[],"mappings":"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"}

package/src/lib/types.d.ts

@@ -0,0 +1,174 @@
+export type Tags = Record<string, unknown>;
+export declare const MOBILE_PLATFORMS: readonly ["android", "ios"];
+export type MobilePlatform = (typeof MOBILE_PLATFORMS)[number];
+export interface TraceOptions {
+    resource?: string;
+    tags?: Tags;
+}
+export interface LogParams {
+    traceName: string;
+    destination: string;
+}
+export interface Span {
+    addTags: (tags: Tags) => void;
+}
+/**
+ * Tracer interface for distributed tracing operations.
+ */
+export interface Tracer {
+    trace<T>(name: string, options: TraceOptions, fun: (span?: Span) => T): T;
+}
+export interface PushChannelData {
+    /**
+     * A list of push channel tokens.
+     */
+    tokens: string[];
+}
+export type InlineChannelDataRequest = Record<string, PushChannelData>;
+/**
+ * Parameters to upsert and inline-identify a user, ensuring they exist before notifying them.
+ */
+export interface InlineIdentifyUserRequest {
+    /**
+     * The user ID.
+     */
+    userId: string;
+    /**
+     * The user's channel data.
+     */
+    channelData?: InlineChannelDataRequest;
+    /**
+     * The user's creation date.
+     */
+    createdAt?: Date | undefined;
+    /**
+     * The user's email address.
+     */
+    email?: string | undefined;
+    /**
+     * The user's display name.
+     */
+    name?: string | undefined;
+    /**
+     * The user's phone number.
+     */
+    phoneNumber?: string | undefined;
+    /**
+     * The user's [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for
+     * scheduled notifications.
+     */
+    timeZone?: string | undefined;
+}
+/**
+ * Specifies a recipient in a request. This can either be a user ID or an inline user request.
+ */
+export type RecipientRequest = string | InlineIdentifyUserRequest;
+export interface TriggerBody {
+    /**
+     * The recipients to trigger the workflow for. Limited to 1,000 recipients.
+     */
+    recipients: RecipientRequest[];
+    /**
+     * The trigger actor.
+     */
+    actor?: RecipientRequest;
+    /**
+     * An optional key used to reference a specific trigger request when issuing a cancellation
+     * request. You must provide it while triggering in order to enable subsequent cancellation and it
+     * should be unique across trigger requests to avoid unintentional cancellations.
+     */
+    cancellationKey?: string;
+    /**
+     * An optional map of data to pass into the trigger execution. Limited to 1024 bytes for each
+     * string and 10MB overall.
+     */
+    data?: Record<string, unknown>;
+    /**
+     * The associated workplace ID.
+     */
+    workplaceId?: string;
+}
+/**
+ * Request parameters for triggering a notification.
+ */
+export interface TriggerRequest {
+    /** Notification key. */
+    key: string;
+    /** Notification payload. */
+    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.
+     */
+    idempotencyKey: string;
+    /** Array of data keys to redact in logs for privacy. */
+    keysToRedact?: string[];
+    /** Expiration timestamp after which the request is dropped. */
+    expiresAt: Date;
+    /** Attempt number for tracking. */
+    attempt: number;
+}
+/**
+ * Response from triggering a notification.
+ */
+export interface TriggerResponse {
+    /** Third-party provider's unique identifier. */
+    id: string;
+}
+/**
+ * Request parameters for appending a push token.
+ */
+export interface AppendPushTokenRequest {
+    /** The channel ID. */
+    channelId: string;
+    /** The user ID. */
+    userId: string;
+    /** The push token to append. */
+    token: string;
+}
+/**
+ * Response from appending a push token.
+ */
+export interface AppendPushTokenResponse {
+    /** Whether the push token was appended successfully. */
+    success: boolean;
+}
+/**
+ * Request parameters for workplace upsert.
+ */
+export interface UpsertWorkplaceRequest {
+    /**
+     * The workplace's unique identifier.
+     */
+    workplaceId: string;
+    /**
+     * The workplace's creation date.
+     */
+    createdAt?: Date | undefined;
+    /**
+     * The workplace's email address.
+     */
+    email?: string | undefined;
+    /**
+     * The workplace's display name.
+     */
+    name?: string | undefined;
+    /**
+     * The workplace's phone number.
+     */
+    phoneNumber?: string | undefined;
+    /**
+     * The workplace's [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for
+     * scheduled notifications.
+     */
+    timeZone?: string | undefined;
+}
+/**
+ * Response after workplace upsert.
+ */
+export interface UpsertWorkplaceResponse {
+    /**
+     * The workplace's unique identifier.
+     */
+    workplaceId: string;
+}

package/src/lib/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOBILE_PLATFORMS = void 0;
+exports.MOBILE_PLATFORMS = ["android", "ios"];
+//# sourceMappingURL=types.js.map

package/src/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../packages/notifications/src/lib/types.ts"],"names":[],"mappings":";;;AAEa,QAAA,gBAAgB,GAAG,CAAC,SAAS,EAAE,KAAK,CAAU,CAAC"}