@stacksjs/ts-analytics 0.1.6

package/dist/Analytics.d.ts

@@ -0,0 +1,558 @@
+import type { AggregatedStats, AggregationPeriod, AnalyticsStoreOptions, CampaignStats, CustomEvent, DeviceStats, DeviceType, EventStats, GeoStats, Goal, GoalStats, GoalType, PageStats, PageView, RealtimeStats, ReferrerStats, Session, Site, SiteSettings } from './types';
+// Re-export types from types.ts
+export type {
+  AggregatedStats,
+  AggregationPeriod,
+  AnalyticsStoreOptions,
+  CampaignStats,
+  CustomEvent,
+  DeviceStats,
+  DeviceType,
+  EventStats,
+  GeoStats,
+  Goal,
+  GoalStats,
+  GoalType,
+  PageStats,
+  PageView,
+  RealtimeStats,
+  ReferrerStats,
+  Session,
+  Site,
+  SiteSettings,
+};
+/**
+ * Generate minimal tracking script
+ */
+/* eslint-disable prefer-const, pickier/no-unused-vars, general/prefer-template */
+export declare function generateTrackingScript(options: TrackingScriptOptions): string;
+/**
+ * DynamoDB key patterns for analytics entities
+ */
+export declare const AnalyticsKeyPatterns: ({
+  // Sites
+  site: {
+    pk: (siteId: string)) => string;
+/**
+ * Aggregator options
+ */
+export declare interface AggregatorOptions {
+  store: AnalyticsStore
+  batchSize?: number
+}
+/**
+ * Result of a goal match check
+ */
+export declare interface GoalMatchResult {
+  matched: boolean
+  goal: Goal
+  value: number
+  trigger: PageView | CustomEvent
+  timestamp: Date
+}
+/**
+ * Conversion record for storage
+ */
+export declare interface Conversion {
+  id: string
+  siteId: string
+  goalId: string
+  visitorId: string
+  sessionId: string
+  value: number
+  path: string
+  timestamp: Date
+  ttl?: number
+}
+/**
+ * Date range for queries
+ */
+export declare interface DateRange {
+  start: Date
+  end: Date
+}
+/**
+ * Dashboard summary data
+ */
+export declare interface DashboardSummary {
+  pageViews: number
+  uniqueVisitors: number
+  sessions: number
+  bounceRate: number
+  avgSessionDuration: number
+  avgPagesPerSession: number
+  comparison?: {
+    pageViewsChange: number
+    visitorsChange: number
+    bounceRateChange: number
+  }
+}
+/**
+ * Time series data point
+ */
+export declare interface TimeSeriesPoint {
+  timestamp: string
+  pageViews: number
+  uniqueVisitors: number
+  sessions: number
+  bounceRate: number
+}
+/**
+ * Top item (page, referrer, country, etc.)
+ */
+export declare interface TopItem {
+  name: string
+  value: number
+  percentage: number
+  change?: number
+}
+/**
+ * Dashboard data response
+ */
+export declare interface DashboardData {
+  summary: DashboardSummary
+  timeSeries: TimeSeriesPoint[]
+  topPages: TopItem[]
+  topReferrers: TopItem[]
+  topCountries: TopItem[]
+  topDevices: TopItem[]
+  topBrowsers: TopItem[]
+  goals?: GoalPerformance[]
+  realtime?: RealtimeData
+}
+/**
+ * Goal performance data
+ */
+export declare interface GoalPerformance {
+  goalId: string
+  goalName: string
+  conversions: number
+  conversionRate: number
+  revenue: number
+}
+/**
+ * Realtime dashboard data
+ */
+export declare interface RealtimeData {
+  currentVisitors: number
+  pageViewsLastHour: number
+  topActivePages: TopItem[]
+}
+/**
+ * Query options
+ */
+export declare interface QueryOptions {
+  siteId: string
+  dateRange: DateRange
+  includeComparison?: boolean
+  includeRealtime?: boolean
+  includeGoals?: boolean
+  topLimit?: number
+  timezone?: string
+}
+/**
+ * Pipeline job configuration
+ */
+export declare interface PipelineJobConfig {
+  siteId: string
+  period: AggregationPeriod
+  windowStart: Date
+  windowEnd: Date
+  deleteRawEvents?: boolean
+}
+/**
+ * Pipeline job result
+ */
+export declare interface PipelineJobResult {
+  config: PipelineJobConfig
+  success: boolean
+  error?: string
+  pageViewsProcessed: number
+  sessionsProcessed: number
+  eventsProcessed: number
+  conversionsTracked: number
+  commands: Array<{
+    command: string
+    input: Record<string, unknown>
+  }>
+  durationMs: number
+}
+/**
+ * Aggregation job status
+ */
+export declare interface AggregationJobStatus {
+  jobId: string
+  siteId: string
+  period: AggregationPeriod
+  status: 'pending' | 'running' | 'completed' | 'failed'
+  startedAt?: Date
+  completedAt?: Date
+  error?: string
+  progress: number
+}
+/**
+ * Options for generating tracking script
+ */
+export declare interface TrackingScriptOptions {
+  siteId: string
+  apiEndpoint: string
+  honorDnt?: boolean
+  trackHashChanges?: boolean
+  trackOutboundLinks?: boolean
+  trackLinkClicks?: boolean
+  trackSpaRoutes?: boolean
+  trackEngagement?: boolean
+  stealthMode?: boolean
+  trackWebVitals?: boolean
+}
+/**
+ * Analytics Store for DynamoDB
+ */
+export declare class AnalyticsStore {
+  constructor(options: AnalyticsStoreOptions);
+  createSiteCommand(site: Site): {
+    command: 'PutItem'
+    input: {
+      TableName: string
+      Item: Record<string, unknown>
+      ConditionExpression: string
+    }
+  };
+  getSiteCommand(siteId: string): {
+    command: 'GetItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+    }
+  };
+  listSitesByOwnerCommand(ownerId: string): {
+    command: 'Query'
+    input: {
+      TableName: string
+      IndexName: string
+      KeyConditionExpression: string
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  recordPageViewCommand(pageView: PageView): {
+    command: 'PutItem'
+    input: {
+      TableName: string
+      Item: Record<string, unknown>
+    }
+  };
+  queryPageViewsCommand(siteId: string, startDate: Date, endDate: Date, options?: { path?: string, limit?: number }): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeNames: Record<string, string>
+        ExpressionAttributeValues: Record<string, unknown>
+        FilterExpression?: string
+        Limit?: number
+        ScanIndexForward: boolean
+      }
+    };
+  upsertSessionCommand(session: Session): {
+    command: 'PutItem'
+    input: {
+      TableName: string
+      Item: Record<string, unknown>
+    }
+  };
+  recordCustomEventCommand(event: CustomEvent): {
+    command: 'PutItem'
+    input: {
+      TableName: string
+      Item: Record<string, unknown>
+    }
+  };
+  upsertAggregatedStatsCommand(stats: AggregatedStats): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  getAggregatedStatsCommand(siteId: string, period: AggregationPeriod, startPeriod: string, endPeriod: string): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+        ScanIndexForward: boolean
+      }
+    };
+  upsertPageStatsCommand(stats: PageStats): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  getTopPagesCommand(siteId: string, period: AggregationPeriod, periodStart: string, limit?: number): {
+      command: 'Query'
+      input: {
+        TableName: string
+        IndexName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+        Limit: number
+        ScanIndexForward: boolean
+      }
+    };
+  upsertReferrerStatsCommand(stats: ReferrerStats): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  createGoalCommand(goal: Goal): {
+    command: 'PutItem'
+    input: {
+      TableName: string
+      Item: Record<string, unknown>
+      ConditionExpression: string
+    }
+  };
+  listGoalsCommand(siteId: string): {
+    command: 'Query'
+    input: {
+      TableName: string
+      KeyConditionExpression: string
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  updateRealtimeStatsCommand(stats: RealtimeStats & { visitorId?: string }): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  getRealtimeStatsCommand(siteId: string, minutes?: number): {
+    command: 'Query'
+    input: {
+      TableName: string
+      KeyConditionExpression: string
+      ExpressionAttributeValues: Record<string, unknown>
+      ScanIndexForward: boolean
+      Limit: number
+    }
+  };
+  upsertGeoStatsCommand(stats: GeoStats): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  getGeoStatsCommand(siteId: string, period: AggregationPeriod, periodStart: string, limit?: number): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+        Limit: number
+      }
+    };
+  getRegionsCommand(siteId: string, period: AggregationPeriod, periodStart: string, country?: string, limit?: number): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+        FilterExpression?: string
+        ExpressionAttributeNames?: Record<string, string>
+        Limit: number
+      }
+    };
+  getCitiesCommand(siteId: string, period: AggregationPeriod, periodStart: string, options?: { country?: string, region?: string }, limit?: number): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+        FilterExpression?: string
+        ExpressionAttributeNames?: Record<string, string>
+        Limit: number
+      }
+    };
+  upsertDeviceStatsCommand(stats: DeviceStats): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  getDeviceStatsCommand(siteId: string, period: AggregationPeriod, periodStart: string, dimension?: 'device' | 'browser' | 'os' | 'screen'): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+        FilterExpression?: string
+        ExpressionAttributeNames?: Record<string, string>
+      }
+    };
+  upsertEventStatsCommand(stats: EventStats): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  getEventStatsCommand(siteId: string, period: AggregationPeriod, periodStart: string): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+      }
+    };
+  upsertGoalStatsCommand(stats: GoalStats): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  getGoalStatsCommand(siteId: string, goalId: string, period: AggregationPeriod, startPeriod: string, endPeriod: string): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+        ScanIndexForward: boolean
+      }
+    };
+  upsertCampaignStatsCommand(stats: CampaignStats): {
+    command: 'UpdateItem'
+    input: {
+      TableName: string
+      Key: Record<string, unknown>
+      UpdateExpression: string
+      ExpressionAttributeNames: Record<string, string>
+      ExpressionAttributeValues: Record<string, unknown>
+    }
+  };
+  getCampaignStatsCommand(siteId: string, period: AggregationPeriod, periodStart: string): {
+      command: 'Query'
+      input: {
+        TableName: string
+        KeyConditionExpression: string
+        ExpressionAttributeValues: Record<string, unknown>
+      }
+    };
+  static getPeriodStart(date: Date, period: AggregationPeriod): string;
+  static generateId(): string;
+  static hashVisitorId(ip: string, userAgent: string, siteId: string, salt: string): Promise<string>;
+  static parseReferrerSource(referrer: string | undefined): string;
+  static parseUserAgent(userAgent: string): {
+    deviceType: DeviceType
+    browser: string
+    browserVersion: string
+    os: string
+    osVersion: string
+  };
+}
+/**
+ * Analytics Aggregator for rolling up raw events into aggregated stats
+ */
+export declare class AnalyticsAggregator {
+  constructor(options: AggregatorOptions);
+  aggregateHourlyStats(siteId: string, hourStart: Date, pageViews: PageView[], sessions: Session[]): AggregatedStats;
+  aggregatePageStats(siteId: string, period: AggregationPeriod, periodStart: Date, pageViews: PageView[]): PageStats[];
+  aggregateReferrerStats(siteId: string, period: AggregationPeriod, periodStart: Date, sessions: Session[]): ReferrerStats[];
+  aggregateGeoStats(siteId: string, period: AggregationPeriod, periodStart: Date, sessions: Session[]): GeoStats[];
+  aggregateDeviceStats(siteId: string, period: AggregationPeriod, periodStart: Date, sessions: Session[]): DeviceStats[];
+}
+/**
+ * Goal Matcher for checking if pageviews/events match goal definitions
+ */
+export declare class GoalMatcher {
+  constructor(goals: Goal[]);
+  matchPageView(pageView: PageView): GoalMatchResult[];
+  matchEvent(event: CustomEvent): GoalMatchResult[];
+  getActiveGoals(): Goal[];
+  static createConversion(siteId: string, match: GoalMatchResult): Conversion;
+}
+/**
+ * Analytics Query API for dashboard data
+ */
+export declare class AnalyticsQueryAPI {
+  constructor(store: AnalyticsStore);
+  static determinePeriod(dateRange: DateRange): AggregationPeriod;
+  static getPreviousPeriod(dateRange: DateRange): DateRange;
+  generateDashboardQueries(options: QueryOptions): {
+    aggregatedStats: ReturnType<AnalyticsStore['getAggregatedStatsCommand']>
+    topPages: ReturnType<AnalyticsStore['getTopPagesCommand']>
+    realtimeStats?: ReturnType<AnalyticsStore['getRealtimeStatsCommand']>
+    goals?: ReturnType<AnalyticsStore['listGoalsCommand']>
+    previousPeriodStats?: ReturnType<AnalyticsStore['getAggregatedStatsCommand']>
+  };
+  getRegions(siteId: string, options: {
+      dateRange: DateRange
+      country?: string
+      limit?: number
+    }): ReturnType<AnalyticsStore['getRegionsCommand']>;
+  getCities(siteId: string, options: {
+      dateRange: DateRange
+      country?: string
+      region?: string
+      limit?: number
+    }): ReturnType<AnalyticsStore['getCitiesCommand']>;
+  static processSummary(stats: AggregatedStats[], previousStats?: AggregatedStats[]): DashboardSummary;
+  static processTimeSeries(stats: AggregatedStats[]): TimeSeriesPoint[];
+  static processTopPages(pageStats: PageStats[], totalPageViews: number): TopItem[];
+  static processTopReferrers(referrerStats: ReferrerStats[], totalVisitors: number): TopItem[];
+  static processTopCountries(geoStats: GeoStats[], totalVisitors: number): TopItem[];
+  static processTopRegions(geoStats: GeoStats[], totalVisitors: number): TopItem[];
+  static processTopCities(geoStats: GeoStats[], totalVisitors: number): TopItem[];
+  static processTopDevices(deviceStats: DeviceStats[], dimension: 'device' | 'browser' | 'os', totalVisitors: number): TopItem[];
+  static processRealtimeData(realtimeStats: RealtimeStats[]): RealtimeData;
+  static processGoalPerformance(goals: Goal[], goalStats: GoalStats[], totalVisitors: number): GoalPerformance[];
+}
+/**
+ * Aggregation Pipeline for scheduled processing of analytics data
+ */
+export declare class AggregationPipeline {
+  constructor(store: AnalyticsStore, aggregator?: AnalyticsAggregator);
+  runAggregationJob(config: PipelineJobConfig, pageViews: PageView[], sessions: Session[], events: CustomEvent[], goals: Goal[]): PipelineJobResult;
+  static getScheduledJobTimes(now?: Date): {
+    hourly: Date
+    daily: Date
+    monthly: Date
+  };
+  static getCronExpression(period: AggregationPeriod): string;
+  static getAggregationWindow(period: AggregationPeriod, referenceTime?: Date): {
+    start: Date
+    end: Date
+  };
+  static createJobConfig(siteId: string, period: AggregationPeriod, referenceTime?: Date): PipelineJobConfig;
+}

package/dist/api.d.ts

@@ -0,0 +1,109 @@
+import { AggregationPipeline, AnalyticsQueryAPI, AnalyticsStore } from './Analytics';
+import type { Goal, Session, Site } from './Analytics';
+/**
+ * Create a Bun/Hono compatible router handler
+ */
+export declare function createBunRouter(api: AnalyticsAPI, executeCommand: HandlerContext['executeCommand']): void;
+/**
+ * Create AWS Lambda handler
+ */
+export declare function createLambdaHandler(api: AnalyticsAPI, executeCommand: HandlerContext['executeCommand']): (event: {
+  httpMethod: string
+  path: string
+  pathParameters?: Record<string, string>
+  queryStringParameters?: Record<string, string>
+  body?: string
+  headers: Record<string, string>
+  requestContext?: { identity?: { sourceIp?: string } }
+}) => Promise<{ statusCode: number, headers: Record<string, string>, body: string }>;
+/**
+ * Generic HTTP request interface (framework-agnostic)
+ */
+export declare interface AnalyticsRequest {
+  method: string
+  path: string
+  params: Record<string, string>
+  query: Record<string, string>
+  body: unknown
+  headers: Record<string, string>
+  ip?: string
+  userAgent?: string
+}
+/**
+ * Generic HTTP response interface
+ */
+export declare interface AnalyticsResponse {
+  status: number
+  headers: Record<string, string>
+  body: unknown
+}
+/**
+ * API handler context
+ */
+export declare interface HandlerContext {
+  store: AnalyticsStore
+  queryApi: AnalyticsQueryAPI
+  pipeline: AggregationPipeline
+  visitorSalt: string
+  executeCommand: (command: { command: string, input: Record<string, unknown> }) => Promise<unknown>
+  getGoals?: (siteId: string) => Promise<Goal[]>
+  getSite?: (siteId: string) => Promise<Site | null>
+  sessionStore?: SessionStore
+}
+/**
+ * Simple in-memory session store interface
+ */
+export declare interface SessionStore {
+  get: (key: string) => Promise<Session | null>
+  set: (key: string, session: Session, ttlSeconds?: number) => Promise<void>
+  delete: (key: string) => Promise<void>
+}
+/**
+ * Collect endpoint payload (from tracking script)
+ */
+export declare interface CollectPayload {
+  s: string
+  sid: string
+  e: 'pageview' | 'event' | 'outbound' | 'error'
+  p?: Record<string, unknown>
+  u: string
+  r?: string
+  t?: string
+  sw?: number
+  sh?: number
+}
+/**
+ * API configuration
+ */
+export declare interface AnalyticsAPIConfig {
+  tableName: string
+  corsOrigins?: string[]
+  useTtl?: boolean
+  rawEventTtl?: number
+  basePath?: string
+}
+/**
+ * Analytics API - handles all analytics HTTP endpoints
+ */
+export declare class AnalyticsAPI {
+  constructor(config: AnalyticsAPIConfig);
+  createContext(executeCommand: HandlerContext['executeCommand'], options?: Partial<Pick<HandlerContext, 'getGoals' | 'getSite' | 'sessionStore'>>): HandlerContext;
+  getCorsHeaders(origin?: string): Record<string, string>;
+  handleOptions(req: AnalyticsRequest): AnalyticsResponse;
+  handleCollect(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleListSites(req: AnalyticsRequest, ctx: HandlerContext, ownerId: string): Promise<AnalyticsResponse>;
+  handleCreateSite(req: AnalyticsRequest, ctx: HandlerContext, ownerId: string): Promise<AnalyticsResponse>;
+  handleGetSite(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleGetStats(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleGetRealtime(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleGetScript(req: AnalyticsRequest): AnalyticsResponse;
+  handleListGoals(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleCreateGoal(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleGetTopPages(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleGetRegions(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleGetCities(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  handleAggregate(req: AnalyticsRequest, ctx: HandlerContext): Promise<AnalyticsResponse>;
+  getStore(): AnalyticsStore;
+  getQueryAPI(): AnalyticsQueryAPI;
+  getPipeline(): AggregationPipeline;
+}