@umituz/web-traffic 1.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 umituz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# @umituz/web-traffic
+
+Web analytics tracking library built with **Domain-Driven Design (DDD)** principles. Track pageviews, events, sessions, conversions, and affiliate referrals with clean architecture.
+
+## 🎯 Features
+
+- **✨ DDD Architecture** - Clean separation of domains, aggregates, and value objects
+- **🎯 Event & Pageview Tracking** - Track user interactions and page views
+- **📊 Session Management** - Automatic session creation with entry/exit page tracking
+- **🔍 UTM Parameters** - Value object-based campaign tracking
+- **💰 Conversion Tracking** - Order aggregate with Money value object
+- **🎯 Affiliate System** - Track referrals with commission calculation
+- **🌐 Multi-site Support** - Track multiple websites with SiteId
+- **📱 Enhanced Device Detection** - Browser, OS, and device type tracking
+- **🔒 Type Safety** - Full TypeScript support with immutable value objects
+- **🧩 Modular** - Subpath exports for tree-shaking
+
+## 📦 Installation
+
+```bash
+npm install @umituz/web-traffic
+```
+
+## 🏗️ Architecture
+
+### DDD Layer Structure
+
+```
+src/
+├── domains/                    # Domain Layer (Pure business logic)
+│   ├── tracking/              # Tracking Bounded Context
+│   │   ├── aggregates/        # Session (aggregate root)
+│   │   ├── entities/          # Event, Pageview
+│   │   ├── value-objects/     # SessionId, EventId, UTMParameters, DeviceInfo
+│   │   ├── repositories/      # Repository interfaces
+│   │   ├── events/            # Domain events
+│   │   └── application/       # Command services
+│   ├── conversion/            # Conversion Bounded Context
+│   │   ├── aggregates/        # Order
+│   │   ├── entities/          # OrderItem
+│   │   ├── value-objects/     # Money
+│   │   ├── repositories/      # Repository interfaces
+│   │   └── events/            # Domain events
+│   ├── affiliate/             # Affiliate Bounded Context
+│   │   ├── aggregates/        # Affiliate (commission tracking)
+│   │   ├── entities/          # AffiliateVisit
+│   │   ├── value-objects/     # AffiliateId, SiteId
+│   │   └── repositories/      # Repository interfaces
+│   └── analytics/             # Analytics Bounded Context
+│       ├── entities/          # AnalyticsData
+│       └── repositories/      # Repository interfaces
+│
+├── infrastructure/            # Infrastructure Layer (Implementation)
+│   ├── repositories/          # HTTP repository implementations
+│   ├── analytics/             # HTTP analytics client
+│   └── tracking/              # WebTrafficService (Facade)
+│
+└── presentation/              # Presentation Layer (React)
+    ├── hooks.ts               # useWebTraffic, useAnalytics
+    └── context.tsx            # WebTrafficProvider
+```
+
+### DDD Concepts
+
+**Value Objects** - Immutable, identity-less objects:
+```typescript
+import { SessionId, EventId, UTMParameters, Money } from '@umituz/web-traffic/tracking';
+
+const sessionId = SessionId.generate(); // Always valid, frozen
+const utm = new UTMParameters({ source: 'google', medium: 'cpc' });
+const money = new Money(99.99, 'USD');
+```
+
+**Aggregates** - Consistency boundaries:
+```typescript
+import { Session } from '@umituz/web-traffic/tracking';
+
+const session = new Session({ id: sessionId, deviceId: 'xxx' });
+session.addEvent(event);    // Maintains invariant
+session.addPageview(pageview);
+const duration = session.getDuration();
+```
+
+**Repositories** - Data access interfaces:
+```typescript
+// Domain layer defines interface
+interface IEventRepository {
+  save(event: Event): Promise<void>;
+  findById(id: EventId): Promise<Event | null>;
+}
+
+// Infrastructure layer implements
+class HTTPEventRepository implements IEventRepository { ... }
+```
+
+## 🚀 Usage
+
+### Basic Setup
+
+```typescript
+import { WebTrafficProvider } from '@umituz/web-traffic/presentation';
+
+function App() {
+  return (
+    <WebTrafficProvider
+      config={{
+        apiKey: 'your-api-key',
+        apiUrl: 'https://your-analytics-api.com',
+        autoTrack: true,
+      }}
+    >
+      <YourApp />
+    </WebTrafficProvider>
+  );
+}
+```
+
+### Track Events
+
+```typescript
+import { useWebTraffic } from '@umituz/web-traffic/presentation';
+
+function MyComponent() {
+  const { trackEvent, trackPageView } = useWebTraffic();
+
+  const handleClick = () => {
+    await trackEvent('button_click', {
+      button_id: 'submit',
+      page: '/home',
+    });
+  };
+
+  return <button onClick={handleClick}>Click Me</button>;
+}
+```
+
+### Work with Value Objects
+
+```typescript
+import {
+  SessionId,
+  EventId,
+  UTMParameters,
+  DeviceInfo
+} from '@umituz/web-traffic/tracking';
+import { Money } from '@umituz/web-traffic/conversion';
+import { SiteId } from '@umituz/web-traffic/affiliate';
+
+// Value objects ensure validity
+const sessionId = new SessionId('session-123'); // Validates format
+const utm = UTMParameters.fromURLSearchParams(searchParams);
+const deviceInfo = DeviceInfo.fromUserAgent(navigator.userAgent);
+
+// Money value object prevents invalid amounts
+const total = new Money(99.99, 'USD');
+const tax = total.multiply(0.1);
+const final = total.add(tax);
+
+// Multi-site support
+const siteId = new SiteId('site-myapp1');
+```
+
+### Work with Aggregates
+
+```typescript
+import { Session } from '@umituz/web-traffic/tracking';
+import { Order } from '@umituz/web-traffic/conversion';
+import { Affiliate } from '@umituz/web-traffic/affiliate';
+
+// Session aggregate maintains consistency
+const session = new Session({
+  id: SessionId.generate(),
+  deviceId: 'device-123',
+  siteId: new SiteId('site-abc'),
+  deviceInfo: DeviceInfo.fromUserAgent(navigator.userAgent)
+});
+
+session.addEvent(event);
+session.addPageview(pageview);
+
+// Session journey tracking
+session.getEntryPage(); // '/home'
+session.getExitPage();  // '/checkout'
+
+// Session enforces business rules
+if (session.isExpired()) {
+  throw new Error('Session expired');
+}
+
+session.close(); // Cannot add more events
+
+// Affiliate aggregate
+const affiliate = new Affiliate({
+  id: AffiliateId.fromSlug('partner123'),
+  siteId: new SiteId('site-abc'),
+  name: 'Partner ABC',
+  slug: 'partner123',
+  commissionRate: 10, // 10%
+});
+
+affiliate.addVisit(visit);
+affiliate.addConversion(revenue);
+const commission = affiliate.calculateCommission();
+```
+
+## 📦 Subpath Exports
+
+```typescript
+// Presentation (React hooks & Provider)
+import { WebTrafficProvider, useWebTraffic } from '@umituz/web-traffic/presentation';
+
+// Tracking Domain
+import {
+  Session,
+  SessionId,
+  EventId,
+  UTMParameters,
+  DeviceInfo
+} from '@umituz/web-traffic/tracking';
+
+// Conversion Domain
+import { Order, Money } from '@umituz/web-traffic/conversion';
+
+// Affiliate Domain
+import { Affiliate, AffiliateId, SiteId } from '@umituz/web-traffic/affiliate';
+
+// Analytics Domain
+import type { AnalyticsData, AnalyticsQuery } from '@umituz/web-traffic/analytics';
+
+// Infrastructure
+import { webTrafficService } from '@umituz/web-traffic/infrastructure';
+```
+
+## 🧪 Testing
+
+DDD architecture makes testing easy:
+
+```typescript
+// Test domain logic in isolation
+describe('Session Aggregate', () => {
+  it('should maintain event count', () => {
+    const session = new Session({ id, deviceId });
+    session.addEvent(event1);
+    session.addEvent(event2);
+    expect(session.getEventCount()).toBe(2);
+  });
+});
+
+// Mock repositories for testing
+class MockEventRepository implements IEventRepository {
+  savedEvents: Event[] = [];
+  async save(event: Event) {
+    this.savedEvents.push(event);
+  }
+}
+```
+
+## 📚 DDD Patterns Used
+
+- ✅ **Bounded Contexts** - Tracking, Conversion, Analytics, Affiliate domains
+- ✅ **Aggregates** - Session, Order, Affiliate (consistency boundaries)
+- ✅ **Value Objects** - SessionId, EventId, UTMParameters, DeviceInfo, Money, SiteId (immutable)
+- ✅ **Repositories** - Interface/implementation separation
+- ✅ **Domain Events** - EventTracked, PageviewTracked, ConversionRecorded
+- ✅ **Application Services** - TrackingCommandService (use-cases)
+- ✅ **Facade Pattern** - WebTrafficService
+
+## 🚀 Features from Traffic-Source Integration
+
+This package integrates best practices from [traffic-source](https://github.com/mddanishyusuf/traffic-source):
+
+- ✅ **Affiliate Tracking** - Track referrals with `?ref=` parameter
+- ✅ **Multi-site Support** - Manage multiple websites with SiteId
+- ✅ **Enhanced Device Detection** - Browser, OS, and device type detection
+- ✅ **Session Journey** - Track entry/exit pages
+- ✅ **Real-time Session Management** - Session aggregate with timeout handling
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@umituz/web-traffic",
+  "version": "1.0.6",
+  "description": "Web analytics tracking library. Event tracking, pageviews, sessions, device info, and UTM parameter support.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./tracking": "./src/domains/tracking/index.ts",
+    "./conversion": "./src/domains/conversion/index.ts",
+    "./analytics": "./src/domains/analytics/index.ts",
+    "./affiliate": "./src/domains/affiliate/index.ts",
+    "./infrastructure": "./src/infrastructure/index.ts",
+    "./presentation": "./src/presentation/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'Lint passed'",
+    "version:patch": "npm version patch -m 'chore: release v%s'",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "web",
+    "analytics",
+    "tracking",
+    "ddd",
+    "domain-driven-design",
+    "pageview",
+    "events",
+    "utm",
+    "session",
+    "conversion",
+    "aggregates",
+    "value-objects"
+  ],
+  "author": "umituz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umituz/web-traffic"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "~19.1.10",
+    "react": "19.1.0",
+    "typescript": "~5.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/domains/affiliate/aggregates/affiliate.aggregate.ts

@@ -0,0 +1,98 @@
+/**
+ * Affiliate Aggregate Root
+ * @description Manages affiliate and their visits within consistency boundary
+ */
+
+import type { AffiliateVisit } from '../entities/affiliate-visit.entity';
+import { AffiliateId } from '../value-objects/affiliate-id.vo';
+import { SiteId } from '../value-objects/site-id.vo';
+import { Money } from '../../conversion/value-objects/money.vo';
+
+export interface AffiliateCreateInput {
+  id: AffiliateId;
+  siteId: SiteId;
+  name: string;
+  slug: string;
+  commissionRate: number; // Percentage (e.g., 10 for 10%)
+  active?: boolean;
+}
+
+export class Affiliate {
+  readonly id: AffiliateId;
+  readonly siteId: SiteId;
+  readonly name: string;
+  readonly slug: string;
+  readonly commissionRate: number;
+  readonly active: boolean;
+  private totalVisits: number = 0;
+  private totalConversions: number = 0;
+  private totalRevenue: Money;
+  readonly createdAt: number;
+
+  constructor(input: AffiliateCreateInput) {
+    this.id = input.id;
+    this.siteId = input.siteId;
+    this.name = input.name;
+    this.slug = input.slug;
+    this.commissionRate = input.commissionRate;
+    this.active = input.active ?? true;
+    this.totalRevenue = Money.zero('USD');
+    this.createdAt = Date.now();
+    Object.freeze(this.id);
+    Object.freeze(this.siteId);
+    Object.freeze(this.name);
+    Object.freeze(this.slug);
+  }
+
+  // Aggregate root methods - maintain consistency
+  addVisit(visit: AffiliateVisit): void {
+    if (!this.active) {
+      throw new Error('Cannot add visit to inactive affiliate');
+    }
+    if (!visit.affiliateId.equals(this.id)) {
+      throw new Error('Visit does not belong to this affiliate');
+    }
+    this.totalVisits++;
+  }
+
+  addConversion(revenue: Money): void {
+    if (!this.active) {
+      throw new Error('Cannot add conversion to inactive affiliate');
+    }
+    this.totalConversions++;
+    this.totalRevenue = this.totalRevenue.add(revenue);
+  }
+
+  calculateCommission(): Money {
+    return this.totalRevenue.multiply(this.commissionRate / 100);
+  }
+
+  isActive(): boolean {
+    return this.active;
+  }
+
+  getStats() {
+    return {
+      totalVisits: this.totalVisits,
+      totalConversions: this.totalConversions,
+      totalRevenue: this.totalRevenue,
+      commission: this.calculateCommission(),
+      conversionRate: this.totalVisits > 0
+        ? (this.totalConversions / this.totalVisits) * 100
+        : 0,
+    };
+  }
+
+  toJSON() {
+    return {
+      id: this.id.toString(),
+      siteId: this.siteId.toString(),
+      name: this.name,
+      slug: this.slug,
+      commissionRate: this.commissionRate,
+      active: this.active,
+      stats: this.getStats(),
+      createdAt: this.createdAt,
+    };
+  }
+}

package/src/domains/affiliate/entities/affiliate-visit.entity.ts

@@ -0,0 +1,52 @@
+/**
+ * AffiliateVisit Entity
+ * @description Represents a visit attributed to an affiliate
+ */
+
+import type { EventId } from '../../tracking/value-objects/event-id.vo';
+import type { AffiliateId } from '../value-objects/affiliate-id.vo';
+import type { SiteId } from '../value-objects/site-id.vo';
+import type { SessionId } from '../../tracking/value-objects/session-id.vo';
+
+export interface AffiliateVisitCreateInput {
+  id: EventId;
+  affiliateId: AffiliateId;
+  siteId: SiteId;
+  visitorId: string;
+  sessionId: SessionId;
+  landingPage: string;
+  timestamp?: number;
+}
+
+export class AffiliateVisit {
+  readonly id: EventId;
+  readonly affiliateId: AffiliateId;
+  readonly siteId: SiteId;
+  readonly visitorId: string;
+  readonly sessionId: SessionId;
+  readonly landingPage: string;
+  readonly timestamp: number;
+
+  constructor(input: AffiliateVisitCreateInput) {
+    this.id = input.id;
+    this.affiliateId = input.affiliateId;
+    this.siteId = input.siteId;
+    this.visitorId = input.visitorId;
+    this.sessionId = input.sessionId;
+    this.landingPage = input.landingPage;
+    this.timestamp = input.timestamp ?? Date.now();
+    Object.freeze(this);
+  }
+
+  toJSON() {
+    return {
+      id: this.id.toString(),
+      affiliateId: this.affiliateId.toString(),
+      siteId: this.siteId.toString(),
+      visitorId: this.visitorId,
+      sessionId: this.sessionId.toString(),
+      landingPage: this.landingPage,
+      timestamp: this.timestamp,
+    };
+  }
+}

package/src/domains/affiliate/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Affiliate Domain Export
+ * Subpath: @umituz/web-traffic/affiliate
+ */
+
+// Aggregates
+export { Affiliate } from './aggregates/affiliate.aggregate';
+export type { AffiliateCreateInput } from './aggregates/affiliate.aggregate';
+
+// Entities
+export { AffiliateVisit } from './entities/affiliate-visit.entity';
+export type { AffiliateVisitCreateInput } from './entities/affiliate-visit.entity';
+
+// Value Objects
+export { AffiliateId } from './value-objects/affiliate-id.vo';
+export { SiteId } from './value-objects/site-id.vo';
+
+// Repository Interfaces
+export type {
+  IAffiliateRepository,
+  IAffiliateVisitRepository,
+} from './repositories/affiliate.repository.interface';

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

@@ -0,0 +1,26 @@
+/**
+ * Affiliate Repository Interface
+ * @description Repository interface for Affiliate persistence (Domain Layer)
+ */
+
+import type { Affiliate } from '../aggregates/affiliate.aggregate';
+import type { AffiliateVisit } from '../entities/affiliate-visit.entity';
+import type { AffiliateId } from '../value-objects/affiliate-id.vo';
+import type { SiteId } from '../value-objects/site-id.vo';
+import type { SessionId } from '../../tracking/value-objects/session-id.vo';
+
+export interface IAffiliateRepository {
+  save(affiliate: Affiliate): Promise<void>;
+  findById(id: AffiliateId): Promise<Affiliate | null>;
+  findBySlug(siteId: SiteId, slug: string): Promise<Affiliate | null>;
+  findBySite(siteId: SiteId): Promise<Affiliate[]>;
+  delete(id: AffiliateId): Promise<void>;
+}
+
+export interface IAffiliateVisitRepository {
+  save(visit: AffiliateVisit): Promise<void>;
+  findById(id: import('../../tracking/value-objects/event-id.vo').EventId): Promise<AffiliateVisit | null>;
+  findByAffiliate(affiliateId: AffiliateId): Promise<AffiliateVisit[]>;
+  findByVisitorAndSession(visitorId: string, sessionId: SessionId): Promise<AffiliateVisit[]>;
+  delete(id: import('../../tracking/value-objects/event-id.vo').EventId): Promise<void>;
+}

package/src/domains/affiliate/value-objects/affiliate-id.vo.ts

@@ -0,0 +1,35 @@
+/**
+ * AffiliateId Value Object
+ * @description Immutable value object for affiliate identification
+ */
+
+export class AffiliateId {
+  private readonly value: string;
+
+  constructor(value: string) {
+    if (!value || value.trim().length === 0) {
+      throw new Error('AffiliateId cannot be empty');
+    }
+    if (!/^[a-zA-Z0-9-_]+$/.test(value)) {
+      throw new Error('AffiliateId must contain only alphanumeric characters, hyphens, and underscores');
+    }
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  equals(other: AffiliateId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  static fromSlug(slug: string): AffiliateId {
+    return new AffiliateId(slug);
+  }
+}

package/src/domains/affiliate/value-objects/site-id.vo.ts

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

package/src/domains/analytics/entities/analytics.entity.ts

@@ -0,0 +1,33 @@
+/**
+ * Analytics Entity
+ * @description Represents aggregated analytics data
+ */
+
+export interface AnalyticsData {
+  readonly pageviews: number;
+  readonly sessions: number;
+  readonly visitors: number;
+  readonly bounceRate: number;
+  readonly avgSessionDuration: number;
+  readonly topPages: TopPage[];
+  readonly topSources: TopSource[];
+  readonly conversions: ConversionStats;
+}
+
+export interface TopPage {
+  readonly path: string;
+  readonly pageviews: number;
+  readonly uniqueVisitors: number;
+}
+
+export interface TopSource {
+  readonly source: string;
+  readonly sessions: number;
+  readonly percentage: number;
+}
+
+export interface ConversionStats {
+  readonly total: number;
+  readonly revenue: number;
+  readonly rate: number;
+}

package/src/domains/analytics/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Analytics Domain Export
+ * Subpath: @umituz/web-traffic/analytics
+ */
+
+// Entities
+export type {
+  AnalyticsData,
+  TopPage,
+  TopSource,
+  ConversionStats,
+} from './entities/analytics.entity';
+
+// Repository Interfaces
+export type {
+  IAnalyticsRepository,
+  AnalyticsQuery,
+} from './repositories/analytics.repository.interface';