@stacksjs/ts-analytics 0.1.6

package/src/tracking.ts

@@ -0,0 +1,27 @@
+/**
+ * `@stacksjs/ts-analytics/tracking`
+ *
+ * A dependency-free entry point exposing the backend-agnostic tracking +
+ * privacy primitives, split out from the main barrel so consumers (e.g. the
+ * ghostanalytics app) can use them WITHOUT pulling in the DynamoDB/router/
+ * aggregation graph that the root `@stacksjs/ts-analytics` export carries.
+ *
+ * Everything re-exported here comes from `src/utils/*`, which have no imports.
+ */
+
+export {
+  getBrowserFamily,
+  isBot,
+  type ParsedUserAgent,
+  parseUserAgent,
+} from './utils/user-agent'
+
+export {
+  anonymizeIp,
+  countryCodeOf,
+  countryFlagEmoji,
+  getCountryFromHeaders,
+  getRegionFromHeaders,
+  isSpamReferrer,
+  parseReferrerSource,
+} from './utils/geolocation'

package/src/types/analytics.ts

@@ -0,0 +1,219 @@
+// Core analytics types - extracted from component inline definitions
+
+export interface Goal {
+  id: string
+  name: string
+  type: string
+  pattern?: string
+  matchType?: string
+  durationMinutes?: number
+  value?: number
+  isActive: boolean
+  conversions?: number
+  conversionRate?: number
+}
+
+export interface GoalFormData {
+  name: string
+  type: string
+  pattern: string
+  matchType: string
+  durationMinutes?: number
+  value?: number
+  isActive: boolean
+}
+
+export interface AnalyticsEvent {
+  name: string
+  count?: number
+}
+
+export interface Session {
+  id: string
+  sessionId: string
+  entryPage: string
+  entryPath: string
+  startTime: string
+  startedAt: string
+  pageViews: number
+  pageViewCount: number
+  duration: number
+  bounced: boolean
+  isBounce: boolean
+  browser: string
+  country: string
+}
+
+export interface PageView {
+  path: string
+}
+
+export interface SessionEvent {
+  type: string
+  name: string
+  path: string
+  message: string
+  timestamp: string
+}
+
+export interface SessionDetail {
+  pageViewCount: number
+  pageViews: PageView[]
+  duration: number
+  browser: string
+  country: string
+  events: SessionEvent[]
+}
+
+export interface Funnel {
+  id: string
+  name: string
+  steps: string[]
+}
+
+export interface FunnelAnalysisStep {
+  path: string
+  visitors: number
+  rate: number
+  dropoff: number
+}
+
+export interface FunnelAnalysis {
+  name: string
+  totalVisitors: number
+  conversionRate: number
+  steps: FunnelAnalysisStep[]
+}
+
+export interface Vital {
+  metric: string
+  p75: number
+  samples: number
+  good: number
+  needsImprovement: number
+  poor: number
+}
+
+export interface BudgetViolation {
+  metric: string
+  currentValue: number
+  threshold: number
+  exceededBy: number
+}
+
+export interface FlowPage {
+  path: string
+  count: number
+}
+
+export interface FlowLink {
+  source: string
+  target: string
+  count: number
+}
+
+export interface FlowData {
+  entryPages: FlowPage[]
+  flows: FlowLink[]
+  mostVisited: FlowPage[]
+  totalSessions: number
+  uniquePaths: number
+}
+
+export interface LiveActivity {
+  path: string
+  country: string
+  device: string
+  browser: string
+  timestamp: string
+}
+
+export interface Insight {
+  title: string
+  description: string
+  type: string
+  severity: string
+}
+
+export interface ComparisonPeriodStats {
+  visitors: number
+  views: number
+  sessions: number
+  bounceRate: number
+  avgDuration: number
+}
+
+/** Shape returned by GET /comparison: the selected range vs the period before. */
+export interface ComparisonStats {
+  current: ComparisonPeriodStats
+  previous: ComparisonPeriodStats
+  /** Percentage change (current vs previous) per metric. */
+  changes: ComparisonPeriodStats
+  periods?: {
+    current: { start: string, end: string }
+    previous: { start: string, end: string }
+  }
+}
+
+export interface Referrer {
+  name: string
+  source?: string
+  visitors: number
+  views?: number
+  favicon?: string
+}
+
+// Settings types
+export interface ApiKey {
+  name: string
+  key: string
+}
+
+export interface Alert {
+  id: string
+  metric: string
+  threshold: number
+  email: string
+}
+
+export interface EmailReport {
+  id: string
+  email: string
+  frequency: string
+}
+
+export interface UptimeMonitor {
+  id: string
+  url: string
+  interval: number
+  status: string
+}
+
+export interface TeamMember {
+  id: string
+  email: string
+  role: string
+}
+
+export interface Webhook {
+  id: string
+  url: string
+  events: string[]
+}
+
+export interface PerfBudget {
+  id: string
+  metric: string
+  threshold: number
+}
+
+export interface SiteSettings {
+  apiKey: ApiKey | null
+  alerts: Alert[]
+  emailReports: EmailReport[]
+  uptimeMonitors: UptimeMonitor[]
+  teamMembers: TeamMember[]
+  webhooks: Webhook[]
+  perfBudgets: PerfBudget[]
+  retentionDays: number
+}

package/src/types/api.ts

@@ -0,0 +1,75 @@
+// API response types - inferred from dashboard fetch calls
+
+import type { Goal, AnalyticsEvent, Session, Funnel, Vital, BudgetViolation, FlowData, LiveActivity, Insight, ComparisonStats, Referrer, ApiKey, Alert, EmailReport, UptimeMonitor, TeamMember, Webhook, PerfBudget } from './analytics'
+
+export interface GoalsResponse {
+  goals?: Goal[]
+}
+
+export interface EventsResponse {
+  events?: AnalyticsEvent[]
+}
+
+export interface SessionsResponse {
+  sessions?: Session[]
+}
+
+export interface FunnelsResponse {
+  funnels?: Funnel[]
+}
+
+export interface VitalsResponse {
+  vitals?: Vital[]
+}
+
+export interface BudgetViolationsResponse {
+  violations?: BudgetViolation[]
+}
+
+export interface FlowResponse extends FlowData {}
+
+export interface LiveResponse {
+  activities?: LiveActivity[]
+}
+
+export interface InsightsResponse {
+  insights?: Insight[]
+}
+
+export interface ComparisonResponse extends ComparisonStats {}
+
+export interface ReferrersResponse {
+  referrers?: Referrer[]
+}
+
+export interface ApiKeysResponse {
+  apiKey?: ApiKey
+}
+
+export interface AlertsResponse {
+  alerts?: Alert[]
+}
+
+export interface EmailReportsResponse {
+  reports?: EmailReport[]
+}
+
+export interface UptimeResponse {
+  monitors?: UptimeMonitor[]
+}
+
+export interface TeamResponse {
+  members?: TeamMember[]
+}
+
+export interface WebhooksResponse {
+  webhooks?: Webhook[]
+}
+
+export interface PerfBudgetsResponse {
+  budgets?: PerfBudget[]
+}
+
+export interface RetentionResponse {
+  days?: number
+}

package/src/types/bun-router.d.ts

@@ -0,0 +1,15 @@
+declare module '@stacksjs/bun-router' {
+  export class Router {
+    constructor(_options?: any)
+    get(_path: string, _handler: any): Promise<any>
+    post(_path: string, _handler: any): Promise<any>
+    put(_path: string, _handler: any): Promise<any>
+    delete(_path: string, _handler: any): Promise<any>
+    patch(_path: string, _handler: any): Promise<any>
+    start(_options?: any): Promise<any>
+    handleRequest(_request: Request): Promise<Response>
+    [key: string]: any
+  }
+
+  export function injectQueryPreservationScript(_html: string, _config: any): string
+}

package/src/types/dashboard.ts

@@ -0,0 +1,62 @@
+// Dashboard UI types - extracted from component inline definitions
+
+export interface ModalOptions {
+  title?: string
+  content?: string
+  size?: string
+  className?: string
+  showFooter?: boolean
+  submitText?: string
+  cancelText?: string
+  onSubmit?: (() => Promise<void>) | null
+  onCancel?: (() => void) | null
+}
+
+export interface ModalAPI {
+  open: (options?: ModalOptions) => void
+  close: () => void
+  handleSubmit: () => Promise<void>
+  getFormData: () => Record<string, string | boolean>
+  confirm: (message: string, onConfirm: () => Promise<void>) => void
+  alert: (title: string, message: string) => void
+}
+
+export interface GoalModalAPI {
+  openCreate: () => void
+  openEdit: (goal: any) => void
+  close: () => void
+}
+
+export interface NavTab {
+  id: string
+  label: string
+  href: string
+}
+
+export interface DashboardHeaderAPI {
+  toggleTheme: () => void
+  goBack: () => void
+  isDarkTheme: () => boolean
+}
+
+export interface DateRange {
+  id: string
+  label: string
+}
+
+export interface ControlsBarAPI {
+  activeRange: () => string
+  showComparison: () => boolean
+  realtimeCount: () => number
+  lastUpdated: () => string
+  isRefreshing: () => boolean
+  setRange: (range: string) => void
+  toggleComparison: () => void
+  refresh: () => Promise<void>
+  exportData: (format: string) => void
+}
+
+export interface ReferrersTableProps {
+  referrers?: import('./analytics').Referrer[]
+  loading?: boolean
+}

package/src/types/index.ts

@@ -0,0 +1,66 @@
+// Barrel export for all shared types
+export type {
+  // Analytics types
+  Goal,
+  GoalFormData,
+  AnalyticsEvent,
+  Session,
+  PageView,
+  SessionEvent,
+  SessionDetail,
+  Funnel,
+  FunnelAnalysisStep,
+  FunnelAnalysis,
+  Vital,
+  BudgetViolation,
+  FlowPage,
+  FlowLink,
+  FlowData,
+  LiveActivity,
+  Insight,
+  ComparisonStats,
+  Referrer,
+  ApiKey,
+  Alert,
+  EmailReport,
+  UptimeMonitor,
+  TeamMember,
+  Webhook,
+  PerfBudget,
+  SiteSettings,
+} from './analytics'
+
+export type {
+  // Dashboard UI types
+  ModalOptions,
+  ModalAPI,
+  GoalModalAPI,
+  NavTab,
+  DashboardHeaderAPI,
+  DateRange,
+  ControlsBarAPI,
+  ReferrersTableProps,
+} from './dashboard'
+
+export type {
+  // API response types
+  GoalsResponse,
+  EventsResponse,
+  SessionsResponse,
+  FunnelsResponse,
+  VitalsResponse,
+  BudgetViolationsResponse,
+  FlowResponse,
+  LiveResponse,
+  InsightsResponse,
+  ComparisonResponse,
+  ReferrersResponse,
+  ApiKeysResponse,
+  AlertsResponse,
+  EmailReportsResponse,
+  UptimeResponse,
+  TeamResponse,
+  WebhooksResponse,
+  PerfBudgetsResponse,
+  RetentionResponse,
+} from './api'

package/src/types/stx.d.ts

@@ -0,0 +1,27 @@
+declare module '@stacksjs/stx' {
+  export function processDirectives(
+    _template: string,
+    _context: Record<string, unknown>,
+    _templatePath: string,
+    _config: any,
+    _seen: Set<string>,
+  ): Promise<string>
+
+  export function extractVariables(
+    _script: string,
+    _context: Record<string, unknown>,
+    _templatePath: string,
+  ): Promise<void>
+
+  export function buildViews(_options?: any): Promise<void>
+
+  export const defaultConfig: Record<string, any>
+
+  export function createRoute(
+    _handler: (request: Request) => Response | Promise<Response>,
+  ): (request: Request) => Response | Promise<Response>
+
+  export function createMiddleware(_options?: any): any
+
+  export function readMarkdownFile(_path: string): any
+}

package/src/types/window.d.ts

@@ -0,0 +1,101 @@
+// Window interface augmentation - eliminates (window as any) casts
+
+import type { ModalAPI, GoalModalAPI, DashboardHeaderAPI, ControlsBarAPI } from './dashboard'
+
+export {}
+
+declare global {
+  interface Window {
+    // Site configuration (set by dashboard.ts / layout scripts)
+    siteId: string | undefined
+    API_ENDPOINT: string
+    ANALYTICS_API: string
+    ANALYTICS_API_ENDPOINT: string
+    ANALYTICS_SITE_ID: string
+    ANALYTICS_STEALTH_MODE: boolean
+    USE_STEALTH: boolean
+
+    // API helpers (set by dashboard.ts)
+    apiPath: (url: string) => string
+    getDateRangeParams: () => string
+
+    // Dashboard controller functions (set by dashboard.ts)
+    fetchDashboardData: (() => Promise<void>) | undefined
+    refreshAllPanels: (() => void) | undefined
+    setDateRange: ((_range: string) => void) | undefined
+    toggleComparison: (() => void) | undefined
+    exportData: ((_format: string) => void) | undefined
+    dateRange: string | undefined
+    navigateTo: ((_tab: string) => void) | undefined
+    applyFilter: ((_type: string, _value: string) => void) | undefined
+
+    // Panel refresh functions (set by individual panels)
+    refreshGoalsPanel: (() => void) | undefined
+    refreshEventsPanel: (() => void) | undefined
+    refreshPagesPanel: (() => void) | undefined
+    refreshReferrersPanel: (() => void) | undefined
+    refreshCountriesPanel: (() => void) | undefined
+    refreshBrowsersPanel: (() => void) | undefined
+    refreshDevicesPanel: (() => void) | undefined
+    refreshCampaignsPanel: (() => void) | undefined
+
+    // Component APIs (set via provide/inject and window exposure)
+    goalModal: GoalModalAPI | undefined
+    Modal: ModalAPI | undefined
+    dashboardHeader: DashboardHeaderAPI | undefined
+    controlsBar: ControlsBarAPI | undefined
+
+    // Header bridge functions
+    headerSetSiteName: ((_name: string) => void) | undefined
+    toggleTheme: (() => void) | undefined
+    goBack: (() => void) | undefined
+
+    // Controls bar bridge functions
+    updateRealtimeCount: ((_count: number) => void) | undefined
+    updateLastUpdated: ((_time: string) => void) | undefined
+    controlsSetDateRange: ((_range: string) => void) | undefined
+
+    // Filter bar functions
+    setFilterCountries: ((_countries: string[]) => void) | undefined
+    setFilterBrowsers: ((_browsers: string[]) => void) | undefined
+    getFilterParams: (() => string) | undefined
+    resetFilters: (() => void) | undefined
+
+    // FunnelsTab window globals (for modal innerHTML onclick)
+    __addFunnelStep: (() => void) | undefined
+    __removeFunnelStep: ((_index: number) => void) | undefined
+
+    // Legacy goal modal functions (dashboard.ts)
+    showEditGoalModal: ((_goalId: string) => void) | undefined
+    confirmDeleteGoal: ((_goalId: string) => void) | undefined
+
+    // Annotation
+    addAnnotation: (() => void) | undefined
+
+    // Modal close (SessionModal)
+    closeModal: (() => void) | undefined
+
+    // STX runtime
+    stx: {
+      state: <T>(initial: T) => { (): T; set: (v: T) => void; update: (fn: (v: T) => T) => void }
+      derived: <T>(fn: () => T) => () => T
+      effect: (fn: () => void | (() => void)) => void
+      mount: (el: Element, fn: () => void) => void
+      [key: string]: any
+    }
+    stxRouter: { navigate: (url: string) => void; clearCache: () => void }
+    stxLoading: { start: () => void; finish: () => void; show: () => void; hide: () => void }
+    STX_ROUTER_OPTIONS: Record<string, any>
+
+    // Composables registry
+    __composables: {
+      useSiteApi: () => any
+      useFetchData: (initialValue?: any) => any
+      useFetchMultiple: () => any
+      useModal: () => any
+    }
+
+    // Tracking script
+    sa: ((..._args: any[]) => void) & { q?: any[][] }
+  }
+}