@codeleap/analytics 6.3.0 → 7.0.0

package/dist/Analytics/index.d.ts

@@ -0,0 +1,19 @@
+import { AnyRecord } from '@codeleap/types';
+import { AnalyticsFunctions, AnalyticsOptions } from './types';
+export * from './types';
+/**
+ * Generic analytics dispatcher that merges shared context, obfuscates sensitive fields, and fans out to `onEvent` / `onInteraction` handlers.
+ * All tracking is silently skipped when `enabled` is false; errors are routed to `onError` rather than thrown.
+ */
+export declare class Analytics<Events extends AnyRecord> {
+    private options;
+    private functions;
+    private enabled;
+    private prepareAnalyticsData;
+    private obfuscateAnalyticsData;
+    constructor(options: AnalyticsOptions, functions: AnalyticsFunctions);
+    event<T extends keyof Events>(name: T, data?: Events[T]): void;
+    interaction<T extends keyof Events>(name: T, data?: Events[T]): void;
+    private handle;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/Analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Analytics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAExD,OAAO,EAAE,kBAAkB,EAAmB,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/E,cAAc,SAAS,CAAA;AAEvB;;;GAGG;AACH,qBAAa,SAAS,CAAC,MAAM,SAAS,SAAS;IAiB3C,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,SAAS;IAjBnB,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,sBAAsB;gBASpB,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,kBAAkB;IASvC,KAAK,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAE,MAAM,CAAC,CAAC,CAAmB;IAIxE,WAAW,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAE,MAAM,CAAC,CAAC,CAAmB;IAI9E,OAAO,CAAC,MAAM;CAkBf"}

package/dist/Analytics/types.d.ts

@@ -0,0 +1,26 @@
+import { Matcher } from '@codeleap/types';
+/** Normalized payload passed to `onEvent` and `onInteraction` handlers after data preparation and obfuscation. */
+export type AnalyticsObject = {
+    name: string;
+    type: 'interaction' | 'event';
+    data: any;
+};
+/** Callbacks that back-end integrations must implement; all three are required — `onError` is the safety net for failed tracking calls. */
+export type AnalyticsFunctions = {
+    onError: (err: any) => void;
+    onInteraction: (obj: AnalyticsObject) => void;
+    onEvent: (obj: AnalyticsObject) => void;
+};
+/**
+ * Configuration for an `Analytics` instance.
+ * `init` is called once at construction when `enabled` is true.
+ * `prepareData` is merged into every event payload, making it the right place for shared context (e.g. session id, app version).
+ */
+export type AnalyticsOptions = {
+    enabled: boolean;
+    obfuscateKeys: Matcher<'key'>[];
+    obfuscateValues: Matcher<'value'>[];
+    init: () => void;
+    prepareData: () => any;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/Analytics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/Analytics/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAEzC,kHAAkH;AAClH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,aAAa,GAAG,OAAO,CAAA;IAC7B,IAAI,EAAE,GAAG,CAAA;CACV,CAAA;AAED,2IAA2I;AAC3I,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC3B,aAAa,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IAC7C,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;CACxC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/B,eAAe,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,CAAA;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,CAAA;CACvB,CAAA"}

package/dist/Segment/index.d.ts

@@ -0,0 +1,28 @@
+import { SegmentUser, DefaultMode, SegmentMethods, SegmentConfig, AnyRecord } from './types';
+export * from './types';
+/**
+ * Platform-agnostic wrapper around a Segment analytics client.
+ * The underlying client is created via `createClient` at construction; all methods are no-ops until then or when `enabled` is false.
+ * Event names are automatically prefixed/suffixed per mode (e.g. `dev_` in dev) so staging traffic never pollutes prod workspaces.
+ * `identifyUser` is idempotent within a session — it calls `identify` at most once per instance.
+ */
+export declare class Segment<C extends SegmentMethods, U extends SegmentUser = SegmentUser, M extends string = DefaultMode> {
+    private config;
+    private _enabled;
+    private apiKey;
+    client: C | null;
+    identifiedUser: boolean;
+    get enabled(): boolean;
+    private get eventPrefix();
+    private get eventSuffix();
+    constructor(config: SegmentConfig<C, U, M>);
+    private buildEventName;
+    track<T extends AnyRecord>(eventName: string, properties?: T | undefined): Promise<void>;
+    screen(name: string, options?: AnyRecord | undefined): Promise<void>;
+    group(groupId: string, groupTraits?: AnyRecord | undefined): Promise<void>;
+    alias(newUserId: string): Promise<void>;
+    reset(): Promise<void>;
+    identifyUser(user: U): Promise<void>;
+    setMode(newMode: M): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/Segment/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Segment/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAElH,cAAc,SAAS,CAAA;AAWvB;;;;;GAKG;AACH,qBAAa,OAAO,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,SAAS,MAAM,GAAG,WAAW;IAChH,OAAO,CAAC,MAAM,CAA2F;IAEzG,OAAO,CAAC,QAAQ,CAAO;IAEvB,OAAO,CAAC,MAAM,CAAsB;IAE7B,MAAM,EAAE,CAAC,GAAG,IAAI,CAAO;IAEvB,cAAc,UAAQ;IAE7B,IAAW,OAAO,YAEjB;IAED,OAAO,KAAK,WAAW,GAGtB;IAED,OAAO,KAAK,WAAW,GAGtB;gBAEW,MAAM,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAqB1C,OAAO,CAAC,cAAc;IAIT,KAAK,CAAC,CAAC,SAAS,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAE,CAAC,GAAG,SAAqB;IAMnF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,SAAS,GAAG,SAAqB;IAM/D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,GAAE,SAAS,GAAG,SAAqB;IAMrE,KAAK,CAAC,SAAS,EAAE,MAAM;IAMvB,KAAK;IAML,YAAY,CAAC,IAAI,EAAE,CAAC;IAU1B,OAAO,CAAC,OAAO,EAAE,CAAC;CAM1B"}

package/dist/Segment/types.d.ts

@@ -0,0 +1,36 @@
+/** Loose record type used for arbitrary Segment event properties and traits. */
+export type AnyRecord = {
+    [x: string]: any;
+};
+/**
+ * Full constructor config for a `Segment` instance.
+ * `createClient` receives the write key and must return a platform-specific Segment client (e.g. `@segment/analytics-next` or the React Native SDK).
+ * `prefix` / `suffix` are keyed by mode so dev events can be namespaced without touching prod data.
+ */
+export type SegmentConfig<C, U extends SegmentUser, M extends string = DefaultMode> = {
+    apiKey: string;
+    enabled?: boolean;
+    getUserTraits: (user: U) => AnyRecord;
+    mode: M;
+    prefix?: Record<M, string | null>;
+    suffix?: Record<M, string | null>;
+    createClient: (writeKey: string) => C;
+};
+/** Structural contract that the platform-specific Segment client must satisfy; lets `Segment<C>` stay platform-agnostic. */
+export type SegmentMethods = {
+    track: (eventName: string, properties?: AnyRecord) => Promise<void>;
+    screen: (name: string, options?: AnyRecord) => Promise<void>;
+    group: (groupId: string, groupTraits?: AnyRecord) => Promise<void>;
+    alias: (newUserId: string) => Promise<void>;
+    reset: () => Promise<void>;
+    identify: (userId: string, userTraits?: AnyRecord) => Promise<void>;
+};
+/** Minimum shape required for a user object passed to `identifyUser`; extend this type to carry additional traits. */
+export type SegmentUser = {
+    id: string;
+};
+/** The two built-in deployment modes; custom modes can be added by passing a wider string union as `M`. */
+export type DefaultMode = 'dev' | 'prod';
+/** Subset of `SegmentConfig` stored at runtime — excludes `apiKey`, `createClient`, and `enabled` which are consumed at construction. */
+export type SegmentGeneralConfig<C, U extends SegmentUser, M extends string> = Omit<SegmentConfig<C, U, M>, 'apiKey' | 'createClient' | 'enabled'>;
+//# sourceMappingURL=types.d.ts.map

package/dist/Segment/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/Segment/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG;IACtB,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CACjB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,MAAM,GAAG,WAAW,IAAI;IACpF,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAA;IACrC,IAAI,EAAE,CAAC,CAAA;IACP,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;IACjC,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,CAAC,CAAA;CACtC,CAAA;AAED,4HAA4H;AAC5H,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACpE,CAAA;AAED,sHAAsH;AACtH,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAA;CACX,CAAA;AAED,2GAA2G;AAC3G,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,CAAA;AAExC,yIAAyI;AACzI,MAAM,MAAM,oBAAoB,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,MAAM,IAAI,IAAI,CACjF,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACtB,QAAQ,GAAG,cAAc,GAAG,SAAS,CACtC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Segment';
+export * from './Analytics';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA"}

package/dist/obfuscate.d.ts

@@ -0,0 +1,13 @@
+import { Matcher } from '@codeleap/types';
+type ObfuscateArgs = {
+    object: any;
+    keys: (Matcher<'key'>)[];
+    values: (Matcher<'value'>)[];
+};
+/**
+ * Deep-clones `object` and replaces matched keys with `"[secret]"` and matched values with `"[secret]"` (or strips query strings from URLs).
+ * Handles circular references gracefully by returning a shallow copy with a `WARNING` flag instead of throwing.
+ */
+export declare function obfuscate(args: ObfuscateArgs): any;
+export {};
+//# sourceMappingURL=obfuscate.d.ts.map

package/dist/obfuscate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"obfuscate.d.ts","sourceRoot":"","sources":["../src/obfuscate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAIzC,KAAK,aAAa,GAAG;IACnB,MAAM,EAAE,GAAG,CAAA;IACX,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAA;IACxB,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,CAAA;CAC7B,CAAA;AAkCD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,OAgC5C"}

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@codeleap/analytics",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "main": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "license": "UNLICENSED",
   "repository": {
     "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
@@ -9,15 +22,18 @@
     "directory": "packages/analytics"
   },
   "devDependencies": {
-    "@codeleap/config": "6.3.0",
+    "@codeleap/config": "7.0.0",
+    "@codeleap/types": "7.0.0",
+    "@codeleap/utils": "7.0.0",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
-    "build": "echo 'No build needed'"
+    "build": "tsc --build tsconfig.build.json",
+    "typecheck": "bun tsc --noEmit -p ./tsconfig.json"
   },
   "peerDependencies": {
-    "@codeleap/utils": "6.3.0",
-    "@codeleap/types": "6.3.0",
+    "@codeleap/utils": "7.0.0",
+    "@codeleap/types": "7.0.0",
     "typescript": "5.5.2"
   }
-}
+}

package/src/Analytics/index.ts

@@ -4,6 +4,10 @@ import { AnalyticsFunctions, AnalyticsObject, AnalyticsOptions } from './types'
 
 export * from './types'
 
+/**
+ * Generic analytics dispatcher that merges shared context, obfuscates sensitive fields, and fans out to `onEvent` / `onInteraction` handlers.
+ * All tracking is silently skipped when `enabled` is false; errors are routed to `onError` rather than thrown.
+ */
 export class Analytics<Events extends AnyRecord> {
   private enabled: boolean
 

package/src/Analytics/types.ts

@@ -1,17 +1,24 @@
 import { Matcher } from '@codeleap/types'
 
+/** Normalized payload passed to `onEvent` and `onInteraction` handlers after data preparation and obfuscation. */
 export type AnalyticsObject = {
   name: string
   type: 'interaction' | 'event'
   data: any
 }
 
+/** Callbacks that back-end integrations must implement; all three are required — `onError` is the safety net for failed tracking calls. */
 export type AnalyticsFunctions = {
   onError: (err: any) => void
   onInteraction: (obj: AnalyticsObject) => void
   onEvent: (obj: AnalyticsObject) => void
 }
 
+/**
+ * Configuration for an `Analytics` instance.
+ * `init` is called once at construction when `enabled` is true.
+ * `prepareData` is merged into every event payload, making it the right place for shared context (e.g. session id, app version).
+ */
 export type AnalyticsOptions = {
   enabled: boolean
   obfuscateKeys: Matcher<'key'>[]

package/src/Segment/index.ts

@@ -11,6 +11,12 @@ const defaultConfig: SegmentGeneralConfig<any, SegmentUser, DefaultMode> = {
   },
 }
 
+/**
+ * Platform-agnostic wrapper around a Segment analytics client.
+ * The underlying client is created via `createClient` at construction; all methods are no-ops until then or when `enabled` is false.
+ * Event names are automatically prefixed/suffixed per mode (e.g. `dev_` in dev) so staging traffic never pollutes prod workspaces.
+ * `identifyUser` is idempotent within a session — it calls `identify` at most once per instance.
+ */
 export class Segment<C extends SegmentMethods, U extends SegmentUser = SegmentUser, M extends string = DefaultMode> {
   private config: SegmentGeneralConfig<C, U, M> = defaultConfig as unknown as SegmentGeneralConfig<C, U, M>
 

package/src/Segment/types.ts

@@ -1,7 +1,13 @@
+/** Loose record type used for arbitrary Segment event properties and traits. */
 export type AnyRecord = {
   [x: string]: any
 }
 
+/**
+ * Full constructor config for a `Segment` instance.
+ * `createClient` receives the write key and must return a platform-specific Segment client (e.g. `@segment/analytics-next` or the React Native SDK).
+ * `prefix` / `suffix` are keyed by mode so dev events can be namespaced without touching prod data.
+ */
 export type SegmentConfig<C, U extends SegmentUser, M extends string = DefaultMode> = {
   apiKey: string
   enabled?: boolean
@@ -12,6 +18,7 @@ export type SegmentConfig<C, U extends SegmentUser, M extends string = DefaultMo
   createClient: (writeKey: string) => C
 }
 
+/** Structural contract that the platform-specific Segment client must satisfy; lets `Segment<C>` stay platform-agnostic. */
 export type SegmentMethods = {
   track: (eventName: string, properties?: AnyRecord) => Promise<void>
   screen: (name: string, options?: AnyRecord) => Promise<void>
@@ -21,12 +28,15 @@ export type SegmentMethods = {
   identify: (userId: string, userTraits?: AnyRecord) => Promise<void>
 }
 
+/** Minimum shape required for a user object passed to `identifyUser`; extend this type to carry additional traits. */
 export type SegmentUser = {
   id: string
 }
 
+/** The two built-in deployment modes; custom modes can be added by passing a wider string union as `M`. */
 export type DefaultMode = 'dev' | 'prod'
 
+/** Subset of `SegmentConfig` stored at runtime — excludes `apiKey`, `createClient`, and `enabled` which are consumed at construction. */
 export type SegmentGeneralConfig<C, U extends SegmentUser, M extends string> = Omit<
   SegmentConfig<C, U, M>,
   'apiKey' | 'createClient' | 'enabled'

package/src/obfuscate.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { cloneDeep } from '@codeleap/utils'
 import { Matcher } from '@codeleap/types'
 import { inspect } from 'util'
@@ -9,7 +10,7 @@ type ObfuscateArgs = {
   values: (Matcher<'value'>)[]
 }
 
-function removeKey(obj, key) {
+function removeKey(obj: Record<string, any>, key: any) {
   if (obj?.hasOwnProperty(key)) {
     obj[key] = '[secret]'
   }
@@ -20,7 +21,7 @@ function removeKey(obj, key) {
   }
 }
 
-function removeValue(obj, value) {
+function removeValue(obj: Record<string, any>, value: any) {
   for (const subObj in obj) {
     const isString = typeof obj[subObj] == 'string'
     if (isString) {
@@ -41,6 +42,10 @@ function removeValue(obj, value) {
   }
 }
 
+/**
+ * Deep-clones `object` and replaces matched keys with `"[secret]"` and matched values with `"[secret]"` (or strips query strings from URLs).
+ * Handles circular references gracefully by returning a shallow copy with a `WARNING` flag instead of throwing.
+ */
 export function obfuscate(args: ObfuscateArgs) {
   const { object, keys, values } = args
 

package/package.json.bak

@@ -1,23 +0,0 @@
-{
-  "name": "@codeleap/analytics",
-  "version": "6.3.0",
-  "main": "src/index.ts",
-  "license": "UNLICENSED",
-  "repository": {
-    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
-    "type": "git",
-    "directory": "packages/analytics"
-  },
-  "devDependencies": {
-    "@codeleap/config": "workspace:*",
-    "ts-node-dev": "1.1.8"
-  },
-  "scripts": {
-    "build": "echo 'No build needed'"
-  },
-  "peerDependencies": {
-    "@codeleap/utils": "workspace:*",
-    "@codeleap/types": "workspace:*",
-    "typescript": "5.5.2"
-  }
-}