@clipboard-health/analytics 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @clipboard-health/analytics <!-- omit from toc -->
+
+Type-safe analytics wrapper around our third-party analytics provider for user identification and event tracking.
+
+## Table of contents <!-- omit from toc -->
+
+- [Install](#install)
+- [Usage](#usage)
+  - [Basic analytics tracking](#basic-analytics-tracking)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+```bash
+npm install @clipboard-health/analytics
+```
+
+## Usage
+
+### Basic analytics tracking
+
+<embedex source="packages/analytics/examples/analytics.ts">
+
+```ts
+import { Analytics } from "@clipboard-health/analytics";
+
+const logger = {
+  info: console.log,
+  warn: console.warn,
+  error: console.error,
+};
+
+{
+  // Basic usage with both features enabled
+  const analytics = new Analytics({
+    apiKey: "your-segment-write-key",
+    logger,
+    enabled: { identify: true, track: true },
+  });
+
+  // Identify a user
+  analytics.identify({
+    userId: "user-123",
+    traits: {
+      email: "user@example.com",
+      name: "John Doe",
+      createdAt: new Date("2023-01-01"),
+      type: "worker",
+    },
+  });
+
+  // Track an event
+  analytics.track({
+    userId: "user-123",
+    event: "Button Clicked",
+    traits: {
+      buttonName: "Apply",
+      page: "home",
+      plan: "worker",
+    },
+  });
+}
+
+{
+  // Disabled analytics example
+  const analytics = new Analytics({
+    apiKey: "your-segment-write-key",
+    logger,
+    enabled: { identify: false, track: false },
+  });
+
+  // These calls will be logged but not sent to Segment
+  analytics.identify({
+    userId: "user-789",
+    traits: { email: "test@example.com" },
+  });
+
+  analytics.track({
+    userId: "user-789",
+    event: "Page View",
+    traits: { page: "home" },
+  });
+}
+```
+
+</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/analytics",
+  "description": "",
+  "version": "0.1.0",
+  "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
+  "dependencies": {
+    "@clipboard-health/util-ts": "3.8.0",
+    "@segment/analytics-node": "2.3.0",
+    "libphonenumber-js": "1.12.10",
+    "tslib": "2.8.1"
+  },
+  "devDependencies": {
+    "@clipboard-health/testing-core": "0.17.0"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/analytics",
+    "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 @@
+export * from "./lib/analytics";

package/src/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/analytics"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/analytics/src/index.ts"],"names":[],"mappings":";;;AAAA,0DAAgC"}

package/src/lib/analytics.d.ts

@@ -0,0 +1,63 @@
+import { type Logger } from "@clipboard-health/util-ts";
+export type UserId = string | number;
+export interface CommonTraits {
+    createdAt?: Date;
+    email?: string;
+    name?: string;
+    phone?: string;
+    type?: string;
+}
+export type Traits = Record<string, unknown> & Readonly<CommonTraits>;
+export interface IdentifyRequest {
+    userId: UserId;
+    traits: Traits;
+}
+export interface TrackRequest {
+    userId: UserId;
+    event: string;
+    traits: Traits;
+}
+export interface Enabled {
+    identify: boolean;
+    track: boolean;
+}
+export declare class Analytics {
+    private readonly enabled;
+    private readonly logger;
+    private readonly segment;
+    /**
+     * Creates a new Analytics instance.
+     *
+     * @param params.apiKey - API key for the third-party provider.
+     * @param params.logger - Logger instance for structured logging.
+     * @param params.enabled - Whether or not analytics are enabled.
+     */
+    constructor(params: {
+        apiKey: string;
+        logger: Logger;
+        enabled: Enabled;
+    });
+    /**
+     * Identifies the user in our third-party analytics provider.
+     *
+     * @param request.userId ID of the user
+     * @param request.traits user traits
+     */
+    identify(params: IdentifyRequest): void;
+    /**
+     * Tracks a user event in our third-party analytics provider.
+     *
+     * @param request.userId ID of the user
+     * @param request.event name of the event
+     * @param request.traits event properties
+     */
+    track(params: TrackRequest): void;
+    /**
+     * Knock and Braze update user data based on Segment Identify events. Knock requires E.164 phone
+     * numbers and Braze prefers them.
+     *
+     * See https://docs.knock.app/api-reference/users/update
+     * See https://www.braze.com/docs/user_guide/message_building_by_channel/sms_mms_rcs/user_phone_numbers
+     */
+    private normalizeTraits;
+}

package/src/lib/analytics.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Analytics = void 0;
+const util_ts_1 = require("@clipboard-health/util-ts");
+const analytics_node_1 = require("@segment/analytics-node");
+const formatPhoneAsE164_1 = require("./formatPhoneAsE164");
+class Analytics {
+    enabled;
+    logger;
+    segment;
+    /**
+     * Creates a new Analytics instance.
+     *
+     * @param params.apiKey - API key for the third-party provider.
+     * @param params.logger - Logger instance for structured logging.
+     * @param params.enabled - Whether or not analytics are enabled.
+     */
+    constructor(params) {
+        const { apiKey, logger, enabled } = params;
+        this.segment = new analytics_node_1.Analytics({ writeKey: apiKey });
+        this.logger = logger;
+        this.enabled = enabled;
+    }
+    /**
+     * Identifies the user in our third-party analytics provider.
+     *
+     * @param request.userId ID of the user
+     * @param request.traits user traits
+     */
+    identify(params) {
+        const { userId, traits } = params;
+        if (!this.enabled.identify) {
+            this.logger.info("Analytics identify is disabled, skipping", { params });
+            return;
+        }
+        this.segment.identify({
+            userId: String(userId),
+            traits: this.normalizeTraits(traits),
+        });
+    }
+    /**
+     * Tracks a user event in our third-party analytics provider.
+     *
+     * @param request.userId ID of the user
+     * @param request.event name of the event
+     * @param request.traits event properties
+     */
+    track(params) {
+        const { userId, event, traits } = params;
+        if (!this.enabled.track) {
+            this.logger.info("Analytics tracking is disabled, skipping", {
+                params,
+            });
+            return;
+        }
+        this.segment.track({
+            userId: String(userId),
+            event,
+            properties: traits,
+        });
+    }
+    /**
+     * Knock and Braze update user data based on Segment Identify events. Knock requires E.164 phone
+     * numbers and Braze prefers them.
+     *
+     * See https://docs.knock.app/api-reference/users/update
+     * See https://www.braze.com/docs/user_guide/message_building_by_channel/sms_mms_rcs/user_phone_numbers
+     */
+    normalizeTraits(traits) {
+        const normalized = { ...traits };
+        if (traits.phone && typeof traits.phone === "string") {
+            const result = (0, formatPhoneAsE164_1.formatPhoneAsE164)({ phone: traits.phone });
+            if (util_ts_1.either.isLeft(result)) {
+                this.logger.error(result.left.issues.map((issue) => issue.message).join(", "), {
+                    phone: traits.phone,
+                });
+            }
+            else {
+                normalized.phone = result.right;
+            }
+        }
+        return normalized;
+    }
+}
+exports.Analytics = Analytics;
+//# sourceMappingURL=analytics.js.map

package/src/lib/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../../../../packages/analytics/src/lib/analytics.ts"],"names":[],"mappings":";;;AAAA,uDAAqE;AACrE,4DAAwE;AAExE,2DAAwD;AA8BxD,MAAa,SAAS;IACH,OAAO,CAAU;IACjB,MAAM,CAAS;IACf,OAAO,CAAmB;IAE3C;;;;;;OAMG;IACH,YAAY,MAA4D;QACtE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAE3C,IAAI,CAAC,OAAO,GAAG,IAAI,0BAAgB,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACI,QAAQ,CAAC,MAAuB;QACrC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAElC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0CAA0C,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;YACzE,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;YACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACtB,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;SACrC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,MAAoB;QAC/B,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAEzC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0CAA0C,EAAE;gBAC3D,MAAM;aACP,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACtB,KAAK;YACL,UAAU,EAAE,MAAM;SACnB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACK,eAAe,CAAC,MAAc;QACpC,MAAM,UAAU,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;QACjC,IAAI,MAAM,CAAC,KAAK,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrD,MAAM,MAAM,GAAG,IAAA,qCAAiB,EAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;YAE1D,IAAI,gBAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBACrB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;oBAC7E,KAAK,EAAE,MAAM,CAAC,KAAK;iBACpB,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YAClC,CAAC;QACH,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AAvFD,8BAuFC"}

package/src/lib/formatPhoneAsE164.d.ts

@@ -0,0 +1,4 @@
+import { either as E, ServiceError } from "@clipboard-health/util-ts";
+export declare function formatPhoneAsE164(params: {
+    phone: string;
+}): E.Either<ServiceError, string>;

package/src/lib/formatPhoneAsE164.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPhoneAsE164 = formatPhoneAsE164;
+const util_ts_1 = require("@clipboard-health/util-ts");
+const libphonenumber_js_1 = require("libphonenumber-js");
+function formatPhoneAsE164(params) {
+    const { phone } = params;
+    try {
+        return util_ts_1.either.right((0, libphonenumber_js_1.parsePhoneNumberWithError)(phone, { defaultCountry: "US" }).format("E.164"));
+    }
+    catch {
+        return util_ts_1.either.left(new util_ts_1.ServiceError({
+            issues: [{ message: "Invalid phone number", code: "INVALID_PHONE_NUMBER" }],
+        }));
+    }
+}
+//# sourceMappingURL=formatPhoneAsE164.js.map

package/src/lib/formatPhoneAsE164.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatPhoneAsE164.js","sourceRoot":"","sources":["../../../../../packages/analytics/src/lib/formatPhoneAsE164.ts"],"names":[],"mappings":";;AAGA,8CAYC;AAfD,uDAAsE;AACtE,yDAA8D;AAE9D,SAAgB,iBAAiB,CAAC,MAAyB;IACzD,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAEzB,IAAI,CAAC;QACH,OAAO,gBAAC,CAAC,KAAK,CAAC,IAAA,6CAAyB,EAAC,KAAK,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,gBAAC,CAAC,IAAI,CACX,IAAI,sBAAY,CAAC;YACf,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,sBAAsB,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;SAC5E,CAAC,CACH,CAAC;IACJ,CAAC;AACH,CAAC"}