@nu-art/analytics-backend 0.400.7

package/_modules/ModuleBE_Analytics.d.ts

@@ -0,0 +1,19 @@
+import { Module } from '@nu-art/ts-common';
+import { AnalyticsPlugin_Base } from '../plugins/AnalyticsPlugin_Base.js';
+import { AnalyticsPluginRegistry } from '../plugins/index.js';
+type Config = {
+    plugins: {
+        [K in keyof AnalyticsPluginRegistry]: AnalyticsPluginRegistry[K] extends AnalyticsPlugin_Base<any, infer C> ? C : never;
+    };
+};
+declare class ModuleBE_Analytics_Class extends Module<Config> {
+    private readonly plugins;
+    protected init(): void;
+    addPlugin(plugin: AnalyticsPlugin_Base): void;
+    removePlugin(plugin: AnalyticsPlugin_Base): void;
+    private initPlugins;
+    private api_sendEvent;
+    private api_updateUser;
+}
+export declare const ModuleBE_Analytics: ModuleBE_Analytics_Class;
+export {};

package/_modules/ModuleBE_Analytics.js

@@ -0,0 +1,40 @@
+import { Module } from '@nu-art/ts-common';
+import { addRoutes, createBodyServerApi } from '@nu-art/thunderstorm-backend';
+import { ApiDef_Analytics } from '@nu-art/analytics-shared';
+class ModuleBE_Analytics_Class extends Module {
+    plugins = new Map();
+    init() {
+        super.init();
+        this.initPlugins();
+        addRoutes([
+            createBodyServerApi(ApiDef_Analytics()._v1.sendEvent, this.api_sendEvent),
+            createBodyServerApi(ApiDef_Analytics()._v1.updateUser, this.api_updateUser),
+        ]);
+    }
+    //######################### Plugin Management #########################
+    addPlugin(plugin) {
+        this.plugins.set(plugin.key, plugin);
+    }
+    removePlugin(plugin) {
+        this.plugins.delete(plugin.key);
+    }
+    initPlugins() {
+        this.plugins.forEach(plugin => {
+            const key = plugin.key;
+            const pluginConfig = this.config.plugins[key];
+            plugin.init(pluginConfig);
+        });
+    }
+    //######################### API Callbacks #########################
+    api_sendEvent = async (request) => {
+        return this.plugins.forEach(plugin => {
+            plugin.registerEvent(request.event);
+        });
+    };
+    api_updateUser = async (request) => {
+        return this.plugins.forEach(plugin => {
+            plugin.updateUser?.(request);
+        });
+    };
+}
+export const ModuleBE_Analytics = new ModuleBE_Analytics_Class();

package/index.d.ts

@@ -0,0 +1 @@
+export * from './_modules/ModuleBE_Analytics.js';

package/index.js

@@ -0,0 +1 @@
+export * from './_modules/ModuleBE_Analytics.js';

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nu-art/analytics-backend",
+  "version": "0.400.7",
+  "description": "analytics Backend",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsc"
+  },
+  "publishConfig": {
+    "directory": "dist",
+    "linkDirectory": true
+  },
+  "dependencies": {
+    "@nu-art/analytics-shared": "0.400.7",
+    "@nu-art/ts-common": "0.400.7",
+    "@nu-art/firebase-backend": "0.400.7",
+    "@nu-art/firebase-shared": "0.400.7",
+    "@nu-art/thunderstorm-backend": "0.400.7",
+    "@nu-art/thunderstorm-shared": "0.400.7",
+    "mixpanel": "~0.18.1"
+  },
+  "devDependencies": {},
+  "private": false,
+  "unitConfig": {
+    "type": "typescript-lib"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./*": {
+      "types": "./*.d.ts",
+      "import": "./*.js"
+    }
+  }
+}

package/plugins/AnalyticsPlugin_Base.d.ts

@@ -0,0 +1,41 @@
+import { Analytics_UpdateUser, TSAnalyticsEvent } from '@nu-art/analytics-shared';
+import { Logger } from '@nu-art/ts-common';
+import { AnalyticsPluginBaseConfig } from './types.js';
+/**
+ * C - plugin specific config, to be used later in interface implementations
+ * R - Translation response
+ */
+export declare abstract class AnalyticsPlugin_Base<R extends any = any, C extends AnalyticsPluginBaseConfig = AnalyticsPluginBaseConfig> extends Logger {
+    /**
+     * Unique key used to identify this plugin and retrieve its config.
+     * Example: 'mixpanel', 'amplitude', 'customLogger'
+     */
+    abstract readonly key: string;
+    /**
+     * the config of the plugin, keeping important plugin specific data
+     * @private
+     */
+    protected config: C | undefined;
+    /**
+     * An event buffer, to packet the events into groups so they can later be bulk sent
+     * @private
+     */
+    private eventBuffer;
+    /**
+     * A debouncer for the "Empty event buffer" functionality.
+     * @private
+     */
+    private debounce_EmptyEventBuffer;
+    /**
+     * A queue for sending the events to the provider.
+     * @private
+     */
+    private queue_Events;
+    protected abstract translateEvent(event: TSAnalyticsEvent): R;
+    protected abstract sendEvents: (events: R[]) => Promise<void>;
+    protected abstract updateUser_Impl: undefined | ((mode: Analytics_UpdateUser['request']['mode'], data: Analytics_UpdateUser['request']['userData']) => Promise<void>);
+    init(config: C): void;
+    private emptyEventBuffer;
+    registerEvent(event: TSAnalyticsEvent): void;
+    updateUser(request: Analytics_UpdateUser['request']): void;
+}

package/plugins/AnalyticsPlugin_Base.js

@@ -0,0 +1,61 @@
+import { debounce, Logger, LogLevel } from '@nu-art/ts-common';
+import { QueueV2 } from '@nu-art/ts-common/utils/queue-v2';
+/**
+ * C - plugin specific config, to be used later in interface implementations
+ * R - Translation response
+ */
+export class AnalyticsPlugin_Base extends Logger {
+    /**
+     * the config of the plugin, keeping important plugin specific data
+     * @private
+     */
+    config;
+    /**
+     * An event buffer, to packet the events into groups so they can later be bulk sent
+     * @private
+     */
+    eventBuffer = [];
+    /**
+     * A debouncer for the "Empty event buffer" functionality.
+     * @private
+     */
+    debounce_EmptyEventBuffer = debounce(() => this.emptyEventBuffer(), 200, 2000);
+    /**
+     * A queue for sending the events to the provider.
+     * @private
+     */
+    queue_Events = new QueueV2('plugin-events', e => this.sendEvents(e));
+    //######################### Initialization #########################
+    init(config) {
+        this.config = config;
+        const tag = `AnalyticsPlugin_${this.key}`;
+        this.setTag(tag);
+        this.setMinLevel(LogLevel.Info);
+        const message = `Loaded - ${this.config.active ? 'Active' : 'Inactive'}`;
+        this.logInfo(message);
+    }
+    //######################### Internal Logic #########################
+    emptyEventBuffer = () => {
+        if (this.eventBuffer.length === 0)
+            return;
+        this.queue_Events.addItem([...this.eventBuffer]);
+        this.eventBuffer = [];
+    };
+    //######################### Public Logic #########################
+    registerEvent(event) {
+        if (!this.config?.active)
+            return;
+        const translatedEvent = this.translateEvent(event);
+        this.eventBuffer.push(translatedEvent);
+        //If the max packet size has not been reached
+        if (this.eventBuffer.length < (this.config.eventPacketSize ?? 0))
+            return this.debounce_EmptyEventBuffer();
+        //Max packet size has been reached, empty the buffer now
+        this.emptyEventBuffer();
+    }
+    updateUser(request) {
+        if (!this.config?.active)
+            return;
+        this.updateUser_Impl?.(request.mode, request.userData);
+    }
+}

package/plugins/AnalyticsPlugin_Logger.d.ts

@@ -0,0 +1,9 @@
+import { TSAnalyticsEvent } from '@nu-art/analytics-shared';
+import { AnalyticsPlugin_Base } from './AnalyticsPlugin_Base.js';
+export declare const pluginKey_Logger = "logger";
+export declare class AnalyticsPlugin_Logger extends AnalyticsPlugin_Base {
+    key: string;
+    protected translateEvent(event: TSAnalyticsEvent): TSAnalyticsEvent;
+    protected updateUser_Impl: undefined;
+    protected sendEvents: (events: any[]) => Promise<void>;
+}

package/plugins/AnalyticsPlugin_Logger.js

@@ -0,0 +1,14 @@
+import { AnalyticsPlugin_Base } from './AnalyticsPlugin_Base.js';
+export const pluginKey_Logger = 'logger';
+export class AnalyticsPlugin_Logger extends AnalyticsPlugin_Base {
+    key = pluginKey_Logger;
+    translateEvent(event) {
+        return event;
+    }
+    updateUser_Impl = undefined;
+    sendEvents = async (events) => {
+        this.logInfoBold('######## Analytics Event - Start ########');
+        this.logInfo(events);
+        this.logInfoBold('######## Analytics Event - End ########');
+    };
+}

package/plugins/AnalyticsPlugin_MixedPanels.d.ts

@@ -0,0 +1,30 @@
+import { Analytics_UpdateUser, TSAnalyticsEvent } from '@nu-art/analytics-shared';
+import { AnalyticsPlugin_Base } from './AnalyticsPlugin_Base.js';
+import mixpanelLib from 'mixpanel';
+import { TypedMap } from '@nu-art/ts-common';
+import { AnalyticPanelConfig } from './types.js';
+type MixedPanelsEventProperties = {
+    distinct_id: string;
+    time: number;
+    $session_id?: string;
+    $groups?: TypedMap<string>;
+    [key: string]: any;
+};
+type MixedPanelsEvent = {
+    event: string;
+    properties: MixedPanelsEventProperties;
+};
+export declare const pluginKey_MixedPanels = "mixed-panels";
+type MPConfig = AnalyticPanelConfig<{
+    mxConfig?: Partial<mixpanelLib.InitConfig>;
+}>;
+export declare class AnalyticsPlugin_MixedPanels extends AnalyticsPlugin_Base<MixedPanelsEvent, MPConfig> {
+    readonly key = "mixed-panels";
+    private mixpanel;
+    init(config: MPConfig): void;
+    private prepareUserProps;
+    protected translateEvent(event: TSAnalyticsEvent): MixedPanelsEvent;
+    protected sendEvents: (events: MixedPanelsEvent[]) => Promise<void>;
+    protected updateUser_Impl: (mode: Analytics_UpdateUser["request"]["mode"], data: Analytics_UpdateUser["request"]["userData"]) => Promise<void>;
+}
+export {};

package/plugins/AnalyticsPlugin_MixedPanels.js

@@ -0,0 +1,98 @@
+import { AnalyticsPlugin_Base } from './AnalyticsPlugin_Base.js';
+import mixpanelLib from 'mixpanel';
+import { _keys, BadImplementationException, exists, MissingDataException } from '@nu-art/ts-common';
+export const pluginKey_MixedPanels = 'mixed-panels';
+export class AnalyticsPlugin_MixedPanels extends AnalyticsPlugin_Base {
+    key = pluginKey_MixedPanels;
+    mixpanel;
+    init(config) {
+        super.init(config);
+        if (!config.token) {
+            if (config.active)
+                throw new MissingDataException(`Missing token for analytics plugin "${pluginKey_MixedPanels}"`);
+            else
+                return;
+        }
+        this.mixpanel = mixpanelLib.init(config.token, config.mxConfig);
+    }
+    //######################### Internal Logic #########################
+    prepareUserProps = (data) => {
+        const { userId, ...rest } = data;
+        const props = {};
+        _keys(rest).forEach(key => {
+            switch (key) {
+                case 'firstName':
+                    props.$first_name = rest[key];
+                    break;
+                case 'lastName':
+                    props.$last_name = rest[key];
+                    break;
+                case 'displayName':
+                    props.$name = rest[key];
+                    break;
+                default:
+                    props[key] = rest[key];
+            }
+        });
+        return props;
+    };
+    //######################### Implemented Logic #########################
+    translateEvent(event) {
+        return {
+            event: event.key,
+            properties: {
+                distinct_id: event.userId ?? 'unknown',
+                time: Math.floor(event.timestamp / 1000), //Mixed panels expects seconds
+                ...(exists(event.context) ? event.context : {}),
+                ...(exists(event.properties) ? event.properties : {}),
+                ...(exists(event.groups) ? event.groups : {}),
+                ...(exists(event.sessionId) ? { $session_id: event.sessionId } : {}),
+            }
+        };
+    }
+    sendEvents = async (events) => {
+        if (!this.mixpanel)
+            throw new BadImplementationException(`Calling send before analytics plugin ${pluginKey_MixedPanels} finished initializing`);
+        return new Promise((resolve, reject) => {
+            this.logDebug('Sending Events', events);
+            this.mixpanel.track_batch(events, {}, (errors) => {
+                if (errors?.length) {
+                    this.logError(errors);
+                    reject(errors);
+                }
+                else {
+                    this.logDebug('Events Sent');
+                    resolve();
+                }
+            });
+        });
+    };
+    updateUser_Impl = (mode, data) => {
+        if (!this.mixpanel)
+            throw new BadImplementationException(`Calling update user before analytics plugin ${pluginKey_MixedPanels} finished initializing`);
+        return new Promise((resolve, reject) => {
+            this.logDebug('Updating user', data);
+            const userProps = this.prepareUserProps(data);
+            const cb = (err) => {
+                if (err) {
+                    this.logError(err);
+                    reject(err);
+                }
+                else {
+                    this.logDebug('Successfully updated user');
+                    resolve();
+                }
+            };
+            switch (mode) {
+                case 'set':
+                    this.mixpanel?.people.set(data.userId, userProps, cb);
+                    break;
+                case 'set_once':
+                    this.mixpanel?.people.set_once(data.userId, userProps, cb);
+                    break;
+                default:
+                    throw new BadImplementationException(`No Implementation for mode ${mode}`);
+            }
+        });
+    };
+}

package/plugins/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './registry.js';
+export * from './AnalyticsPlugin_Logger.js';
+export * from './AnalyticsPlugin_MixedPanels.js';

package/plugins/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './registry.js';
+export * from './AnalyticsPlugin_Logger.js';
+export * from './AnalyticsPlugin_MixedPanels.js';

package/plugins/registry.d.ts

@@ -0,0 +1,6 @@
+import { AnalyticsPlugin_Logger, pluginKey_Logger } from './AnalyticsPlugin_Logger.js';
+import { AnalyticsPlugin_MixedPanels, pluginKey_MixedPanels } from './AnalyticsPlugin_MixedPanels.js';
+export type AnalyticsPluginRegistry = {
+    [pluginKey_Logger]: AnalyticsPlugin_Logger;
+    [pluginKey_MixedPanels]: AnalyticsPlugin_MixedPanels;
+};

package/plugins/registry.js

@@ -0,0 +1,2 @@
+import { pluginKey_Logger } from './AnalyticsPlugin_Logger.js';
+import { pluginKey_MixedPanels } from './AnalyticsPlugin_MixedPanels.js';

package/plugins/types.d.ts

@@ -0,0 +1,6 @@
+export type AnalyticsPluginBaseConfig = {
+    active: boolean;
+    token?: string;
+    eventPacketSize?: number;
+};
+export type AnalyticPanelConfig<C> = AnalyticsPluginBaseConfig & C;

package/plugins/types.js

@@ -0,0 +1 @@
+export {};