@dereekb/analytics 13.4.0

package/nestjs/index.esm.js

@@ -0,0 +1,641 @@
+import { Injectable, Inject, Logger, Module, SetMetadata } from '@nestjs/common';
+import { Analytics } from '@segment/analytics-node';
+import { ConfigService, ConfigModule } from '@nestjs/config';
+import { ServerEnvironmentService } from '@dereekb/nestjs';
+import { tap } from 'rxjs/operators';
+
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function __decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if ((typeof Reflect === "undefined" ? "undefined" : _type_of(Reflect)) === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function __param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+function _class_call_check$4(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _defineProperties$3(target, props) {
+    for(var i = 0; i < props.length; i++){
+        var descriptor = props[i];
+        descriptor.enumerable = descriptor.enumerable || false;
+        descriptor.configurable = true;
+        if ("value" in descriptor) descriptor.writable = true;
+        Object.defineProperty(target, descriptor.key, descriptor);
+    }
+}
+function _create_class$3(Constructor, protoProps, staticProps) {
+    if (staticProps) _defineProperties$3(Constructor, staticProps);
+    return Constructor;
+}
+function _define_property$3(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * Configuration for the Segment analytics service.
+ */ var SegmentServiceConfig = /*#__PURE__*/ function() {
+    function SegmentServiceConfig() {
+        _class_call_check$4(this, SegmentServiceConfig);
+        /**
+     * Segment write key for the source.
+     */ _define_property$3(this, "writeKey", void 0);
+        /**
+     * When true, events are logged to the console instead of sent to Segment.
+     */ _define_property$3(this, "logOnly", void 0);
+        /**
+     * Optional application context included in all Segment event contexts.
+     */ _define_property$3(this, "appContext", void 0);
+    }
+    _create_class$3(SegmentServiceConfig, null, [
+        {
+            key: "assertValidConfig",
+            value: /**
+     * Validates that the given config has the required fields (e.g., a non-empty write key).
+     *
+     * @param config - The config instance to validate.
+     * @throws {Error} When the write key is missing or empty.
+     *
+     * @example
+     * ```ts
+     * SegmentServiceConfig.assertValidConfig(config);
+     * ```
+     */ function assertValidConfig(config) {
+                if (!config.writeKey) {
+                    throw new Error('No Segment write key specified.');
+                }
+            }
+        }
+    ]);
+    return SegmentServiceConfig;
+} 
+();
+
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _class_call_check$3(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _defineProperties$2(target, props) {
+    for(var i = 0; i < props.length; i++){
+        var descriptor = props[i];
+        descriptor.enumerable = descriptor.enumerable || false;
+        descriptor.configurable = true;
+        if ("value" in descriptor) descriptor.writable = true;
+        Object.defineProperty(target, descriptor.key, descriptor);
+    }
+}
+function _create_class$2(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties$2(Constructor.prototype, protoProps);
+    return Constructor;
+}
+function _define_property$2(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * Injectable wrapper around the Segment Analytics Node SDK.
+ *
+ * Manages the Analytics client lifecycle, including flushing on module destroy.
+ */ var SegmentApi = /*#__PURE__*/ function() {
+    function SegmentApi(config) {
+        _class_call_check$3(this, SegmentApi);
+        _define_property$2(this, "config", void 0);
+        _define_property$2(this, "analytics", void 0);
+        this.config = config;
+        this.analytics = new Analytics({
+            writeKey: this.config.writeKey
+        });
+    }
+    _create_class$2(SegmentApi, [
+        {
+            key: "logOnly",
+            get: function get() {
+                return this.config.logOnly;
+            }
+        },
+        {
+            key: "onModuleDestroy",
+            value: function onModuleDestroy() {
+                return _async_to_generator(function() {
+                    return _ts_generator(this, function(_state) {
+                        switch(_state.label){
+                            case 0:
+                                return [
+                                    4,
+                                    this.analytics.closeAndFlush()
+                                ];
+                            case 1:
+                                _state.sent();
+                                return [
+                                    2
+                                ];
+                        }
+                    });
+                }).call(this);
+            }
+        }
+    ]);
+    return SegmentApi;
+}();
+SegmentApi = __decorate([
+    Injectable(),
+    __param(0, Inject(SegmentServiceConfig))
+], SegmentApi);
+
+function _class_call_check$2(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _defineProperties$1(target, props) {
+    for(var i = 0; i < props.length; i++){
+        var descriptor = props[i];
+        descriptor.enumerable = descriptor.enumerable || false;
+        descriptor.configurable = true;
+        if ("value" in descriptor) descriptor.writable = true;
+        Object.defineProperty(target, descriptor.key, descriptor);
+    }
+}
+function _create_class$1(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties$1(Constructor.prototype, protoProps);
+    return Constructor;
+}
+function _define_property$1(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property$1(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+/**
+ * High-level Segment analytics service.
+ *
+ * Handles track and identify calls, merging application context and
+ * supporting log-only mode for development/testing.
+ */ var SegmentService = /*#__PURE__*/ function() {
+    function SegmentService(segmentApi, config) {
+        _class_call_check$2(this, SegmentService);
+        _define_property$1(this, "segmentApi", void 0);
+        _define_property$1(this, "config", void 0);
+        _define_property$1(this, "logger", new Logger('SegmentService'));
+        this.segmentApi = segmentApi;
+        this.config = config;
+    }
+    _create_class$1(SegmentService, [
+        {
+            /**
+     * Tracks an event for a user. Requires a userId.
+     *
+     * In log-only mode, events are logged to the console instead of being sent to Segment.
+     *
+     * @param userId - the user to associate with the event
+     * @param event - the track event containing event name, properties, and optional context
+     *
+     * @throws {Error} When userId is falsy.
+     *
+     * @example
+     * ```ts
+     * segmentService.track('uid_123', {
+     *   event: 'Item Purchased',
+     *   properties: { itemId: 'sku_abc', price: 29.99 }
+     * });
+     * ```
+     */ key: "track",
+            value: function track(userId, event) {
+                if (!userId) {
+                    throw new Error('No userId was provided to track().');
+                }
+                if (!this.config.logOnly) {
+                    this.segmentApi.analytics.track({
+                        userId: userId,
+                        event: event.event,
+                        properties: event.properties,
+                        timestamp: event.timestamp,
+                        context: _object_spread({}, event.context, this._appContext())
+                    });
+                } else {
+                    this.logger.debug("Segment (Log Only) - Track: ".concat(userId, " ").concat(event.event));
+                }
+            }
+        },
+        {
+            /**
+     * Tracks an event only if userId is provided. No-op if userId is nullish.
+     *
+     * Convenience wrapper around {@link track} for cases where the user may not be authenticated.
+     *
+     * @param userId - the user to associate with the event, or nullish to skip
+     * @param event - the track event containing event name, properties, and optional context
+     */ key: "tryTrack",
+            value: function tryTrack(userId, event) {
+                if (userId) {
+                    this.track(userId, event);
+                }
+            }
+        },
+        {
+            /**
+     * Identifies a user with optional traits, syncing user properties to Segment.
+     *
+     * In log-only mode, the identify call is logged to the console instead of being sent.
+     *
+     * @param params - the identify parameters including userId and optional traits
+     *
+     * @example
+     * ```ts
+     * segmentService.identify({
+     *   userId: 'uid_123',
+     *   traits: { plan: 'premium', role: 'admin' }
+     * });
+     * ```
+     */ key: "identify",
+            value: function identify(params) {
+                if (!this.config.logOnly) {
+                    this.segmentApi.analytics.identify(_object_spread_props(_object_spread({}, params), {
+                        context: _object_spread({}, params.context, this._appContext())
+                    }));
+                } else {
+                    this.logger.debug("Segment (Log Only) - Identify: ".concat(params.userId));
+                }
+            }
+        },
+        {
+            key: "_appContext",
+            value: function _appContext() {
+                var appContext = this.config.appContext;
+                var result;
+                if (appContext) {
+                    result = {
+                        app: appContext
+                    };
+                }
+                return result;
+            }
+        }
+    ]);
+    return SegmentService;
+}();
+SegmentService = __decorate([
+    Injectable(),
+    __param(0, Inject(SegmentApi)),
+    __param(1, Inject(SegmentServiceConfig))
+], SegmentService);
+
+function _class_call_check$1(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+/**
+ * Factory that creates a SegmentServiceConfig from environment variables.
+ *
+ * When a {@link ServerEnvironmentService} is provided and the current environment is a
+ * testing environment, `logOnly` is forced to true regardless of the env variable.
+ *
+ * @param configService - NestJS ConfigService for reading environment variables.
+ * @param serverEnvironmentService - Service that identifies the current server environment.
+ * @returns A validated {@link SegmentServiceConfig} instance.
+ *
+ * @example
+ * ```ts
+ * const config = segmentServiceConfigFactory(configService, serverEnvironmentService);
+ * ```
+ */ function segmentServiceConfigFactory(configService, serverEnvironmentService) {
+    var isTestingEnv = serverEnvironmentService.isTestingEnv;
+    var logOnly = isTestingEnv || configService.get('SEGMENT_LOG_ONLY', 'false') === 'true';
+    var config = {
+        writeKey: configService.get('SEGMENT_WRITE_KEY', ''),
+        logOnly: logOnly
+    };
+    SegmentServiceConfig.assertValidConfig(config);
+    return config;
+}
+/**
+ * NestJS module that provides the {@link SegmentService} and its dependencies.
+ *
+ * Reads `SEGMENT_WRITE_KEY` and `SEGMENT_LOG_ONLY` from environment variables via {@link ConfigModule}.
+ * When a {@link ServerEnvironmentService} is available and the environment is a testing environment,
+ * `logOnly` is forced to `true`.
+ */ var SegmentServiceModule = function SegmentServiceModule() {
+    _class_call_check$1(this, SegmentServiceModule);
+};
+SegmentServiceModule = __decorate([
+    Module({
+        imports: [
+            ConfigModule
+        ],
+        providers: [
+            {
+                provide: SegmentServiceConfig,
+                inject: [
+                    ConfigService,
+                    ServerEnvironmentService
+                ],
+                useFactory: segmentServiceConfigFactory
+            },
+            SegmentApi,
+            SegmentService
+        ],
+        exports: [
+            SegmentService
+        ]
+    })
+], SegmentServiceModule);
+
+function _class_call_check(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _defineProperties(target, props) {
+    for(var i = 0; i < props.length; i++){
+        var descriptor = props[i];
+        descriptor.enumerable = descriptor.enumerable || false;
+        descriptor.configurable = true;
+        if ("value" in descriptor) descriptor.writable = true;
+        Object.defineProperty(target, descriptor.key, descriptor);
+    }
+}
+function _create_class(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties(Constructor.prototype, protoProps);
+    return Constructor;
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+var ANALYTICS_INTERCEPTOR_METADATA_KEY = 'analyticsevent';
+/**
+ * Decorator that marks a controller method for analytics event emission.
+ *
+ * Used in conjunction with {@link AnalyticsEventInterceptor} to emit events
+ * to NestJS EventEmitter2 after the handler completes.
+ *
+ * @param config - The analytics event configuration specifying the event name and optional data extractor.
+ * @returns A method decorator that attaches analytics metadata.
+ *
+ * @example
+ * ```ts
+ * @EmitAnalyticsEvent({ name: 'User Registered', fn: (result) => ({ userId: result.id }) })
+ * @Post('register')
+ * async register(@Body() body: RegisterDto) {
+ *   return this.authService.register(body);
+ * }
+ * ```
+ */ var EmitAnalyticsEvent = function EmitAnalyticsEvent(config) {
+    if (!config.name) {
+        throw new Error('Analytics event name was not set properly.');
+    }
+    return SetMetadata(ANALYTICS_INTERCEPTOR_METADATA_KEY, config);
+};
+/**
+ * NestJS interceptor that emits analytics events via EventEmitter2
+ * for controller methods decorated with {@link EmitAnalyticsEvent}.
+ */ var AnalyticsEventInterceptor = /*#__PURE__*/ function() {
+    function AnalyticsEventInterceptor(reflector, eventEmitter) {
+        _class_call_check(this, AnalyticsEventInterceptor);
+        _define_property(this, "reflector", void 0);
+        _define_property(this, "eventEmitter", void 0);
+        this.reflector = reflector;
+        this.eventEmitter = eventEmitter;
+    }
+    _create_class(AnalyticsEventInterceptor, [
+        {
+            /**
+     * Intercepts the request pipeline, emitting an analytics event after the handler completes
+     * if the method is decorated with {@link EmitAnalyticsEvent}.
+     *
+     * @param context - The NestJS execution context.
+     * @param next - The next handler in the pipeline.
+     * @returns An observable that emits the handler result after triggering the analytics event.
+     */ key: "intercept",
+            value: function intercept(context, next) {
+                var _this = this;
+                var handler = context.getHandler();
+                var config = this.reflector.get(ANALYTICS_INTERCEPTOR_METADATA_KEY, handler);
+                return next.handle().pipe(tap(function(result) {
+                    var eventValues = config.fn ? config.fn(result, context) : undefined;
+                    if (eventValues != undefined) {
+                        _this.eventEmitter.emit(config.name, eventValues);
+                    }
+                }));
+            }
+        }
+    ]);
+    return AnalyticsEventInterceptor;
+}();
+AnalyticsEventInterceptor = __decorate([
+    Injectable()
+], AnalyticsEventInterceptor);
+
+export { ANALYTICS_INTERCEPTOR_METADATA_KEY, AnalyticsEventInterceptor, EmitAnalyticsEvent, SegmentApi, SegmentService, SegmentServiceConfig, SegmentServiceModule, segmentServiceConfigFactory };

package/nestjs/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@dereekb/analytics/nestjs",
+  "version": "13.4.0",
+  "peerDependencies": {
+    "@dereekb/analytics": "13.4.0",
+    "@dereekb/nestjs": "13.4.0",
+    "@dereekb/util": "13.4.0",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/config": "^4.0.3",
+    "@nestjs/core": "^11.1.16",
+    "@nestjs/event-emitter": "^3.0.1",
+    "@segment/analytics-node": "^2.3.0",
+    "rxjs": "^7.8.0"
+  },
+  "devDependencies": {
+    "@nestjs/testing": "^11.1.14"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/nestjs/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/nestjs/src/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './segment';
+export * from './interceptor';