@umituz/web-traffic 1.0.6

package/src/domains/tracking/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Tracking Domain Export
+ * Subpath: @umituz/web-traffic/tracking
+ */
+
+// Aggregates
+export { Session } from './aggregates/session.aggregate';
+export type { SessionCreateInput } from './aggregates/session.aggregate';
+
+// Entities
+export { Event } from './entities/event.entity';
+export type { EventCreateInput } from './entities/event.entity';
+
+export { Pageview } from './entities/pageview.entity';
+export type { PageviewCreateInput } from './entities/pageview.entity';
+
+// Value Objects
+export { SessionId } from './value-objects/session-id.vo';
+export { EventId } from './value-objects/event-id.vo';
+export { UTMParameters } from './value-objects/utm-parameters.vo';
+export { DeviceInfo } from './value-objects/device-info.vo';
+export type { DeviceType, BrowserInfo, OSInfo } from './value-objects/device-info.vo';
+
+// Repository Interfaces
+export type {
+  IEventRepository,
+  IPageviewRepository,
+  ISessionRepository,
+} from './repositories/event.repository.interface';
+
+// Domain Events
+export { EventTracked } from './events/event-tracked.domain-event';
+export { PageviewTracked } from './events/pageview-tracked.domain-event';
+
+// Application Services
+export { TrackingCommandService } from './application/tracking-command.service';
+export type { TrackingCommandResult } from './application/tracking-command.service';

package/src/domains/tracking/repositories/event.repository.interface.ts

@@ -0,0 +1,29 @@
+/**
+ * Event Repository Interface
+ * @description Repository interface for Event persistence (Domain Layer)
+ */
+
+import type { Event } from '../entities/event.entity';
+import type { EventId } from '../value-objects/event-id.vo';
+import type { SessionId } from '../value-objects/session-id.vo';
+
+export interface IEventRepository {
+  save(event: Event): Promise<void>;
+  findById(id: EventId): Promise<Event | null>;
+  findBySessionId(sessionId: SessionId): Promise<Event[]>;
+  delete(id: EventId): Promise<void>;
+}
+
+export interface IPageviewRepository {
+  save(pageview: import('../entities/pageview.entity').Pageview): Promise<void>;
+  findById(id: EventId): Promise<import('../entities/pageview.entity').Pageview | null>;
+  findBySessionId(sessionId: SessionId): Promise<import('../entities/pageview.entity').Pageview[]>;
+  delete(id: EventId): Promise<void>;
+}
+
+export interface ISessionRepository {
+  save(session: import('../aggregates/session.aggregate').Session): Promise<void>;
+  findById(id: SessionId): Promise<import('../aggregates/session.aggregate').Session | null>;
+  findActive(deviceId: string, timeoutMs: number): Promise<import('../aggregates/session.aggregate').Session | null>;
+  delete(id: SessionId): Promise<void>;
+}

package/src/domains/tracking/value-objects/device-info.vo.ts

@@ -0,0 +1,163 @@
+/**
+ * DeviceInfo Value Object
+ * @description Immutable value object for device/browser information
+ */
+
+export type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
+
+export interface BrowserInfo {
+  readonly name: string | null;
+  readonly version: string | null;
+}
+
+export interface OSInfo {
+  readonly name: string | null;
+  readonly version: string | null;
+}
+
+export class DeviceInfo {
+  private readonly browser: BrowserInfo;
+  private readonly os: OSInfo;
+  private readonly deviceType: DeviceType;
+  private readonly screenWidth: number | null;
+  private readonly screenHeight: number | null;
+
+  constructor(params: {
+    browser: BrowserInfo;
+    os: OSInfo;
+    deviceType: DeviceType;
+    screenWidth: number | null;
+    screenHeight: number | null;
+  }) {
+    this.browser = { ...params.browser };
+    this.os = { ...params.os };
+    this.deviceType = params.deviceType;
+    this.screenWidth = params.screenWidth;
+    this.screenHeight = params.screenHeight;
+    Object.freeze(this);
+  }
+
+  getBrowser(): BrowserInfo {
+    return { ...this.browser };
+  }
+
+  getOS(): OSInfo {
+    return { ...this.os };
+  }
+
+  getDeviceType(): DeviceType {
+    return this.deviceType;
+  }
+
+  getScreenSize(): { width: number | null; height: number | null } {
+    return {
+      width: this.screenWidth,
+      height: this.screenHeight,
+    };
+  }
+
+  isMobile(): boolean {
+    return this.deviceType === 'mobile';
+  }
+
+  isTablet(): boolean {
+    return this.deviceType === 'tablet';
+  }
+
+  isDesktop(): boolean {
+    return this.deviceType === 'desktop';
+  }
+
+  toJSON() {
+    return {
+      browser: this.browser,
+      os: this.os,
+      deviceType: this.deviceType,
+      screenWidth: this.screenWidth,
+      screenHeight: this.screenHeight,
+    };
+  }
+
+  static fromUserAgent(userAgent: string, screenWidth?: number): DeviceInfo {
+    // Simple UA parsing (production would use ua-parser-js)
+    const browser = parseBrowser(userAgent);
+    const os = parseOS(userAgent);
+    const deviceType = detectDeviceType(userAgent, screenWidth);
+
+    return new DeviceInfo({
+      browser,
+      os,
+      deviceType,
+      screenWidth: screenWidth ?? null,
+      screenHeight: null,
+    });
+  }
+}
+
+function parseBrowser(userAgent: string): BrowserInfo {
+  const chromeMatch = userAgent.match(/Chrome\/(\d+\.\d+\.\d+\.\d+)/);
+  if (chromeMatch) {
+    return { name: 'Chrome', version: chromeMatch[1] };
+  }
+
+  const firefoxMatch = userAgent.match(/Firefox\/(\d+\.\d+)/);
+  if (firefoxMatch) {
+    return { name: 'Firefox', version: firefoxMatch[1] };
+  }
+
+  const safariMatch = userAgent.match(/Safari\/(\d+\.\d+)/);
+  if (safariMatch && !userAgent.includes('Chrome')) {
+    return { name: 'Safari', version: safariMatch[1] };
+  }
+
+  const edgeMatch = userAgent.match(/Edg\/(\d+\.\d+\.\d+\.\d+)/);
+  if (edgeMatch) {
+    return { name: 'Edge', version: edgeMatch[1] };
+  }
+
+  return { name: null, version: null };
+}
+
+function parseOS(userAgent: string): OSInfo {
+  const windowsMatch = userAgent.match(/Windows NT (\d+\.\d+)/);
+  if (windowsMatch) {
+    return { name: 'Windows', version: windowsMatch[1] };
+  }
+
+  const macMatch = userAgent.match(/Mac OS X (\d+[._]\d+)/);
+  if (macMatch) {
+    return { name: 'macOS', version: macMatch[1].replace('_', '.') };
+  }
+
+  const iosMatch = userAgent.match(/iOS (\d+[._]\d+)/);
+  if (iosMatch) {
+    return { name: 'iOS', version: iosMatch[1].replace('_', '.') };
+  }
+
+  const androidMatch = userAgent.match(/Android (\d+\.\d+)/);
+  if (androidMatch) {
+    return { name: 'Android', version: androidMatch[1] };
+  }
+
+  const linuxMatch = userAgent.includes('Linux');
+  if (linuxMatch) {
+    return { name: 'Linux', version: null };
+  }
+
+  return { name: null, version: null };
+}
+
+function detectDeviceType(userAgent: string, screenWidth?: number): DeviceType {
+  if (screenWidth) {
+    if (screenWidth < 768) return 'mobile';
+    if (screenWidth < 1024) return 'tablet';
+    return 'desktop';
+  }
+
+  const mobile = /Mobile|Android|iPhone|iPad|iPod/i.test(userAgent);
+  if (mobile) {
+    return /iPad/i.test(userAgent) ? 'tablet' : 'mobile';
+  }
+
+  return 'desktop';
+}

package/src/domains/tracking/value-objects/event-id.vo.ts

@@ -0,0 +1,36 @@
+/**
+ * EventId Value Object
+ * @description Immutable value object for event identification
+ */
+
+export class EventId {
+  private readonly value: string;
+
+  constructor(value: string) {
+    if (!value || value.trim().length === 0) {
+      throw new Error('EventId cannot be empty');
+    }
+    if (!value.startsWith('event-')) {
+      throw new Error('EventId must start with "event-"');
+    }
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  equals(other: EventId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  static generate(): EventId {
+    const id = `event-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    return new EventId(id);
+  }
+}

package/src/domains/tracking/value-objects/session-id.vo.ts

@@ -0,0 +1,36 @@
+/**
+ * SessionId Value Object
+ * @description Immutable value object for session identification
+ */
+
+export class SessionId {
+  private readonly value: string;
+
+  constructor(value: string) {
+    if (!value || value.trim().length === 0) {
+      throw new Error('SessionId cannot be empty');
+    }
+    if (!value.startsWith('session-')) {
+      throw new Error('SessionId must start with "session-"');
+    }
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  equals(other: SessionId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  static generate(): SessionId {
+    const id = `session-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    return new SessionId(id);
+  }
+}

package/src/domains/tracking/value-objects/utm-parameters.vo.ts

@@ -0,0 +1,75 @@
+/**
+ * UTMParameters Value Object
+ * @description Immutable value object for UTM campaign parameters
+ */
+
+export class UTMParameters {
+  private readonly source?: string;
+  private readonly medium?: string;
+  private readonly campaign?: string;
+  private readonly term?: string;
+  private readonly content?: string;
+
+  constructor(params: {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+  }) {
+    this.source = params.source;
+    this.medium = params.medium;
+    this.campaign = params.campaign;
+    this.term = params.term;
+    this.content = params.content;
+    Object.freeze(this);
+  }
+
+  getSource(): string | undefined {
+    return this.source;
+  }
+
+  getMedium(): string | undefined {
+    return this.medium;
+  }
+
+  getCampaign(): string | undefined {
+    return this.campaign;
+  }
+
+  getTerm(): string | undefined {
+    return this.term;
+  }
+
+  getContent(): string | undefined {
+    return this.content;
+  }
+
+  hasAnyUTM(): boolean {
+    return !!(this.source || this.medium || this.campaign || this.term || this.content);
+  }
+
+  toJSON() {
+    return {
+      source: this.source,
+      medium: this.medium,
+      campaign: this.campaign,
+      term: this.term,
+      content: this.content,
+    };
+  }
+
+  static fromURLSearchParams(searchParams: URLSearchParams): UTMParameters | null {
+    const source = searchParams.get('utm_source') || undefined;
+    const medium = searchParams.get('utm_medium') || undefined;
+    const campaign = searchParams.get('utm_campaign') || undefined;
+    const term = searchParams.get('utm_term') || undefined;
+    const content = searchParams.get('utm_content') || undefined;
+
+    if (!source && !medium && !campaign && !term && !content) {
+      return null;
+    }
+
+    return new UTMParameters({ source, medium, campaign, term, content });
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @umituz/web-traffic
+ * Web analytics tracking library with DDD architecture
+ *
+ * IMPORTANT: Apps should use subpath imports, NOT this root barrel.
+ *
+ * RECOMMENDED IMPORTS:
+ * - @umituz/web-traffic/presentation (React hooks & Provider)
+ * - @umituz/web-traffic/tracking (Tracking domain)
+ * - @umituz/web-traffic/conversion (Conversion domain)
+ * - @umituz/web-traffic/analytics (Analytics domain)
+ * - @umituz/web-traffic/infrastructure (Infrastructure services)
+ */
+
+// Presentation Layer
+export * from './presentation';

package/src/infrastructure/analytics/http-analytics.repository.impl.ts

@@ -0,0 +1,60 @@
+/**
+ * HTTP Analytics Repository Implementation
+ * @description HTTP-based implementation of IAnalyticsRepository
+ */
+
+import type {
+  IAnalyticsRepository,
+  AnalyticsQuery,
+} from '../../domains/analytics/repositories/analytics.repository.interface';
+import type { AnalyticsData } from '../../domains/analytics/entities/analytics.entity';
+
+export interface HTTPAnalyticsConfig {
+  readonly apiUrl: string;
+  readonly apiKey: string;
+}
+
+export class HTTPAnalyticsRepository implements IAnalyticsRepository {
+  constructor(private readonly config: HTTPAnalyticsConfig) {}
+
+  async getAnalytics(query: AnalyticsQuery): Promise<AnalyticsData | null> {
+    try {
+      const params = new URLSearchParams({
+        start_date: query.startDate.toISOString(),
+        end_date: query.endDate.toISOString(),
+        ...(query.path && { path: query.path }),
+      });
+
+      const response = await fetch(`${this.config.apiUrl}/analytics?${params}`, {
+        headers: {
+          'X-API-Key': this.config.apiKey,
+        },
+      });
+
+      if (!response.ok) {
+        console.error('Analytics fetch failed:', response.statusText);
+        return null;
+      }
+
+      return await response.json();
+    } catch (error) {
+      console.error('Analytics error:', error);
+      return null;
+    }
+  }
+
+  async getPageviews(query: AnalyticsQuery): Promise<number> {
+    const data = await this.getAnalytics(query);
+    return data?.pageviews ?? 0;
+  }
+
+  async getSessions(query: AnalyticsQuery): Promise<number> {
+    const data = await this.getAnalytics(query);
+    return data?.sessions ?? 0;
+  }
+
+  async getVisitors(query: AnalyticsQuery): Promise<number> {
+    const data = await this.getAnalytics(query);
+    return data?.visitors ?? 0;
+  }
+}

package/src/infrastructure/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Infrastructure Export
+ * Subpath: @umituz/web-traffic/infrastructure
+ */
+
+// Repositories
+export {
+  HTTPEventRepository,
+  HTTPPageviewRepository,
+  LocalSessionRepository,
+} from './repositories/http-event.repository.impl';
+export type { HTTPRepositoryConfig } from './repositories/http-event.repository.impl';
+
+export { HTTPAnalyticsRepository } from './analytics/http-analytics.repository.impl';
+export type { HTTPAnalyticsConfig } from './analytics/http-analytics.repository.impl';
+
+// Services
+export { webTrafficService } from './tracking/web-traffic.service';
+export type { WebTrafficConfig } from './tracking/web-traffic.service';

package/src/infrastructure/repositories/http-event.repository.impl.ts

@@ -0,0 +1,160 @@
+/**
+ * HTTP Event Repository Implementation
+ * @description HTTP-based implementation of IEventRepository
+ */
+
+import type {
+  IEventRepository,
+  IPageviewRepository,
+  ISessionRepository,
+} from '../../domains/tracking/repositories/event.repository.interface';
+import type { Event } from '../../domains/tracking/entities/event.entity';
+import type { Pageview } from '../../domains/tracking/entities/pageview.entity';
+import type { Session } from '../../domains/tracking/aggregates/session.aggregate';
+import { EventId } from '../../domains/tracking/value-objects/event-id.vo';
+import { SessionId } from '../../domains/tracking/value-objects/session-id.vo';
+
+export interface HTTPRepositoryConfig {
+  readonly apiUrl: string;
+  readonly apiKey: string;
+}
+
+export class HTTPEventRepository implements IEventRepository {
+  private queue: Array<{ event: Event | Pageview; timestamp: number }> = [];
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private readonly FLUSH_INTERVAL = 30000; // 30 seconds
+  private readonly MAX_QUEUE_SIZE = 100;
+
+  constructor(private readonly config: HTTPRepositoryConfig) {
+    this.startFlushTimer();
+    if (typeof window !== 'undefined') {
+      window.addEventListener('beforeunload', () => this.flush());
+    }
+  }
+
+  async save(event: Event): Promise<void> {
+    this.queue.push({ event, timestamp: Date.now() });
+    if (this.queue.length >= 10) {
+      await this.flush();
+    }
+  }
+
+  async findById(id: EventId): Promise<Event | null> {
+    // For HTTP repository, we don't fetch individual events
+    return null;
+  }
+
+  async findBySessionId(sessionId: SessionId): Promise<Event[]> {
+    // Would need an endpoint to fetch events by session
+    return [];
+  }
+
+  async delete(id: EventId): Promise<void> {
+    // Implement if needed
+  }
+
+  private startFlushTimer(): void {
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, this.FLUSH_INTERVAL);
+  }
+
+  private async flush(): Promise<void> {
+    if (this.queue.length === 0) return;
+
+    const items = [...this.queue];
+    this.queue = [];
+
+    try {
+      const response = await fetch(`${this.config.apiUrl}/track`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.config.apiKey,
+        },
+        body: JSON.stringify({
+          events: items.map((item) => item.event.toJSON()),
+        }),
+        keepalive: true,
+      });
+
+      if (!response.ok) {
+        console.error('Tracking failed:', response.statusText);
+        this.queue.unshift(...items);
+      }
+    } catch (error) {
+      console.error('Tracking error:', error);
+      this.queue.unshift(...items);
+    }
+  }
+
+  destroy(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+    this.flush();
+  }
+}
+
+export class HTTPPageviewRepository implements IPageviewRepository {
+  private eventRepo: IEventRepository;
+
+  constructor(config: HTTPRepositoryConfig) {
+    this.eventRepo = new HTTPEventRepository(config);
+  }
+
+  async save(pageview: Pageview): Promise<void> {
+    await this.eventRepo.save(pageview as any);
+  }
+
+  async findById(id: EventId): Promise<Pageview | null> {
+    return null;
+  }
+
+  async findBySessionId(sessionId: SessionId): Promise<Pageview[]> {
+    return [];
+  }
+
+  async delete(id: EventId): Promise<void> {
+    // Implement if needed
+  }
+}
+
+export class LocalSessionRepository implements ISessionRepository {
+  private sessions = new Map<string, Session>();
+
+  async save(session: Session): Promise<void> {
+    this.sessions.set(session.id.toString(), session);
+    if (typeof window !== 'undefined') {
+      localStorage.setItem('wt_session', JSON.stringify(session.toJSON()));
+    }
+  }
+
+  async findById(id: SessionId): Promise<Session | null> {
+    return this.sessions.get(id.toString()) || null;
+  }
+
+  async findActive(deviceId: string, timeoutMs: number): Promise<Session | null> {
+    if (typeof window === 'undefined') return null;
+
+    const stored = localStorage.getItem('wt_session');
+    if (!stored) return null;
+
+    const data = JSON.parse(stored);
+    const sessionId = new SessionId(data.id);
+
+    const session = this.sessions.get(sessionId.toString());
+    if (session && session.isActive(timeoutMs)) {
+      return session;
+    }
+
+    return null;
+  }
+
+  async delete(id: SessionId): Promise<void> {
+    this.sessions.delete(id.toString());
+    if (typeof window !== 'undefined') {
+      localStorage.removeItem('wt_session');
+    }
+  }
+}