@stacksjs/ts-analytics 0.1.6

package/dist/dashboard/types/index.d.ts

@@ -0,0 +1,144 @@
+export declare const defaultTheme: DashboardTheme;
+export declare const darkTheme: DashboardTheme;
+/**
+ * Analytics Dashboard Types
+ */
+// ============================================================================
+// Dashboard Data Types
+// ============================================================================
+export declare interface DashboardStats {
+  pageViews: number
+  uniqueVisitors: number
+  sessions: number
+  bounceRate: number
+  avgSessionDuration: number
+  avgPagesPerSession: number
+}
+export declare interface StatsChange {
+  pageViews: number
+  uniqueVisitors: number
+  sessions: number
+  bounceRate: number
+  avgSessionDuration: number
+}
+export declare interface DashboardSummary extends DashboardStats {
+  change?: StatsChange
+}
+export declare interface TimeSeriesDataPoint {
+  date: string
+  pageViews: number
+  uniqueVisitors: number
+  sessions: number
+}
+export declare interface TopItem {
+  name: string
+  value: number
+  percentage: number
+  change?: number
+}
+export declare interface RealtimeData {
+  currentVisitors: number
+  pageViewsLastHour: number
+  topActivePages: TopItem[]
+}
+export declare interface DeviceBreakdown {
+  desktop: number
+  mobile: number
+  tablet: number
+}
+export declare interface BrowserStats {
+  name: string
+  visitors: number
+  percentage: number
+}
+export declare interface CountryStats {
+  country: string
+  countryCode: string
+  visitors: number
+  percentage: number
+}
+export declare interface GoalConversion {
+  goalId: string
+  goalName: string
+  conversions: number
+  conversionRate: number
+  revenue: number
+}
+// ============================================================================
+// Component Props Types
+// ============================================================================
+export declare interface StatCardProps {
+  title: string
+  value: number | string
+  change?: number
+  changeLabel?: string
+  icon?: string
+  format?: 'number' | 'percentage' | 'duration' | 'currency'
+  loading?: boolean
+}
+export declare interface TopListProps {
+  title: string
+  items: TopItem[]
+  loading?: boolean
+  showPercentage?: boolean
+  maxItems?: number
+  emptyMessage?: string
+}
+export declare interface ChartProps {
+  data: TimeSeriesDataPoint[]
+  loading?: boolean
+  height?: number
+  showLegend?: boolean
+  metrics?: Array<'pageViews' | 'uniqueVisitors' | 'sessions'>
+}
+export declare interface RealtimeCounterProps {
+  count: number
+  label?: string
+  pulseColor?: string
+  loading?: boolean
+}
+export declare interface DateRangeOption {
+  label: string
+  value: string
+  days: number
+}
+export declare interface DateRange {
+  start: Date
+  end: Date
+  preset?: string
+}
+// ============================================================================
+// API Types
+// ============================================================================
+export declare interface AnalyticsApiConfig {
+  baseUrl: string
+  siteId: string
+  headers?: Record<string, string>
+}
+export declare interface FetchOptions {
+  startDate?: Date
+  endDate?: Date
+  period?: 'hour' | 'day' | 'month'
+  limit?: number
+}
+// ============================================================================
+// Theme Types
+// ============================================================================
+export declare interface DashboardTheme {
+  primary: string
+  secondary: string
+  success: string
+  warning: string
+  danger: string
+  background: string
+  surface: string
+  text: string
+  textSecondary: string
+  border: string
+  chart: {
+    pageViews: string
+    visitors: string
+    sessions: string
+    grid: string
+  }
+}

package/dist/dashboard/utils/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Format a number with locale-aware separators
+ */
+export declare function formatNumber(value: number, decimals?: number): string;
+/**
+ * Format a number as compact (1.2K, 3.4M, etc.)
+ */
+export declare function formatCompact(value: number): string;
+/**
+ * Format a percentage
+ */
+export declare function formatPercentage(value: number, decimals?: number): string;
+/**
+ * Format duration in milliseconds to human-readable string
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Format currency
+ */
+export declare function formatCurrency(value: number, currency?: string): string;
+/**
+ * Format a change percentage with + or - sign
+ */
+export declare function formatChange(value: number): string;
+/**
+ * Format date for display
+ */
+export declare function formatDate(date: Date | string, format?: 'short' | 'long' | 'time'): string;
+/**
+ * Format date range for display
+ */
+export declare function formatDateRange(start: Date, end: Date): string;
+/**
+ * Get relative time string (e.g., "2 hours ago")
+ */
+export declare function getRelativeTime(date: Date | string): string;
+/**
+ * Get date range from preset value
+ */
+export declare function getDateRangeFromPreset(preset: string): { start: Date, end: Date } | null;
+/**
+ * Generate chart gradient
+ */
+export declare function createChartGradient(ctx: CanvasRenderingContext2D, color: string, height: number): CanvasGradient;
+/**
+ * Calculate nice axis ticks
+ */
+export declare function calculateAxisTicks(min: number, max: number, count?: number): number[];
+/**
+ * Calculate percentage change between two values
+ */
+export declare function calculateChange(current: number, previous: number): number;
+/**
+ * Aggregate time series data by period
+ */
+export declare function aggregateTimeSeries<T extends { date: string }>(data: T[], period: 'hour' | 'day' | 'week' | 'month', aggregator: (items: T[]) => Omit<T, 'date'>): T[];
+/**
+ * Fill missing dates in time series
+ */
+export declare function fillMissingDates<T extends { date: string }>(data: T[], startDate: Date, endDate: Date, defaultValue: Omit<T, 'date'>): T[];
+/**
+ * Convert hex to RGB
+ */
+export declare function hexToRgb(hex: string): { r: number, g: number, b: number } | null;
+/**
+ * Add alpha to hex color
+ */
+export declare function hexWithAlpha(hex: string, alpha: number): string;
+/**
+ * Generate color palette for charts
+ */
+export declare function generateColorPalette(baseColor: string, count: number): string[];
+export declare const dateRangePresets: DateRangePreset[];
+// ============================================================================
+// Date Range Helpers
+// ============================================================================
+export declare interface DateRangePreset {
+  label: string
+  value: string
+  getRange: () => { start: Date, end: Date }
+}

package/dist/dynamodb.d.ts

@@ -0,0 +1,86 @@
+import type { AggregationPeriod, AnalyticsEntityType } from './types';
+import type { AnalyticsConfig } from './config';
+/**
+ * Build a partition key for an analytics entity
+ */
+export declare function buildPK(entityType: AnalyticsEntityType, id: string): string;
+/**
+ * Build a sort key for an analytics entity
+ */
+export declare function buildSK(entityType: AnalyticsEntityType, ...parts: string[]): string;
+/**
+ * Build a composite key with timestamp
+ */
+export declare function buildTimestampKey(prefix: string, timestamp: Date, id?: string): string;
+/**
+ * Build GSI1 partition key
+ */
+export declare function buildGSI1PK(siteId: string, dimension: string, value: string): string;
+/**
+ * Build period-based sort key for aggregates
+ */
+export declare function buildPeriodSK(prefix: string, period: AggregationPeriod, periodStart: string, ...additionalParts: string[]): string;
+/**
+ * Convert a JavaScript value to DynamoDB AttributeValue
+ */
+export declare function toDynamoValue(value: unknown): Record<string, unknown>;
+/**
+ * Convert DynamoDB AttributeValue to JavaScript value
+ */
+export declare function fromDynamoValue(attr: Record<string, unknown>): unknown;
+/**
+ * Marshal a JavaScript object to DynamoDB Item
+ */
+export declare function marshal(obj: Record<string, unknown>): Record<string, Record<string, unknown>>;
+/**
+ * Unmarshal a DynamoDB Item to JavaScript object
+ */
+export declare function unmarshal(item: Record<string, Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Build a query for items by site and sort key prefix
+ */
+export declare function buildSiteQuery(siteId: string, skPrefix: string, config?: AnalyticsConfig): {
+  TableName: string
+  KeyConditionExpression: string
+  ExpressionAttributeValues: Record<string, Record<string, string>>
+};
+/**
+ * Build a query for items in a time range
+ */
+export declare function buildTimeRangeQuery(siteId: string, skPrefix: string, startTime: Date, endTime: Date, config?: AnalyticsConfig): {
+  TableName: string
+  KeyConditionExpression: string
+  ExpressionAttributeValues: Record<string, Record<string, string>>
+};
+/**
+ * Generate a unique ID (ULID-like)
+ */
+export declare function generateId(): string;
+/**
+ * Generate a session ID
+ */
+export declare function generateSessionId(): string;
+/**
+ * Hash a visitor ID for privacy
+ */
+export declare function hashVisitorId(ip: string, userAgent: string, siteId: string, salt: string): Promise<string>;
+/**
+ * Get the start of a period
+ */
+export declare function getPeriodStart(date: Date, period: AggregationPeriod): string;
+/**
+ * Get the appropriate period for a date range
+ */
+export declare function determinePeriod(startDate: Date, endDate: Date): AggregationPeriod;
+/**
+ * Analytics key patterns for single-table design
+ */
+export declare const KeyPatterns: ({
+  site: {
+    pk: (siteId: string)) => string;
+/**
+ * Get daily salt for visitor ID hashing (rotates daily for privacy).
+ * Secret-seeded so visitor hashes cannot be reproduced without the server
+ * secret (#88) — see src/lib/salt.ts.
+ */
+export { getDailySalt, getSharedDailySalt } from './lib/salt';

package/dist/funnels.d.ts

@@ -0,0 +1,104 @@
+import type { CustomEvent, PageView, Session } from './types';
+/*' })
+ *   .step('add_to_cart', 'Add to Cart', { eventName: 'add_to_cart' })
+ *   .step('checkout', 'Checkout', { path: '/checkout' })
+ *   .step('purchase', 'Purchase', { eventName: 'purchase' })
+ *   .window(30 * 60 * 1000) // 30 minutes
+ *   .build()
+ * ```
+ */
+export declare function createFunnel(id: string): FunnelBuilder;
+/**
+ * Calculate drop-off rate between two steps
+ */
+export declare function calculateDropOffRate(stepACount: number, stepBCount: number): number;
+/**
+ * Format funnel analysis as a simple report
+ */
+export declare function formatFunnelReport(analysis: FunnelAnalysis): string;
+/**
+ * Identify common drop-off points
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+export declare function identifyDropOffPoints(analysis: FunnelAnalysis): Array<{
+  step: FunnelStep
+  dropOffRate: number
+  impact: number // How much this affects overall conversion
+}>;
+/**
+ * Common e-commerce checkout funnel
+ */
+export declare const ecommerceCheckoutFunnel: Funnel;
+/**
+ * SaaS signup funnel
+ */
+export declare const saasSignupFunnel: Funnel;
+/**
+ * Content engagement funnel
+ */
+export declare const contentEngagementFunnel: Funnel;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface FunnelStep {
+  id: string
+  name: string
+  match: FunnelStepMatcher
+}
+export declare interface FunnelStepMatcher {
+  path?: string
+  eventName?: string
+  eventCategory?: string
+  custom?: (event: PageView | CustomEvent) => boolean
+}
+export declare interface Funnel {
+  id: string
+  name: string
+  steps: FunnelStep[]
+  windowMs?: number
+}
+export declare interface FunnelAnalysis {
+  funnel: Funnel
+  dateRange: {
+    start: Date
+    end: Date
+  }
+  totalEntries: number
+  completions: number
+  conversionRate: number
+  steps: FunnelStepAnalysis[]
+  avgCompletionTimeMs?: number
+}
+export declare interface FunnelStepAnalysis {
+  step: FunnelStep
+  reached: number
+  droppedOff: number
+  conversionFromPrevious: number
+  conversionFromStart: number
+  avgTimeOnStepMs?: number
+}
+export declare interface UserJourney {
+  visitorId: string
+  sessionId: string
+  stepsCompleted: number
+  totalSteps: number
+  completed: boolean
+  stepTimestamps: Date[]
+  completionTimeMs?: number
+  dropOffStep?: string
+}
+declare class FunnelBuilder {
+  constructor(id: string);
+  name(name: string): this;
+  step(id: string, name: string, match: FunnelStepMatcher): this;
+  window(windowMs: number): this;
+  build(): Funnel;
+}
+/**
+ * Analyze funnel performance from event data
+ */
+export declare class FunnelAnalyzer {
+  constructor(funnel: Funnel);
+  analyze(pageViews: PageView[], events: CustomEvent[], sessions: Session[]): FunnelAnalysis;
+  getJourneys(pageViews: PageView[], events: CustomEvent[]): UserJourney[];
+}

package/dist/geolocation.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Cloudflare headers provider - uses CF-* headers from Cloudflare
+ */
+export declare function createCloudflareProvider(): GeoProvider;
+/**
+ * MaxMind GeoLite2 provider
+ * Requires maxmind package and GeoLite2-City.mmdb database
+ */
+export declare function createMaxMindProvider(databasePath?: string): GeoProvider;
+/**
+ * IP-API.com free provider (limited to 45 req/min)
+ */
+export declare function createIpApiProvider(): GeoProvider;
+/**
+ * Cloudflare request headers extractor
+ */
+export declare function extractCloudflareGeo(headers: Record<string, string>): IPGeoResult | null;
+/**
+ * Vercel request headers extractor
+ */
+export declare function extractVercelGeo(headers: Record<string, string>): IPGeoResult | null;
+/**
+ * Get or create default geolocation service
+ */
+export declare function getGeolocationService(config?: GeoServiceConfig): GeolocationService;
+/**
+ * Lookup IP address using default service
+ */
+export declare function lookupIP(ip: string): Promise<IPGeoResult | null>;
+/**
+ * Lookup from request headers using default service
+ */
+export declare function lookupFromHeaders(headers: Record<string, string>): Promise<IPGeoResult | null>;
+/**
+ * Format location for display
+ */
+export declare function formatGeoLocation(result: IPGeoResult): string;
+/**
+ * Format short location (City, State/Region)
+ */
+export declare function formatGeoLocationShort(result: IPGeoResult): string;
+/**
+ * IP geolocation result
+ */
+export declare interface IPGeoResult {
+  ip: string
+  countryCode: string
+  country: string
+  regionCode?: string
+  region?: string
+  city?: string
+  metro?: string
+  postalCode?: string
+  latitude?: number
+  longitude?: number
+  timezone?: string
+  accuracyRadius?: number
+  isp?: string
+  organization?: string
+  asn?: number
+}
+/**
+ * Geolocation provider interface
+ */
+export declare interface GeoProvider {
+  name: string
+  lookup: (ip: string) => Promise<IPGeoResult | null>
+}
+/**
+ * Geolocation service configuration
+ */
+export declare interface GeoServiceConfig {
+  provider?: GeoProvider
+  fallbackProviders?: GeoProvider[]
+  cacheTtlSeconds?: number
+  enableCache?: boolean
+  privacyMode?: boolean
+}
+/**
+ * IP Geolocation Module
+ *
+ * Provides IP-to-location resolution for analytics tracking.
+ * Uses ts-countries for geographic data enrichment.
+ */
+// ts-countries loaded dynamically
+export type GeoLocation = any;
+/**
+ * Main geolocation service
+ */
+export declare class GeolocationService {
+  constructor(config?: GeoServiceConfig);
+  lookup(ip: string): Promise<IPGeoResult | null>;
+  lookupFromHeaders(headers: Record<string, string>): Promise<IPGeoResult | null>;
+  clearCache(): void;
+  getCacheStats(): { size: number, hitRate: number };
+}