@stacksjs/ts-analytics 0.1.6

package/dist/types.d.ts

@@ -0,0 +1,595 @@
+/**
+ * GSI projection configuration
+ */
+export declare interface IndexProjection {
+  type: ProjectionType
+  attributes?: string[]
+}
+/**
+ * Global Secondary Index definition
+ */
+export declare interface GSIDefinition {
+  name: string
+  partitionKey: string
+  sortKey?: string
+  projection: IndexProjection
+  readCapacity?: number
+  writeCapacity?: number
+}
+/**
+ * Local Secondary Index definition
+ */
+export declare interface LSIDefinition {
+  name: string
+  sortKey: string
+  projection: IndexProjection
+}
+/**
+ * Single-table design configuration (compatible with dynamodb-tooling)
+ */
+export declare interface SingleTableDesignConfig {
+  enabled: boolean
+  partitionKeyName: string
+  sortKeyName: string
+  gsi1pkName: string
+  gsi1skName: string
+  gsi2pkName: string
+  gsi2skName: string
+  entityTypeAttribute: string
+  pkPrefix: string
+  skPrefix: string
+  gsiCount: number
+  keyDelimiter: string
+}
+/**
+ * Analytics DynamoDB table configuration
+ */
+export declare interface AnalyticsTableConfig {
+  tableName: string
+  billingMode: BillingMode
+  singleTable: SingleTableDesignConfig
+  globalSecondaryIndexes: GSIDefinition[]
+  localSecondaryIndexes: LSIDefinition[]
+  ttlAttributeName?: string
+}
+/**
+ * Key pattern templates for analytics entities
+ *
+ * Single-table design following Alex DeBrie patterns:
+ * - PK: ENTITY#id (for direct lookups)
+ * - SK: ENTITY#id or composite for hierarchical data
+ * - GSI1: For access patterns like site-based queries
+ * - GSI2: For time-based queries
+ */
+export declare interface AnalyticsKeyPatterns {
+  site: {
+    pk: `SITE#${string}`
+    sk: `SITE#${string}`
+  }
+  pageView: {
+    pk: `SITE#${string}`
+    sk: `PV#${string}#${string}`
+    gsi1pk: `SESSION#${string}`
+    gsi1sk: `PV#${string}`
+  }
+  session: {
+    pk: `SITE#${string}`
+    sk: `SESSION#${string}`
+    gsi1pk: `VISITOR#${string}`
+    gsi1sk: `SESSION#${string}`
+  }
+  event: {
+    pk: `SITE#${string}`
+    sk: `EVENT#${string}#${string}`
+    gsi1pk: `SESSION#${string}`
+    gsi1sk: `EVENT#${string}`
+  }
+  goal: {
+    pk: `SITE#${string}`
+    sk: `GOAL#${string}`
+  }
+  conversion: {
+    pk: `SITE#${string}`
+    sk: `CONV#${string}#${string}`
+    gsi1pk: `GOAL#${string}`
+    gsi1sk: `CONV#${string}`
+  }
+  aggregatedStats: {
+    pk: `SITE#${string}`
+    sk: `STATS#${string}#${string}`
+  }
+  pageStats: {
+    pk: `SITE#${string}`
+    sk: `PSTATS#${string}#${string}#${string}`
+  }
+  referrerStats: {
+    pk: `SITE#${string}`
+    sk: `RSTATS#${string}#${string}#${string}`
+  }
+  realtimeStats: {
+    pk: `SITE#${string}`
+    sk: `RT#${string}`
+  }
+}
+/**
+ * Site settings
+ */
+export declare interface SiteSettings {
+  collectGeolocation: boolean
+  trackReferrers: boolean
+  trackUtmParams: boolean
+  trackDeviceType: boolean
+  publicDashboard: boolean
+  publicDashboardPassword?: string
+  excludedPaths: string[]
+  excludedIps: string[]
+  dataRetentionDays: number
+}
+/**
+ * Site/Website being tracked
+ */
+export declare interface Site {
+  id: string
+  name: string
+  domains: string[]
+  timezone: string
+  isActive: boolean
+  ownerId: string
+  settings: SiteSettings
+  createdAt: Date
+  updatedAt: Date
+}
+/**
+ * Page view event (raw event - stored temporarily for aggregation)
+ */
+export declare interface PageView {
+  id: string
+  siteId: string
+  visitorId: string
+  sessionId: string
+  path: string
+  hostname: string
+  title?: string
+  referrer?: string
+  referrerSource?: string
+  utmSource?: string
+  utmMedium?: string
+  utmCampaign?: string
+  utmContent?: string
+  utmTerm?: string
+  gclid?: string
+  fbclid?: string
+  country?: string
+  region?: string
+  city?: string
+  deviceType?: DeviceType
+  browser?: string
+  browserVersion?: string
+  os?: string
+  osVersion?: string
+  screenWidth?: number
+  screenHeight?: number
+  isUnique: boolean
+  isBounce: boolean
+  timeOnPage?: number
+  timestamp: Date
+  ttl?: number
+}
+/**
+ * Custom event (non-pageview events like button clicks, form submissions)
+ */
+export declare interface CustomEvent {
+  id: string
+  siteId: string
+  visitorId: string
+  sessionId: string
+  name: string
+  category?: string
+  value?: number
+  properties?: Record<string, string | number | boolean>
+  path: string
+  timestamp: Date
+  ttl?: number
+}
+/**
+ * Session (visitor session)
+ */
+export declare interface Session {
+  id: string
+  siteId: string
+  visitorId: string
+  entryPath: string
+  exitPath: string
+  referrer?: string
+  referrerSource?: string
+  utmSource?: string
+  utmMedium?: string
+  utmCampaign?: string
+  utmContent?: string
+  utmTerm?: string
+  gclid?: string
+  fbclid?: string
+  country?: string
+  region?: string
+  city?: string
+  deviceType?: DeviceType
+  browser?: string
+  os?: string
+  pageViewCount: number
+  eventCount: number
+  isBounce: boolean
+  duration: number
+  startedAt: Date
+  endedAt: Date
+  ttl?: number
+}
+/**
+ * Goal/Conversion definition
+ */
+export declare interface Goal {
+  id: string
+  siteId: string
+  name: string
+  type: GoalType
+  pattern: string
+  matchType: 'exact' | 'contains' | 'regex'
+  value?: number
+  isActive: boolean
+  createdAt: Date
+  updatedAt: Date
+}
+/**
+ * Conversion record (goal completion)
+ */
+export declare interface Conversion {
+  id: string
+  siteId: string
+  goalId: string
+  visitorId: string
+  sessionId: string
+  value?: number
+  path: string
+  referrerSource?: string
+  utmSource?: string
+  utmCampaign?: string
+  timestamp: Date
+  ttl?: number
+}
+/**
+ * Aggregated stats (pre-computed for fast dashboard queries)
+ */
+export declare interface AggregatedStats {
+  siteId: string
+  period: AggregationPeriod
+  periodStart: string
+  pageViews: number
+  uniqueVisitors: number
+  sessions: number
+  bounces: number
+  bounceRate: number
+  avgSessionDuration: number
+  avgPagesPerSession: number
+  totalTimeOnSite: number
+  newVisitors: number
+  returningVisitors: number
+  createdAt: Date
+  updatedAt: Date
+}
+/**
+ * Page-level aggregated stats
+ */
+export declare interface PageStats {
+  siteId: string
+  period: AggregationPeriod
+  periodStart: string
+  path: string
+  title?: string
+  pageViews: number
+  uniqueVisitors: number
+  entries: number
+  exits: number
+  bounces: number
+  avgTimeOnPage: number
+  exitRate: number
+}
+/**
+ * Referrer stats
+ */
+export declare interface ReferrerStats {
+  siteId: string
+  period: AggregationPeriod
+  periodStart: string
+  source: string
+  referrer?: string
+  visitors: number
+  pageViews: number
+  bounceRate: number
+  avgSessionDuration: number
+}
+/**
+ * Geographic stats
+ */
+export declare interface GeoStats {
+  siteId: string
+  period: AggregationPeriod
+  periodStart: string
+  country: string
+  region?: string
+  city?: string
+  visitors: number
+  pageViews: number
+  bounceRate: number
+}
+/**
+ * Device/Browser stats
+ */
+export declare interface DeviceStats {
+  siteId: string
+  period: AggregationPeriod
+  periodStart: string
+  dimension: 'device' | 'browser' | 'os' | 'screen'
+  value: string
+  visitors: number
+  pageViews: number
+  bounceRate: number
+}
+/**
+ * UTM Campaign stats
+ */
+export declare interface CampaignStats {
+  siteId: string
+  period: AggregationPeriod
+  periodStart: string
+  utmSource: string
+  utmMedium?: string
+  utmCampaign?: string
+  visitors: number
+  pageViews: number
+  conversions: number
+  conversionRate: number
+  revenue: number
+  bounceRate: number
+}
+/**
+ * Custom event stats
+ */
+export declare interface EventStats {
+  siteId: string
+  period: AggregationPeriod
+  periodStart: string
+  eventName: string
+  count: number
+  uniqueVisitors: number
+  totalValue: number
+  avgValue: number
+}
+/**
+ * Goal stats (conversions)
+ */
+export declare interface GoalStats {
+  siteId: string
+  goalId: string
+  period: AggregationPeriod
+  periodStart: string
+  conversions: number
+  uniqueConversions: number
+  conversionRate: number
+  revenue: number
+}
+/**
+ * Real-time stats (last 5 minutes, stored with short TTL)
+ */
+export declare interface RealtimeStats {
+  siteId: string
+  minute: string
+  currentVisitors: number
+  pageViews: number
+  activePages: Record<string, number>
+  visitorIds?: string[]
+  ttl: number
+}
+/**
+ * Date range for queries
+ */
+export declare interface DateRange {
+  start: Date
+  end: Date
+}
+/**
+ * Query options
+ */
+export declare interface QueryOptions {
+  siteId: string
+  dateRange: DateRange
+  includeComparison?: boolean
+  groupBy?: 'hour' | 'day' | 'month'
+}
+/**
+ * Dashboard summary data
+ */
+export declare interface DashboardSummary {
+  pageViews: number
+  uniqueVisitors: number
+  sessions: number
+  bounceRate: number
+  avgSessionDuration: number
+  avgPagesPerSession: number
+  change?: {
+    pageViews: number
+    uniqueVisitors: number
+    sessions: number
+    bounceRate: number
+    avgSessionDuration: number
+  }
+}
+/**
+ * Time series data point
+ */
+export declare interface TimeSeriesPoint {
+  date: string
+  pageViews: number
+  uniqueVisitors: number
+  sessions: number
+}
+/**
+ * Top item (page, referrer, etc.)
+ */
+export declare interface TopItem {
+  name: string
+  value: number
+  percentage: number
+  metadata?: Record<string, string | undefined>
+}
+/**
+ * Realtime data
+ */
+export declare interface RealtimeData {
+  currentVisitors: number
+  pageViewsLastHour: number
+  topActivePages: TopItem[]
+}
+/**
+ * Dashboard data
+ */
+export declare interface DashboardData {
+  summary: DashboardSummary
+  timeSeries: TimeSeriesPoint[]
+  topPages: TopItem[]
+  topReferrers: TopItem[]
+  deviceBreakdown: TopItem[]
+  realtime?: RealtimeData
+}
+/**
+ * Goal match result
+ */
+export declare interface GoalMatchResult {
+  goalId: string
+  goalName: string
+  value?: number
+  matchedAt: Date
+  matchedPath: string
+  matchedEvent?: string
+}
+/**
+ * Goal performance metrics
+ */
+export declare interface GoalPerformance {
+  goalId: string
+  goalName: string
+  conversions: number
+  conversionRate: number
+  revenue: number
+  topConvertingPages: TopItem[]
+  topConvertingSources: TopItem[]
+}
+/**
+ * Aggregation job status
+ */
+export declare interface AggregationJobStatus {
+  jobId: string
+  siteId: string
+  period: AggregationPeriod
+  status: 'pending' | 'running' | 'completed' | 'failed'
+  startedAt?: Date
+  completedAt?: Date
+  error?: string
+  stats?: {
+    pageViewsProcessed: number
+    sessionsProcessed: number
+    eventsProcessed: number
+  }
+}
+/**
+ * Pipeline job configuration
+ */
+export declare interface PipelineJobConfig {
+  siteId: string
+  period: AggregationPeriod
+  windowStart: Date
+  windowEnd: Date
+  processPageViews: boolean
+  processSessions: boolean
+  processEvents: boolean
+  processGoals: boolean
+}
+/**
+ * Pipeline job result
+ */
+export declare interface PipelineJobResult {
+  success: boolean
+  aggregatedStats?: AggregatedStats
+  pageStats?: PageStats[]
+  referrerStats?: ReferrerStats[]
+  geoStats?: GeoStats[]
+  deviceStats?: DeviceStats[]
+  campaignStats?: CampaignStats[]
+  eventStats?: EventStats[]
+  goalStats?: GoalStats[]
+  errors?: string[]
+}
+/**
+ * Tracking script options
+ */
+export declare interface TrackingScriptOptions {
+  siteId: string
+  apiEndpoint?: string
+  honorDnt?: boolean
+  trackHashChanges?: boolean
+  trackOutboundLinks?: boolean
+  stealthMode?: boolean
+}
+/**
+ * Analytics store options
+ */
+export declare interface AnalyticsStoreOptions {
+  tableName: string
+  useTtl?: boolean
+  rawEventTtl?: number
+  hourlyAggregateTtl?: number
+  dailyAggregateTtl?: number
+}
+/**
+ * Aggregator options
+ */
+export declare interface AggregatorOptions {
+  store: unknown
+  batchSize?: number
+}
+/**
+ * DynamoDB billing mode
+ */
+export type BillingMode = 'PAY_PER_REQUEST' | 'PROVISIONED';
+/**
+ * Projection type for indexes
+ */
+export type ProjectionType = 'ALL' | 'KEYS_ONLY' | 'INCLUDE';
+/**
+ * Analytics entity types for single-table design
+ */
+export type AnalyticsEntityType = | 'SITE'
+  | 'PAGEVIEW'
+  | 'SESSION'
+  | 'EVENT'
+  | 'GOAL'
+  | 'CONVERSION'
+  | 'STATS_AGG'
+  | 'STATS_PAGE'
+  | 'STATS_REF'
+  | 'STATS_GEO'
+  | 'STATS_DEVICE'
+  | 'STATS_CAMPAIGN'
+  | 'STATS_EVENT'
+  | 'STATS_GOAL'
+  | 'REALTIME';
+/**
+ * Device type
+ */
+export type DeviceType = 'desktop' | 'mobile' | 'tablet' | 'unknown';
+/**
+ * Goal type
+ */
+export type GoalType = 'pageview' | 'event';
+/**
+ * Time period for aggregations
+ */
+export type AggregationPeriod = 'hour' | 'day' | 'month';

package/dist/utils/geolocation.d.ts

@@ -0,0 +1,111 @@
+/** ISO-3166 alpha-2 code for a stored country value (name or code). */
+export declare function countryCodeOf(nameOrCode: string): string | undefined;
+/** Emoji flag (regional indicator pair) for an ISO alpha-2 code — Fathom-style. */
+export declare function countryFlagEmoji(code: string): string;
+/**
+ * Get country from CloudFront/Cloudflare headers
+ */
+export declare function getCountryFromHeaders(headers: Record<string, string> | undefined): string | undefined;
+/**
+ * Get country from IP address using geolocation services
+ */
+/**
+ * Reduce an IP's precision before it leaves the system (e.g. to a third-party
+ * geo API), per config.privacy.ipAnonymization (#144). 'partial' drops the host
+ * portion (IPv4 /24, IPv6 /48) — still country-accurate; 'full' drops it
+ * entirely; 'none' passes through.
+ */
+export declare function anonymizeIp(ip: string, mode?: string): string;
+export declare function getCountryFromIP(ip: string): Promise<string | undefined>;
+/**
+ * Parse a referrer URL into a normalized, human-readable source name
+ * (e.g. "Google", "Reddit", "ChatGPT"). Unknown hosts fall back to the
+ * bare domain (www. stripped). Empty → "Direct", invalid → "Unknown".
+ */
+export declare function parseReferrerSource(referrer?: string): string;
+/**
+ * Classify traffic into a marketing channel. Paid/email are inferred from
+ * UTM medium and ad click IDs (gclid/fbclid); otherwise from the referrer.
+ */
+export declare function getReferrerChannel(opts: {
+  referrer?: string
+  utmMedium?: string
+  gclid?: string
+  fbclid?: string
+}): ReferrerChannel;
+/**
+ * Channel for an already-normalized source name (e.g. a stored referrerSource).
+ * Used at query time where the original referrer/UTM is no longer available, so
+ * it can only classify Search/Social/AI/Referral/Direct (not Paid/Email).
+ */
+export declare function getReferrerSourceChannel(source?: string): ReferrerChannel;
+/**
+ * Whether a referrer is a known referral-spam domain (so its hits can be dropped).
+ */
+export declare function isSpamReferrer(referrer?: string): boolean;
+/**
+ * Get region from headers (CloudFront/Cloudflare)
+ */
+export declare function getRegionFromHeaders(headers: Record<string, string> | undefined): string | undefined;
+/**
+ * Get city from headers (CloudFront/Cloudflare)
+ */
+export declare function getCityFromHeaders(headers: Record<string, string> | undefined): string | undefined;
+/**
+ * Geolocation utilities
+ */
+// Country code to name mapping
+export declare const COUNTRY_NAMES: {
+  US: 'United States';
+  GB: 'United Kingdom';
+  CA: 'Canada';
+  AU: 'Australia';
+  DE: 'Germany';
+  FR: 'France';
+  JP: 'Japan';
+  CN: 'China';
+  IN: 'India';
+  BR: 'Brazil';
+  MX: 'Mexico';
+  ES: 'Spain';
+  IT: 'Italy';
+  NL: 'Netherlands';
+  SE: 'Sweden';
+  NO: 'Norway';
+  DK: 'Denmark';
+  FI: 'Finland';
+  CH: 'Switzerland';
+  AT: 'Austria';
+  BE: 'Belgium';
+  PL: 'Poland';
+  RU: 'Russia';
+  KR: 'South Korea';
+  SG: 'Singapore';
+  HK: 'Hong Kong';
+  TW: 'Taiwan';
+  NZ: 'New Zealand';
+  IE: 'Ireland';
+  PT: 'Portugal';
+  CZ: 'Czech Republic';
+  GR: 'Greece';
+  IL: 'Israel';
+  ZA: 'South Africa';
+  AR: 'Argentina';
+  CL: 'Chile';
+  CO: 'Colombia';
+  PH: 'Philippines';
+  TH: 'Thailand';
+  MY: 'Malaysia';
+  ID: 'Indonesia';
+  VN: 'Vietnam';
+  AE: 'UAE';
+  SA: 'Saudi Arabia';
+  TR: 'Turkey';
+  UA: 'Ukraine';
+  RO: 'Romania';
+  HU: 'Hungary'
+};
+/**
+ * Marketing channel a referrer belongs to.
+ */
+export type ReferrerChannel = 'Search' | 'Social' | 'AI' | 'Email' | 'Referral' | 'Paid' | 'Direct';

package/dist/utils/user-agent.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parse user agent string to extract device, browser, and OS info
+ */
+export declare function parseUserAgent(ua: string): ParsedUserAgent;
+export declare function isBot(ua: string): boolean;
+/**
+ * Get browser family (simplifies browser name to family)
+ */
+export declare function getBrowserFamily(browser: string): string;
+/**
+ * User agent parsing utilities
+ */
+export declare interface ParsedUserAgent {
+  deviceType: 'desktop' | 'mobile' | 'tablet'
+  browser: string
+  os: string
+}

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tracker/library version (#179) — embedded in the generated script, sent on
+ * every beacon (`v`), and aggregated into the hourly ingest counters, so
+ * support can tell exactly which tracker build a site is running instead of
+ * guessing at cache states. Kept in sync with package.json by a test.
+ */
+export declare const TRACKER_VERSION: string;