@umituz/web-traffic 1.0.6

package/src/domains/analytics/repositories/analytics.repository.interface.ts

@@ -0,0 +1,19 @@
+/**
+ * Analytics Repository Interface
+ * @description Repository interface for Analytics queries (Domain Layer)
+ */
+
+import type { AnalyticsData } from '../entities/analytics.entity';
+
+export interface AnalyticsQuery {
+  readonly startDate: Date;
+  readonly endDate: Date;
+  readonly path?: string;
+}
+
+export interface IAnalyticsRepository {
+  getAnalytics(query: AnalyticsQuery): Promise<AnalyticsData | null>;
+  getPageviews(query: AnalyticsQuery): Promise<number>;
+  getSessions(query: AnalyticsQuery): Promise<number>;
+  getVisitors(query: AnalyticsQuery): Promise<number>;
+}

package/src/domains/conversion/aggregates/order.aggregate.ts

@@ -0,0 +1,85 @@
+/**
+ * Order Aggregate Root
+ * @description Manages conversion order and its items
+ */
+
+import type { OrderItem } from '../entities/order-item.entity';
+import type { EventId } from '../../tracking/value-objects/event-id.vo';
+import { Money } from '../value-objects/money.vo';
+
+export interface OrderCreateInput {
+  sessionId: string;
+  orderId: string;
+  items: Array<{
+    id: string;
+    name: string;
+    price: number;
+    quantity: number;
+  }>;
+  currency?: string;
+}
+
+export class Order {
+  readonly id: EventId;
+  readonly sessionId: string;
+  readonly orderId: string;
+  private items: OrderItem[];
+  private total: Money;
+  readonly createdAt: number;
+
+  constructor(input: OrderCreateInput & { id: EventId }) {
+    this.id = input.id;
+    this.sessionId = input.sessionId;
+    this.orderId = input.orderId;
+    this.createdAt = Date.now();
+    this.items = [];
+
+    // Calculate total and create items
+    let totalAmount = 0;
+    for (const item of input.items) {
+      const orderItem: OrderItem = {
+        id: item.id,
+        name: item.name,
+        price: item.price,
+        quantity: item.quantity,
+      };
+      this.items.push(orderItem);
+      totalAmount += item.price * item.quantity;
+    }
+
+    this.total = new Money(totalAmount, input.currency);
+
+    Object.freeze(this.items);
+    Object.freeze(this.id);
+    Object.freeze(this.sessionId);
+    Object.freeze(this.orderId);
+    Object.freeze(this.createdAt);
+  }
+
+  getTotal(): Money {
+    return this.total;
+  }
+
+  getItems(): OrderItem[] {
+    return [...this.items];
+  }
+
+  getItemCount(): number {
+    return this.items.reduce((sum, item) => sum + item.quantity, 0);
+  }
+
+  isValid(): boolean {
+    return this.items.length > 0 && this.total.getAmount() > 0;
+  }
+
+  toJSON() {
+    return {
+      id: this.id.toString(),
+      sessionId: this.sessionId,
+      orderId: this.orderId,
+      items: this.getItems(),
+      total: this.total.toJSON(),
+      createdAt: this.createdAt,
+    };
+  }
+}

package/src/domains/conversion/entities/order-item.entity.ts

@@ -0,0 +1,27 @@
+/**
+ * OrderItem Entity
+ * @description Represents an item in a conversion order
+ */
+
+export interface OrderItem {
+  readonly id: string;
+  readonly name: string;
+  readonly price: number;
+  readonly quantity: number;
+}
+
+export interface OrderItemCreateInput {
+  id: string;
+  name: string;
+  price: number;
+  quantity: number;
+}
+
+export function createOrderItem(input: OrderItemCreateInput): OrderItem {
+  return {
+    id: input.id,
+    name: input.name,
+    price: input.price,
+    quantity: input.quantity,
+  };
+}

package/src/domains/conversion/events/conversion-recorded.domain-event.ts

@@ -0,0 +1,30 @@
+/**
+ * Conversion Recorded Domain Event
+ * @description Published when a conversion is recorded
+ */
+
+import type { Money } from '../value-objects/money.vo';
+
+export class ConversionRecorded {
+  readonly eventType = 'ConversionRecorded';
+  readonly orderId: string;
+  readonly sessionId: string;
+  readonly revenue: Money;
+  readonly itemCount: number;
+  readonly occurredAt: number;
+
+  constructor(params: {
+    orderId: string;
+    sessionId: string;
+    revenue: Money;
+    itemCount: number;
+    occurredAt?: number;
+  }) {
+    this.orderId = params.orderId;
+    this.sessionId = params.sessionId;
+    this.revenue = params.revenue;
+    this.itemCount = params.itemCount;
+    this.occurredAt = params.occurredAt ?? Date.now();
+    Object.freeze(this);
+  }
+}

package/src/domains/conversion/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Conversion Domain Export
+ * Subpath: @umituz/web-traffic/conversion
+ */
+
+// Aggregates
+export { Order } from './aggregates/order.aggregate';
+export type { OrderCreateInput } from './aggregates/order.aggregate';
+
+// Entities
+export { createOrderItem } from './entities/order-item.entity';
+export type { OrderItem, OrderItemCreateInput } from './entities/order-item.entity';
+
+// Value Objects
+export { Money } from './value-objects/money.vo';
+
+// Repository Interfaces
+export type { IConversionRepository } from './repositories/conversion.repository.interface';
+
+// Domain Events
+export { ConversionRecorded } from './events/conversion-recorded.domain-event';

package/src/domains/conversion/repositories/conversion.repository.interface.ts

@@ -0,0 +1,13 @@
+/**
+ * Conversion Repository Interface
+ * @description Repository interface for Order persistence (Domain Layer)
+ */
+
+import type { Order } from '../aggregates/order.aggregate';
+
+export interface IConversionRepository {
+  save(order: Order): Promise<void>;
+  findById(orderId: string): Promise<Order | null>;
+  findBySessionId(sessionId: string): Promise<Order[]>;
+  delete(orderId: string): Promise<void>;
+}

package/src/domains/conversion/value-objects/money.vo.ts

@@ -0,0 +1,55 @@
+/**
+ * Money Value Object
+ * @description Immutable value object for monetary values
+ */
+
+export class Money {
+  private readonly amount: number;
+  private readonly currency: string;
+
+  constructor(amount: number, currency: string = 'USD') {
+    if (amount < 0) {
+      throw new Error('Amount cannot be negative');
+    }
+    if (!currency || currency.length !== 3) {
+      throw new Error('Currency must be a valid ISO 4217 code');
+    }
+    this.amount = Math.round(amount * 100) / 100; // Round to 2 decimal places
+    this.currency = currency.toUpperCase();
+    Object.freeze(this);
+  }
+
+  getAmount(): number {
+    return this.amount;
+  }
+
+  getCurrency(): string {
+    return this.currency;
+  }
+
+  add(other: Money): Money {
+    if (this.currency !== other.currency) {
+      throw new Error('Cannot add money with different currencies');
+    }
+    return new Money(this.amount + other.amount, this.currency);
+  }
+
+  multiply(factor: number): Money {
+    return new Money(this.amount * factor, this.currency);
+  }
+
+  equals(other: Money): boolean {
+    return this.amount === other.amount && this.currency === other.currency;
+  }
+
+  toJSON() {
+    return {
+      amount: this.amount,
+      currency: this.currency,
+    };
+  }
+
+  static zero(currency: string = 'USD'): Money {
+    return new Money(0, currency);
+  }
+}

package/src/domains/tracking/aggregates/session.aggregate.ts

@@ -0,0 +1,154 @@
+/**
+ * Session Aggregate Root
+ * @description Manages user session and its events within consistency boundary
+ */
+
+import type { Pageview } from '../entities/pageview.entity';
+import type { Event } from '../entities/event.entity';
+import { SessionId } from '../value-objects/session-id.vo';
+import type { SiteId } from '../../affiliate/value-objects/site-id.vo';
+import type { DeviceInfo } from '../value-objects/device-info.vo';
+
+export interface SessionCreateInput {
+  deviceId: string;
+  siteId: SiteId;
+  deviceInfo: DeviceInfo;
+  startTime?: number;
+}
+
+export class Session {
+  readonly id: SessionId;
+  readonly deviceId: string;
+  readonly siteId: SiteId;
+  readonly deviceInfo: DeviceInfo;
+  readonly startTime: number;
+  private endTime: number | null;
+  private events: Event[];
+  private pageviews: Pageview[];
+  private eventCount: number;
+  private pageviewCount: number;
+  private entryPage: string | null;
+  private exitPage: string | null;
+
+  constructor(input: SessionCreateInput & { id: SessionId }) {
+    this.id = input.id;
+    this.deviceId = input.deviceId;
+    this.siteId = input.siteId;
+    this.deviceInfo = input.deviceInfo;
+    this.startTime = input.startTime ?? Date.now();
+    this.endTime = null;
+    this.events = [];
+    this.pageviews = [];
+    this.eventCount = 0;
+    this.pageviewCount = 0;
+    this.entryPage = null;
+    this.exitPage = null;
+    Object.freeze(this.id);
+    Object.freeze(this.deviceId);
+    Object.freeze(this.siteId);
+    Object.freeze(this.deviceInfo);
+    Object.freeze(this.startTime);
+  }
+
+  // Aggregate root methods - maintain consistency
+  addEvent(event: Event): void {
+    if (this.isExpired()) {
+      throw new Error('Cannot add event to expired session');
+    }
+    this.events.push(event);
+    this.eventCount++;
+    this.updateLastActivity();
+  }
+
+  addPageview(pageview: Pageview): void {
+    if (this.isExpired()) {
+      throw new Error('Cannot add pageview to expired session');
+    }
+    this.pageviews.push(pageview);
+    this.pageviewCount++;
+    this.exitPage = pageview.path;
+    if (!this.entryPage) {
+      this.entryPage = pageview.path;
+    }
+    this.updateLastActivity();
+  }
+
+  getEntryPage(): string | null {
+    return this.entryPage;
+  }
+
+  getExitPage(): string | null {
+    return this.exitPage;
+  }
+
+  getSiteId(): SiteId {
+    return this.siteId;
+  }
+
+  getVisitorId(): string {
+    return this.deviceId;
+  }
+
+  getDeviceInfo(): DeviceInfo {
+    return this.deviceInfo;
+  }
+
+  close(): void {
+    if (this.endTime) {
+      throw new Error('Session already closed');
+    }
+    this.endTime = Date.now();
+  }
+
+  isExpired(timeoutMs: number = 30 * 60 * 1000): boolean {
+    if (this.endTime) {
+      return true;
+    }
+    return Date.now() - this.startTime > timeoutMs;
+  }
+
+  isActive(timeoutMs: number = 30 * 60 * 1000): boolean {
+    return !this.isExpired(timeoutMs);
+  }
+
+  getDuration(): number {
+    const end = this.endTime ?? Date.now();
+    return end - this.startTime;
+  }
+
+  getEventCount(): number {
+    return this.eventCount;
+  }
+
+  getPageviewCount(): number {
+    return this.pageviewCount;
+  }
+
+  getEvents(): Event[] {
+    return [...this.events];
+  }
+
+  getPageviews(): Pageview[] {
+    return [...this.pageviews];
+  }
+
+  private updateLastActivity(): void {
+    // Could emit domain event here
+  }
+
+  toJSON() {
+    return {
+      id: this.id.toString(),
+      deviceId: this.deviceId,
+      siteId: this.siteId.toString(),
+      deviceInfo: this.deviceInfo.toJSON(),
+      startTime: this.startTime,
+      endTime: this.endTime,
+      eventCount: this.eventCount,
+      pageviewCount: this.pageviewCount,
+      entryPage: this.entryPage,
+      exitPage: this.exitPage,
+      duration: this.getDuration(),
+    };
+  }
+}

package/src/domains/tracking/application/tracking-command.service.ts

@@ -0,0 +1,109 @@
+/**
+ * Tracking Command Service
+ * @description Application service for tracking commands (use-cases)
+ */
+
+import { EventId } from '../../tracking/value-objects/event-id.vo';
+import { SessionId } from '../../tracking/value-objects/session-id.vo';
+import { UTMParameters } from '../../tracking/value-objects/utm-parameters.vo';
+import { Session } from '../../tracking/aggregates/session.aggregate';
+import { Event } from '../../tracking/entities/event.entity';
+import { Pageview } from '../../tracking/entities/pageview.entity';
+import type { ISessionRepository, IEventRepository, IPageviewRepository } from '../../tracking/repositories/event.repository.interface';
+import type { EventTracked } from '../events/event-tracked.domain-event';
+import type { PageviewTracked } from '../events/pageview-tracked.domain-event';
+
+export interface TrackingCommandResult {
+  success: boolean;
+  eventId?: string;
+  error?: string;
+}
+
+export class TrackingCommandService {
+  constructor(
+    private readonly sessionRepo: ISessionRepository,
+    private readonly eventRepo: IEventRepository,
+    private readonly pageviewRepo: IPageviewRepository
+  ) {}
+
+  async trackEvent(
+    sessionId: string,
+    eventName: string,
+    properties: Record<string, unknown> = {}
+  ): Promise<TrackingCommandResult> {
+    try {
+      const sessionIdVo = new SessionId(sessionId);
+      const eventId = EventId.generate();
+
+      const event = new Event({
+        id: eventId,
+        sessionId: sessionIdVo,
+        name: eventName,
+        properties,
+      });
+
+      // Get or create session
+      let session = await this.sessionRepo.findById(sessionIdVo);
+      if (!session) {
+        throw new Error('Session not found');
+      }
+
+      session.addEvent(event);
+      await this.eventRepo.save(event);
+      await this.sessionRepo.save(session);
+
+      return {
+        success: true,
+        eventId: eventId.toString(),
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  async trackPageview(
+    sessionId: string,
+    path: string,
+    referrer: string | null = null,
+    utmParams?: { source?: string; medium?: string; campaign?: string; term?: string; content?: string }
+  ): Promise<TrackingCommandResult> {
+    try {
+      const sessionIdVo = new SessionId(sessionId);
+      const pageviewId = EventId.generate();
+
+      const utmParameters = utmParams ? new UTMParameters(utmParams) : null;
+
+      const pageview = new Pageview({
+        id: pageviewId,
+        sessionId: sessionIdVo,
+        siteId: new SessionId(data.sessionId).getSiteId(),
+        path,
+        referrer,
+        utmParameters,
+      });
+
+      // Get or create session
+      let session = await this.sessionRepo.findById(sessionIdVo);
+      if (!session) {
+        throw new Error('Session not found');
+      }
+
+      session.addPageview(pageview);
+      await this.pageviewRepo.save(pageview);
+      await this.sessionRepo.save(session);
+
+      return {
+        success: true,
+        eventId: pageviewId.toString(),
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+}

package/src/domains/tracking/entities/event.entity.ts

@@ -0,0 +1,48 @@
+/**
+ * Event Entity
+ * @description Represents a tracked analytics event using value objects
+ */
+
+import { EventId } from '../value-objects/event-id.vo';
+import type { SessionId } from '../value-objects/session-id.vo';
+
+export interface EventCreateInput {
+  sessionId: SessionId;
+  name: string;
+  properties: Record<string, unknown>;
+}
+
+export class Event {
+  readonly id: EventId;
+  readonly sessionId: SessionId;
+  readonly name: string;
+  readonly properties: Record<string, unknown>;
+  readonly timestamp: number;
+
+  constructor(input: EventCreateInput & { id: EventId; timestamp?: number }) {
+    this.id = input.id;
+    this.sessionId = input.sessionId;
+    this.name = input.name;
+    this.properties = { ...input.properties };
+    this.timestamp = input.timestamp ?? Date.now();
+    Object.freeze(this.properties);
+  }
+
+  hasProperty(key: string): boolean {
+    return key in this.properties;
+  }
+
+  getProperty<T = unknown>(key: string): T | undefined {
+    return this.properties[key] as T;
+  }
+
+  toJSON() {
+    return {
+      id: this.id.toString(),
+      sessionId: this.sessionId.toString(),
+      name: this.name,
+      properties: this.properties,
+      timestamp: this.timestamp,
+    };
+  }
+}

package/src/domains/tracking/entities/pageview.entity.ts

@@ -0,0 +1,52 @@
+/**
+ * Pageview Entity
+ * @description Represents a page view using value objects
+ */
+
+import { EventId } from '../value-objects/event-id.vo';
+import type { SessionId } from '../value-objects/session-id.vo';
+import type { SiteId } from '../../affiliate/value-objects/site-id.vo';
+import { UTMParameters } from '../value-objects/utm-parameters.vo';
+
+export interface PageviewCreateInput {
+  sessionId: SessionId;
+  siteId: SiteId;
+  path: string;
+  referrer: string | null;
+  utmParameters: UTMParameters | null;
+}
+
+export class Pageview {
+  readonly id: EventId;
+  readonly sessionId: SessionId;
+  readonly siteId: SiteId;
+  readonly path: string;
+  readonly referrer: string | null;
+  readonly utmParameters: UTMParameters | null;
+  readonly timestamp: number;
+
+  constructor(input: PageviewCreateInput & { id: EventId; timestamp?: number }) {
+    this.id = input.id;
+    this.sessionId = input.sessionId;
+    this.siteId = input.siteId;
+    this.path = input.path;
+    this.referrer = input.referrer;
+    this.utmParameters = input.utmParameters;
+    this.timestamp = input.timestamp ?? Date.now();
+  }
+
+  hasUTMParameters(): boolean {
+    return this.utmParameters?.hasAnyUTM() ?? false;
+  }
+
+  toJSON() {
+    return {
+      id: this.id.toString(),
+      sessionId: this.sessionId.toString(),
+      path: this.path,
+      referrer: this.referrer,
+      utmParameters: this.utmParameters?.toJSON() ?? null,
+      timestamp: this.timestamp,
+    };
+  }
+}

package/src/domains/tracking/events/event-tracked.domain-event.ts

@@ -0,0 +1,28 @@
+/**
+ * Event Tracked Domain Event
+ * @description Published when an analytics event is tracked
+ */
+
+import type { EventId } from '../../tracking/value-objects/event-id.vo';
+import type { SessionId } from '../../tracking/value-objects/session-id.vo';
+
+export class EventTracked {
+  readonly eventType = 'EventTracked';
+  readonly eventId: EventId;
+  readonly sessionId: SessionId;
+  readonly eventName: string;
+  readonly occurredAt: number;
+
+  constructor(params: {
+    eventId: EventId;
+    sessionId: SessionId;
+    eventName: string;
+    occurredAt?: number;
+  }) {
+    this.eventId = params.eventId;
+    this.sessionId = params.sessionId;
+    this.eventName = params.eventName;
+    this.occurredAt = params.occurredAt ?? Date.now();
+    Object.freeze(this);
+  }
+}

package/src/domains/tracking/events/pageview-tracked.domain-event.ts

@@ -0,0 +1,31 @@
+/**
+ * Pageview Tracked Domain Event
+ * @description Published when a pageview is tracked
+ */
+
+import type { EventId } from '../../tracking/value-objects/event-id.vo';
+import type { SessionId } from '../../tracking/value-objects/session-id.vo';
+
+export class PageviewTracked {
+  readonly eventType = 'PageviewTracked';
+  readonly pageviewId: EventId;
+  readonly sessionId: SessionId;
+  readonly path: string;
+  readonly hasUTM: boolean;
+  readonly occurredAt: number;
+
+  constructor(params: {
+    pageviewId: EventId;
+    sessionId: SessionId;
+    path: string;
+    hasUTM: boolean;
+    occurredAt?: number;
+  }) {
+    this.pageviewId = params.pageviewId;
+    this.sessionId = params.sessionId;
+    this.path = params.path;
+    this.hasUTM = params.hasUTM;
+    this.occurredAt = params.occurredAt ?? Date.now();
+    Object.freeze(this);
+  }
+}