core

@pulsekit/core

Core analytics queries, types, and SQL migrations for PulseKit.

Installation

npm install @pulsekit/core

Peer dependency: @supabase/supabase-js >= 2.0.0

What's Included

Query Functions

Functions that fetch analytics data from Supabase via RPC:

• getPulseStats(supabase, options) — Page views, top pages, visitor locations, and daily traffic
• getPulseVitals(supabase, options) — Web Vitals metrics (LCP, FID, CLS, etc.)
• getPulseErrors(supabase, options) — Client and server error tracking data
• getPulseAggregates(supabase, options) — Pre-aggregated stats for KPI summaries
• dateRangeFromTimeframe(timeframe) — Convert a named timeframe (e.g. "7d", "30d") to a date range

Types

Core TypeScript types used across all PulseKit packages:

import type {
  PulseEventType,
  PulseEventPayload,
  PulseStats,
  Timeframe,
  DailyStat,
  TopPageStat,
  LocationStat,
  WebVitalStat,
  VitalsOverview,
  ErrorStat,
  ErrorsOverview,
  AggregateRow,
  AggregatesOverview,
} from "@pulsekit/core";

SQL Migrations

The sql/ directory contains Supabase migration files that set up the required database schema:

File	Purpose
001_init_pulse.sql	Base pulse_events table and RPC functions
002_aggregation_function.sql	Aggregation queries
003_geo_and_timezone.sql	Geolocation and timezone support
004_web_vitals.sql	Web Vitals storage and queries
005_error_tracking.sql	Error tracking tables and queries
006_date_range_support.sql	Date range filtering
007_data_lifecycle.sql	Data retention and cleanup

Copy these into your Supabase migrations directory and run npx supabase db push.

License

MIT