Build a URL Shortener: Redirect Engine & Analytics

// src/types/url.ts — updated
 
export interface UrlRecord {
  id: string;
  shortCode: string;
  originalUrl: string;
  redirectType: 301 | 302;
  isActive: boolean;
  expiresAt: Date | null;
  createdAt: Date;
  updatedAt: Date;
  clickCount: number;
}

// prisma/schema.prisma
 
model Url {
  id           String    @id @default(cuid())
  shortCode    String    @unique @map("short_code")
  originalUrl  String    @map("original_url")
  redirectType Int       @default(302) @map("redirect_type")
  isActive     Boolean   @default(true) @map("is_active")
  expiresAt    DateTime? @map("expires_at")
  clickCount   Int       @default(0) @map("click_count")
  createdAt    DateTime  @default(now()) @map("created_at")
  updatedAt    DateTime  @updatedAt @map("updated_at")
 
  // Relations
  clicks Click[]
 
  @@index([shortCode])
  @@index([isActive, expiresAt])
  @@map("urls")
}
 
model Click {
  id        String   @id @default(cuid())
  urlId     String   @map("url_id")
  timestamp DateTime @default(now())
 
  // Request metadata
  ipAddress String?  @map("ip_address")
  userAgent String?  @map("user_agent")
  referrer  String?
 
  // Parsed user-agent field
  browser        String?
  browserVersion String? @map("browser_version")
  os             String?
  osVersion      String? @map("os_version")
  deviceType     String? @map("device_type")
 
  // Geolocation
  country String?
  city    String?
 
  // Deduplication
  visitorId String? @map("visitor_id")
 
  // Relations
  url Url @relation(fields: [urlId], references: [id], onDelete: Cascade)
 
  @@index([urlId, timestamp])
  @@index([urlId, country])
  @@index([urlId, browser])
  @@index([urlId, deviceType])
  @@index([visitorId, urlId])
  @@map("clicks")
}

npx prisma migrate dev --name add-clicks-and-url-fields

npm install ua-parser-js geoip-lite
npm install -D @types/ua-parser-js @types/geoip-lite

// src/services/clickService.ts
 
import { PrismaClient } from '@prisma/client';
import UAParser from 'ua-parser-js';
import geoip from 'geoip-lite';
import crypto from 'crypto';
 
const prisma = new PrismaClient();
 
export interface ClickData {
  urlId: string;
  ipAddress: string | undefined;
  userAgent: string | undefined;
  referrer: string | undefined;
}
 
export class ClickService {
  /**
   * Record một click event. Method này được thiết kế để gọi
   * fire-and-forget — đừng await nó trong redirect path.
   */
  async recordClick(data: ClickData): Promise<void> {
    try {
      const parsed = this.parseUserAgent(data.userAgent);
      const geo = this.lookupGeolocation(data.ipAddress);
      const visitorId = this.generateVisitorId(data.ipAddress, data.userAgent);
 
      await prisma.click.create({
        data: {
          urlId: data.urlId,
          ipAddress: data.ipAddress,
          userAgent: data.userAgent,
          referrer: this.sanitizeReferrer(data.referrer),
          browser: parsed.browser,
          browserVersion: parsed.browserVersion,
          os: parsed.os,
          osVersion: parsed.osVersion,
          deviceType: parsed.deviceType,
          country: geo.country,
          city: geo.city,
          visitorId,
        },
      });
 
      // Tăng click count denormalized trên URL
      await prisma.url.update({
        where: { id: data.urlId },
        data: { clickCount: { increment: 1 } },
      });
    } catch (error) {
      // Log nhưng không throw — click tracking failure
      // không bao giờ được ảnh hưởng redirect
      console.error('Failed to record click:', error);
    }
  }
 
  private parseUserAgent(userAgent: string | undefined): ParsedUA {
    if (!userAgent) {
      return {
        browser: null,
        browserVersion: null,
        os: null,
        osVersion: null,
        deviceType: 'unknown',
      };
    }
 
    const parser = new UAParser(userAgent);
    const browser = parser.getBrowser();
    const os = parser.getOS();
    const device = parser.getDevice();
 
    return {
      browser: browser.name || null,
      browserVersion: browser.version || null,
      os: os.name || null,
      osVersion: os.version || null,
      deviceType: this.normalizeDeviceType(device.type),
    };
  }
 
  private normalizeDeviceType(type: string | undefined): string {
    // ua-parser-js trả về: console, mobile, tablet, smarttv, wearable, embedded
    // Ta normalize thành: mobile, tablet, desktop, other
    switch (type) {
      case 'mobile':
        return 'mobile';
      case 'tablet':
        return 'tablet';
      case 'smarttv':
      case 'console':
      case 'wearable':
      case 'embedded':
        return 'other';
      default:
        // undefined nghĩa là desktop (ua-parser-js không set type cho desktop)
        return 'desktop';
    }
  }
 
  private lookupGeolocation(ipAddress: string | undefined): GeoResult {
    if (!ipAddress) {
      return { country: null, city: null };
    }
 
    // Bỏ qua localhost/private IP
    if (this.isPrivateIp(ipAddress)) {
      return { country: null, city: null };
    }
 
    const geo = geoip.lookup(ipAddress);
    if (!geo) {
      return { country: null, city: null };
    }
 
    return {
      country: geo.country || null, // ISO 3166-1 alpha-2 (vd: "US", "VN")
      city: geo.city || null,
    };
  }
 
  private isPrivateIp(ip: string): boolean {
    // IPv4 private range
    const privateRanges = [
      /^127\./,         // Loopback
      /^10\./,          // Class A private
      /^172\.(1[6-9]|2[0-9]|3[01])\./, // Class B private
      /^192\.168\./,    // Class C private
      /^::1$/,          // IPv6 loopback
      /^fc00:/,         // IPv6 ULA
      /^fe80:/,         // IPv6 link-local
    ];
 
    return privateRanges.some((range) => range.test(ip));
  }
 
  private generateVisitorId(
    ipAddress: string | undefined,
    userAgent: string | undefined
  ): string | null {
    if (!ipAddress) return null;
 
    // Hash IP + user-agent để tạo pseudonymous visitor ID
    // Cho phép đếm unique visitor mà không cần lưu raw IP
    const input = `${ipAddress}:${userAgent || 'unknown'}`;
    return crypto.createHash('sha256').update(input).digest('hex').slice(0, 16);
  }
 
  private sanitizeReferrer(referrer: string | undefined): string | null {
    if (!referrer) return null;
 
    try {
      const url = new URL(referrer);
      // Bỏ query param và fragment để bảo vệ privacy
      return `${url.protocol}//${url.host}${url.pathname}`;
    } catch {
      return null;
    }
  }
}
 
// Type definition
interface ParsedUA {
  browser: string | null;
  browserVersion: string | null;
  os: string | null;
  osVersion: string | null;
  deviceType: string;
}
 
interface GeoResult {
  country: string | null;
  city: string | null;
}

// src/routes/redirectRoutes.ts
 
import { Router, Request, Response, NextFunction } from 'express';
import { UrlService } from '../services/urlService';
import { ClickService } from '../services/clickService';
 
const router = Router();
const urlService = new UrlService();
const clickService = new ClickService();
 
// GET /:code — redirect tới original URL
router.get(
  '/:code',
  async (req: Request, res: Response, next: NextFunction) => {
    try {
      const { code } = req.params;
 
      // Resolve short code thành URL record
      const urlRecord = await urlService.resolveUrl(code);
 
      if (!urlRecord) {
        res.status(404).json({ error: 'Short URL not found' });
        return;
      }
 
      // Check URL bị deactivate chưa
      if (!urlRecord.isActive) {
        res.status(410).json({
          error: 'This short URL has been deactivated',
        });
        return;
      }
 
      // Check URL hết hạn chưa
      if (urlRecord.expiresAt && urlRecord.expiresAt < new Date()) {
        res.status(410).json({
          error: 'This short URL has expired',
        });
        return;
      }
 
      // Gửi redirect TRƯỚC — đây là critical path
      res.redirect(urlRecord.redirectType, urlRecord.originalUrl);
 
      // Record click SAU redirect (fire-and-forget)
      // Chạy bất đồng bộ — ta không await
      const clientIp = getClientIp(req);
      clickService.recordClick({
        urlId: urlRecord.id,
        ipAddress: clientIp,
        userAgent: req.headers['user-agent'],
        referrer: req.headers['referer'], // Note: HTTP header viết sai chính tả là "referer"
      });
    } catch (error) {
      next(error);
    }
  }
);
 
/**
 * Extract client IP từ request, xử lý proxy.
 * Trong production sau reverse proxy (Nginx, CloudFlare),
 * IP thật nằm trong X-Forwarded-For hoặc X-Real-IP header.
 */
function getClientIp(req: Request): string | undefined {
  // X-Forwarded-For có thể chứa nhiều IP: client, proxy1, proxy2
  const forwarded = req.headers['x-forwarded-for'];
  if (forwarded) {
    const ips = (Array.isArray(forwarded) ? forwarded[0] : forwarded).split(',');
    return ips[0].trim();
  }
 
  const realIp = req.headers['x-real-ip'];
  if (realIp) {
    return Array.isArray(realIp) ? realIp[0] : realIp;
  }
 
  return req.socket.remoteAddress;
}
 
export default router;

// Gửi redirect TRƯỚC
res.redirect(urlRecord.redirectType, urlRecord.originalUrl);
 
// Record click SAU (fire-and-forget)
clickService.recordClick({ ... });

// src/services/urlService.ts — updated resolveUrl method
 
import { PrismaClient } from '@prisma/client';
 
const prisma = new PrismaClient();
 
export class UrlService {
  /**
   * Resolve short code thành URL record.
   * Trả về full record để redirect handler check
   * status, expiration, và redirect type.
   */
  async resolveUrl(shortCode: string) {
    const url = await prisma.url.findUnique({
      where: { shortCode },
      select: {
        id: true,
        shortCode: true,
        originalUrl: true,
        redirectType: true,
        isActive: true,
        expiresAt: true,
      },
    });
 
    return url;
  }
 
  /**
   * Tạo short URL mới với optional redirect configuration.
   */
  async createUrl(data: {
    originalUrl: string;
    shortCode: string;
    customAlias?: string;
    redirectType?: 301 | 302;
    expiresAt?: Date;
  }) {
    return prisma.url.create({
      data: {
        shortCode: data.shortCode,
        originalUrl: data.originalUrl,
        redirectType: data.redirectType ?? 302,
        expiresAt: data.expiresAt ?? null,
      },
    });
  }
 
  /**
   * Deactivate URL (soft delete).
   * URL vẫn tồn tại trong database nhưng không redirect nữa.
   */
  async deactivateUrl(shortCode: string) {
    return prisma.url.update({
      where: { shortCode },
      data: { isActive: false },
    });
  }
 
  /**
   * Kích hoạt lại URL đã bị deactivate.
   */
  async reactivateUrl(shortCode: string) {
    return prisma.url.update({
      where: { shortCode },
      data: { isActive: true },
    });
  }
}

// src/services/analyticsService.ts
 
import { PrismaClient } from '@prisma/client';
 
const prisma = new PrismaClient();
 
export interface AnalyticsQuery {
  startDate?: Date;
  endDate?: Date;
  groupBy?: 'hour' | 'day' | 'week' | 'month';
}
 
export interface ClicksOverTime {
  period: string;
  clicks: number;
  uniqueVisitors: number;
}
 
export interface TopReferrer {
  referrer: string;
  clicks: number;
}
 
export interface DeviceBreakdown {
  deviceType: string;
  clicks: number;
  percentage: number;
}
 
export interface BrowserBreakdown {
  browser: string;
  clicks: number;
  percentage: number;
}
 
export interface CountryBreakdown {
  country: string;
  clicks: number;
  percentage: number;
}
 
export interface UrlAnalytics {
  totalClicks: number;
  uniqueVisitors: number;
  clicksOverTime: ClicksOverTime[];
  topReferrers: TopReferrer[];
  devices: DeviceBreakdown[];
  browsers: BrowserBreakdown[];
  countries: CountryBreakdown[];
}
 
export class AnalyticsService {
  /**
   * Lấy analytics tổng hợp cho một URL.
   */
  async getUrlAnalytics(
    urlId: string,
    query: AnalyticsQuery = {}
  ): Promise<UrlAnalytics> {
    const { startDate, endDate } = this.getDateRange(query);
 
    // Chạy tất cả query song song để tăng performance
    const [
      totalClicks,
      uniqueVisitors,
      clicksOverTime,
      topReferrers,
      devices,
      browsers,
      countries,
    ] = await Promise.all([
      this.getTotalClicks(urlId, startDate, endDate),
      this.getUniqueVisitors(urlId, startDate, endDate),
      this.getClicksOverTime(urlId, startDate, endDate, query.groupBy || 'day'),
      this.getTopReferrers(urlId, startDate, endDate),
      this.getDeviceBreakdown(urlId, startDate, endDate),
      this.getBrowserBreakdown(urlId, startDate, endDate),
      this.getCountryBreakdown(urlId, startDate, endDate),
    ]);
 
    return {
      totalClicks,
      uniqueVisitors,
      clicksOverTime,
      topReferrers,
      devices,
      browsers,
      countries,
    };
  }
 
  private async getTotalClicks(
    urlId: string,
    startDate: Date,
    endDate: Date
  ): Promise<number> {
    return prisma.click.count({
      where: {
        urlId,
        timestamp: { gte: startDate, lte: endDate },
      },
    });
  }
 
  private async getUniqueVisitors(
    urlId: string,
    startDate: Date,
    endDate: Date
  ): Promise<number> {
    // Đếm distinct visitor ID
    const result = await prisma.click.groupBy({
      by: ['visitorId'],
      where: {
        urlId,
        visitorId: { not: null },
        timestamp: { gte: startDate, lte: endDate },
      },
    });
 
    return result.length;
  }
 
  private async getClicksOverTime(
    urlId: string,
    startDate: Date,
    endDate: Date,
    groupBy: 'hour' | 'day' | 'week' | 'month'
  ): Promise<ClicksOverTime[]> {
    // Dùng raw SQL cho date truncation — Prisma không hỗ trợ
    // date_trunc natively trong groupBy
    const truncFormat = this.getDateTruncFormat(groupBy);
 
    const results: any[] = await prisma.$queryRaw`
      SELECT
        date_trunc(${truncFormat}, timestamp) as period,
        COUNT(*)::int as clicks,
        COUNT(DISTINCT visitor_id)::int as unique_visitors
      FROM clicks
      WHERE url_id = ${urlId}
        AND timestamp >= ${startDate}
        AND timestamp <= ${endDate}
      GROUP BY period
      ORDER BY period ASC
    `;
 
    return results.map((row) => ({
      period: row.period.toISOString(),
      clicks: row.clicks,
      uniqueVisitors: row.unique_visitors,
    }));
  }
 
  private async getTopReferrers(
    urlId: string,
    startDate: Date,
    endDate: Date,
    limit: number = 10
  ): Promise<TopReferrer[]> {
    const results = await prisma.click.groupBy({
      by: ['referrer'],
      where: {
        urlId,
        referrer: { not: null },
        timestamp: { gte: startDate, lte: endDate },
      },
      _count: { referrer: true },
      orderBy: { _count: { referrer: 'desc' } },
      take: limit,
    });
 
    return results.map((row) => ({
      referrer: row.referrer || 'Direct',
      clicks: row._count.referrer,
    }));
  }
 
  private async getDeviceBreakdown(
    urlId: string,
    startDate: Date,
    endDate: Date
  ): Promise<DeviceBreakdown[]> {
    const results = await prisma.click.groupBy({
      by: ['deviceType'],
      where: {
        urlId,
        timestamp: { gte: startDate, lte: endDate },
      },
      _count: { deviceType: true },
      orderBy: { _count: { deviceType: 'desc' } },
    });
 
    const total = results.reduce((sum, r) => sum + r._count.deviceType, 0);
 
    return results.map((row) => ({
      deviceType: row.deviceType || 'unknown',
      clicks: row._count.deviceType,
      percentage: total > 0
        ? Math.round((row._count.deviceType / total) * 10000) / 100
        : 0,
    }));
  }
 
  private async getBrowserBreakdown(
    urlId: string,
    startDate: Date,
    endDate: Date
  ): Promise<BrowserBreakdown[]> {
    const results = await prisma.click.groupBy({
      by: ['browser'],
      where: {
        urlId,
        timestamp: { gte: startDate, lte: endDate },
      },
      _count: { browser: true },
      orderBy: { _count: { browser: 'desc' } },
      take: 10,
    });
 
    const total = results.reduce((sum, r) => sum + r._count.browser, 0);
 
    return results.map((row) => ({
      browser: row.browser || 'Unknown',
      clicks: row._count.browser,
      percentage: total > 0
        ? Math.round((row._count.browser / total) * 10000) / 100
        : 0,
    }));
  }
 
  private async getCountryBreakdown(
    urlId: string,
    startDate: Date,
    endDate: Date
  ): Promise<CountryBreakdown[]> {
    const results = await prisma.click.groupBy({
      by: ['country'],
      where: {
        urlId,
        timestamp: { gte: startDate, lte: endDate },
      },
      _count: { country: true },
      orderBy: { _count: { country: 'desc' } },
      take: 20,
    });
 
    const total = results.reduce((sum, r) => sum + r._count.country, 0);
 
    return results.map((row) => ({
      country: row.country || 'Unknown',
      clicks: row._count.country,
      percentage: total > 0
        ? Math.round((row._count.country / total) * 10000) / 100
        : 0,
    }));
  }
 
  private getDateRange(query: AnalyticsQuery): {
    startDate: Date;
    endDate: Date;
  } {
    const endDate = query.endDate || new Date();
    const startDate = query.startDate || new Date(
      endDate.getTime() - 30 * 24 * 60 * 60 * 1000 // Default: 30 ngày gần nhất
    );
 
    return { startDate, endDate };
  }
 
  private getDateTruncFormat(
    groupBy: 'hour' | 'day' | 'week' | 'month'
  ): string {
    const formats = {
      hour: 'hour',
      day: 'day',
      week: 'week',
      month: 'month',
    };
    return formats[groupBy];
  }
}

Math.round((count / total) * 10000) / 100
// 3456 / 10000 * 10000 = 3456 → / 100 = 34.56%

// src/routes/analyticsRoutes.ts
 
import { Router, Request, Response, NextFunction } from 'express';
import { AnalyticsService } from '../services/analyticsService';
import { PrismaClient } from '@prisma/client';
 
const router = Router();
const analyticsService = new AnalyticsService();
const prisma = new PrismaClient();
 
// GET /api/urls/:code/stats — summary stats cho URL
router.get(
  '/urls/:code/stats',
  async (req: Request, res: Response, next: NextFunction) => {
    try {
      const url = await prisma.url.findUnique({
        where: { shortCode: req.params.code },
      });
 
      if (!url) {
        res.status(404).json({ error: 'Short URL not found' });
        return;
      }
 
      const { startDate, endDate, groupBy } = parseQueryParams(req);
 
      const analytics = await analyticsService.getUrlAnalytics(url.id, {
        startDate,
        endDate,
        groupBy,
      });
 
      res.json({
        shortCode: url.shortCode,
        originalUrl: url.originalUrl,
        isActive: url.isActive,
        createdAt: url.createdAt,
        ...analytics,
      });
    } catch (error) {
      next(error);
    }
  }
);
 
// GET /api/urls/:code/clicks — raw click event (có phân trang)
router.get(
  '/urls/:code/clicks',
  async (req: Request, res: Response, next: NextFunction) => {
    try {
      const url = await prisma.url.findUnique({
        where: { shortCode: req.params.code },
      });
 
      if (!url) {
        res.status(404).json({ error: 'Short URL not found' });
        return;
      }
 
      const page = parseInt(req.query.page as string) || 1;
      const limit = Math.min(parseInt(req.query.limit as string) || 50, 100);
      const offset = (page - 1) * limit;
 
      const [clicks, total] = await Promise.all([
        prisma.click.findMany({
          where: { urlId: url.id },
          orderBy: { timestamp: 'desc' },
          skip: offset,
          take: limit,
          select: {
            id: true,
            timestamp: true,
            referrer: true,
            browser: true,
            browserVersion: true,
            os: true,
            osVersion: true,
            deviceType: true,
            country: true,
            city: true,
          },
        }),
        prisma.click.count({ where: { urlId: url.id } }),
      ]);
 
      res.json({
        clicks,
        pagination: {
          page,
          limit,
          total,
          totalPages: Math.ceil(total / limit),
          hasMore: offset + limit < total,
        },
      });
    } catch (error) {
      next(error);
    }
  }
);
 
// Helper để parse analytics query parameter
function parseQueryParams(req: Request) {
  const startDate = req.query.start
    ? new Date(req.query.start as string)
    : undefined;
  const endDate = req.query.end
    ? new Date(req.query.end as string)
    : undefined;
  const groupBy = (req.query.groupBy as string) || 'day';
 
  // Validate groupBy
  const validGroupBy = ['hour', 'day', 'week', 'month'];
  if (!validGroupBy.includes(groupBy)) {
    throw new Error(
      `Invalid groupBy value. Must be one of: ${validGroupBy.join(', ')}`
    );
  }
 
  return {
    startDate,
    endDate,
    groupBy: groupBy as 'hour' | 'day' | 'week' | 'month',
  };
}
 
export default router;

// src/app.ts — thêm analytics route
 
import analyticsRoutes from './routes/analyticsRoutes';
 
// ... middleware hiện tại ...
 
// API route
app.use('/api', urlRoutes);
app.use('/api', analyticsRoutes);  // Thêm dòng này
 
// Redirect catch-all (phải ở cuối)
app.use(redirectRoutes);

const page = parseInt(req.query.page as string) || 1;
const limit = Math.min(parseInt(req.query.limit as string) || 50, 100);

private generateVisitorId(
  ipAddress: string | undefined,
  userAgent: string | undefined
): string | null {
  if (!ipAddress) return null;
 
  const input = `${ipAddress}:${userAgent || 'unknown'}`;
  return crypto.createHash('sha256').update(input).digest('hex').slice(0, 16);
}

COUNT(DISTINCT visitor_id) as unique_visitors

// Trong ClickService.recordClick() — optional deduplication
 
async recordClick(data: ClickData): Promise<void> {
  try {
    const visitorId = this.generateVisitorId(data.ipAddress, data.userAgent);
 
    // Optional: skip nếu cùng visitor click trong 5 phút gần nhất
    if (visitorId) {
      const recentClick = await prisma.click.findFirst({
        where: {
          urlId: data.urlId,
          visitorId,
          timestamp: {
            gte: new Date(Date.now() - 5 * 60 * 1000), // 5 phút
          },
        },
      });
 
      if (recentClick) {
        return; // Skip duplicate click
      }
    }
 
    // ... phần còn lại của recordClick logic
  } catch (error) {
    console.error('Failed to record click:', error);
  }
}

X-Forwarded-For: 203.0.113.42, 172.67.x.x, 10.0.0.1

// src/app.ts — trust proxy configuration
 
const app = express();
 
// Trust proxy đầu tiên (Nginx/load balancer)
// Làm cho req.ip trả về real client IP
app.set('trust proxy', 1);

url-shortener/
├── src/
│   ├── config/
│   │   └── env.ts
│   ├── middleware/
│   │   ├── errorHandler.ts
│   │   └── validateRequest.ts
│   ├── routes/
│   │   ├── urlRoutes.ts
│   │   ├── redirectRoutes.ts       # Updated: click tracking
│   │   └── analyticsRoutes.ts      # MỚI: analytics endpoint
│   ├── services/
│   │   ├── urlService.ts           # Updated: resolve + deactivate
│   │   ├── clickService.ts         # MỚI: click recording
│   │   └── analyticsService.ts     # MỚI: aggregation query
│   ├── types/
│   │   └── url.ts                  # Updated: field mới
│   ├── utils/
│   │   └── shortCode.ts
│   ├── app.ts                      # Updated: analytics route
│   └── index.ts
├── prisma/
│   └── schema.prisma               # Updated: Click model
├── .env
├── package.json
└── tsconfig.json

npm run dev

curl -X POST http://localhost:3000/api/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/expressjs/express",
    "redirectType": 302,
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

{
  "shortCode": "aBc1X9z",
  "shortUrl": "http://localhost:3000/aBc1X9z",
  "originalUrl": "https://github.com/expressjs/express",
  "redirectType": 302,
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "createdAt": "2026-03-21T10:00:00.000Z"
}

# Click từ nhiều "browser" khác nhau bằng cách thay đổi user-agent
curl -v -L http://localhost:3000/aBc1X9z \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0" \
  -H "Referer: https://twitter.com/post/123"
 
curl -v -L http://localhost:3000/aBc1X9z \
  -H "User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_0) Safari/605.1" \
  -H "Referer: https://facebook.com/share"
 
curl -v -L http://localhost:3000/aBc1X9z \
  -H "User-Agent: Mozilla/5.0 (Linux; Android 14) Chrome/120.0 Mobile"

curl http://localhost:3000/api/urls/aBc1X9z/stats

{
  "shortCode": "aBc1X9z",
  "originalUrl": "https://github.com/expressjs/express",
  "isActive": true,
  "createdAt": "2026-03-21T10:00:00.000Z",
  "totalClicks": 3,
  "uniqueVisitors": 3,
  "clicksOverTime": [
    {
      "period": "2026-03-21T00:00:00.000Z",
      "clicks": 3,
      "uniqueVisitors": 3
    }
  ],
  "topReferrers": [
    { "referrer": "https://twitter.com/post/123", "clicks": 1 },
    { "referrer": "https://facebook.com/share", "clicks": 1 }
  ],
  "devices": [
    { "deviceType": "desktop", "clicks": 1, "percentage": 33.33 },
    { "deviceType": "mobile", "clicks": 2, "percentage": 66.67 }
  ],
  "browsers": [
    { "browser": "Chrome", "clicks": 2, "percentage": 66.67 },
    { "browser": "Mobile Safari", "clicks": 1, "percentage": 33.33 }
  ],
  "countries": []
}

# 7 ngày gần nhất, group theo giờ
curl "http://localhost:3000/api/urls/aBc1X9z/stats?start=2026-03-14&end=2026-03-21&groupBy=hour"

curl "http://localhost:3000/api/urls/aBc1X9z/clicks?page=1&limit=10"

{
  "clicks": [
    {
      "id": "cm...",
      "timestamp": "2026-03-21T10:02:00.000Z",
      "referrer": "https://facebook.com/share",
      "browser": "Mobile Safari",
      "browserVersion": "605.1",
      "os": "iOS",
      "osVersion": "17.0",
      "deviceType": "mobile",
      "country": null,
      "city": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}

# Deactivate URL (bạn sẽ thêm endpoint này)
curl -X PATCH http://localhost:3000/api/urls/aBc1X9z \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'
 
# Thử truy cập
curl -v http://localhost:3000/aBc1X9z

< HTTP/1.1 410 Gone
{"error": "This short URL has been deactivated"}

// Concept — batch click recording
class BatchClickService {
  private buffer: ClickData[] = [];
  private readonly BATCH_SIZE = 100;
  private readonly FLUSH_INTERVAL = 5000; // 5 giây
 
  constructor() {
    setInterval(() => this.flush(), this.FLUSH_INTERVAL);
  }
 
  add(click: ClickData): void {
    this.buffer.push(click);
    if (this.buffer.length >= this.BATCH_SIZE) {
      this.flush();
    }
  }
 
  private async flush(): Promise<void> {
    if (this.buffer.length === 0) return;
 
    const batch = this.buffer.splice(0);
    try {
      await prisma.click.createMany({ data: batch });
    } catch (error) {
      console.error(`Failed to flush ${batch.length} clicks:`, error);
    }
  }
}

// SAI — redirect đợi click recording
const originalUrl = await urlService.resolveAndTrack(code);
await clickService.recordClick({ ... });  // Block!
res.redirect(302, originalUrl);
 
// ĐÚNG — redirect trước, record sau
res.redirect(302, originalUrl);
clickService.recordClick({ ... });  // Fire-and-forget

// SAI — lấy IP proxy, không phải IP user
const ip = req.socket.remoteAddress;
 
// ĐÚNG — check forwarded header
const ip = req.headers['x-forwarded-for']?.split(',')[0]?.trim()
  || req.headers['x-real-ip']
  || req.socket.remoteAddress;

// SAI — lộ PII
select: { ipAddress: true, ... }
 
// ĐÚNG — loại bỏ field nhạy cảm
select: {
  id: true,
  timestamp: true,
  browser: true,
  // ipAddress cố ý bị loại
}

// SAI — trả về tất cả click (có thể hàng triệu)
const clicks = await prisma.click.findMany({ where: { urlId } });
 
// ĐÚNG — phân trang với max limit
const limit = Math.min(parseInt(req.query.limit) || 50, 100);