create-pulsekit 0.0.2 → 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/benoiteom/pulse-analytics/main/assets/logo.svg" alt="PulseKit" width="200" />
+</p>
+
+# create-pulsekit
+
+CLI scaffolding tool for setting up [PulseKit](https://github.com/benoiteom/pulse-analytics) analytics in a Next.js project.
+
+## Usage
+
+Run in the root of an existing Next.js project:
+
+```bash
+npx create-pulsekit
+```
+
+## What It Does
+
+1. **Detects** your package manager (npm, yarn, pnpm, bun)
+2. **Validates** that you're in a Next.js project
+3. **Installs** `@pulsekit/core`, `@pulsekit/next`, and `@pulsekit/react`
+4. **Scaffolds** the analytics dashboard page and API routes
+5. **Injects** the `<PulseTracker />` component into your root layout
+6. **Injects** the error instrumentation for server-side error tracking
+7. **Writes** the Supabase SQL migration file
+
+## After Setup
+
+1. Add your Supabase credentials to `.env.local`:
+   ```
+   NEXT_PUBLIC_SUPABASE_URL=<your-supabase-url>
+   NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<your-anon-key>
+   ```
+2. Link and push the database migration:
+   ```bash
+   npx supabase link
+   npx supabase db push
+   ```
+3. Start your dev server and visit `/admin/analytics`
+
+## License
+
+MIT

package/dist/index.js

@@ -75,7 +75,7 @@ var PACKAGES = [
   "@pulsekit/core",
   "@pulsekit/next",
   "@pulsekit/react",
-  "@supabase/supabase-js"
+  "@supabase/supabase-js@latest"
 ];
 async function installPackages(pm) {
   console.log("  Installing packages...\n");
@@ -130,16 +130,29 @@ const supabase = createClient(
 
 export const POST = createRefreshHandler({ supabase });
 `;
-  const dashboardPage = `import { createClient } from "@supabase/supabase-js";
+  const consolidateRoute = `import { createConsolidateHandler } from "@pulsekit/next";
+import { createClient } from "@supabase/supabase-js";
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
+);
+
+export const POST = createConsolidateHandler({ supabase });
+`;
+  const dashboardPage = `import { Suspense } from "react";
+import { createClient } from "@supabase/supabase-js";
 import { PulseDashboard } from "@pulsekit/react";
 import { getPulseTimezone } from "@pulsekit/next";
+import { Spinner } from "@/components/ui/spinner";
+import "@pulsekit/react/pulse.css";
 
 const supabase = createClient(
   process.env.NEXT_PUBLIC_SUPABASE_URL!,
   process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
 );
 
-export default async function AnalyticsPage() {
+async function Dashboard() {
   const timezone = await getPulseTimezone();
 
   return (
@@ -151,10 +164,45 @@ export default async function AnalyticsPage() {
     />
   );
 }
+
+export default function AnalyticsPage() {
+  return (
+    <Suspense fallback={<div className="flex items-center justify-center min-h-screen p-6"><Spinner className="size-6" /></div>}>
+      <Dashboard />
+    </Suspense>
+  );
+}
+`;
+  const spinnerContent = `import { LoaderIcon } from "lucide-react"
+import { cn } from "@/lib/utils"
+
+function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
+  return (
+    <LoaderIcon
+      role="status"
+      aria-label="Loading"
+      className={cn("size-4 animate-spin", className)}
+      {...props}
+    />
+  )
+}
+
+export { Spinner }
 `;
+  const cwd = process.cwd();
+  const componentsBase = appDir.includes(import_node_path2.default.join("src", "app")) ? import_node_path2.default.join(cwd, "src", "components", "ui") : import_node_path2.default.join(cwd, "components", "ui");
+  const spinnerPath = import_node_path2.default.join(componentsBase, "spinner.tsx");
+  import_node_fs2.default.mkdirSync(componentsBase, { recursive: true });
+  if (import_node_fs2.default.existsSync(spinnerPath)) {
+    console.log("    Skipped (already exists): components/ui/spinner.tsx");
+  } else {
+    import_node_fs2.default.writeFileSync(spinnerPath, spinnerContent, "utf8");
+    console.log("    Created: components/ui/spinner.tsx");
+  }
   const files = [
     { rel: "api/pulse/route.ts", content: pulseRoute },
     { rel: "api/pulse/refresh-aggregates/route.ts", content: refreshRoute },
+    { rel: "api/pulse/consolidate/route.ts", content: consolidateRoute },
     { rel: "admin/analytics/page.tsx", content: dashboardPage }
   ];
   for (const { rel, content } of files) {
@@ -218,7 +266,7 @@ async function injectPulseTracker() {
   const indent = content.slice(lineStart, bodyCloseIndex).match(/^\s*/)?.[0] ?? "        ";
   const trackerJsx = `${indent}  <PulseTracker excludePaths={["/admin/analytics"]} />
 `;
-  content = content.slice(0, bodyCloseIndex) + trackerJsx + content.slice(bodyCloseIndex);
+  content = content.slice(0, lineStart) + trackerJsx + content.slice(lineStart);
   import_node_fs3.default.writeFileSync(foundPath, content, "utf8");
   console.log(
     `    Modified: ${import_node_path3.default.relative(process.cwd(), foundPath)}
@@ -237,27 +285,102 @@ function printManualInstructions() {
   );
 }
 
-// src/migration.ts
+// src/inject-instrumentation.ts
 var import_node_fs4 = __toESM(require("fs"));
 var import_node_path4 = __toESM(require("path"));
+var FULL_CONTENT = `import { createClient } from "@supabase/supabase-js";
+import { createPulseErrorReporter } from "@pulsekit/next";
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
+);
+
+export const onRequestError = createPulseErrorReporter({
+  supabase,
+  siteId: "default",
+});
+`;
+var IMPORT_LINE = 'import { createPulseErrorReporter } from "@pulsekit/next";';
+var EXPORT_BLOCK = `
+export const onRequestError = createPulseErrorReporter({
+  supabase,
+  siteId: "default",
+});
+`;
+async function injectInstrumentation() {
+  console.log("  Setting up error reporting instrumentation...\n");
+  const appDir = getAppDir();
+  const useSrc = appDir.includes(import_node_path4.default.join("src", "app"));
+  const baseDir = useSrc ? import_node_path4.default.join(process.cwd(), "src") : process.cwd();
+  const candidates = [
+    import_node_path4.default.join(baseDir, "instrumentation.ts"),
+    import_node_path4.default.join(baseDir, "instrumentation.js")
+  ];
+  let foundPath = null;
+  for (const candidate of candidates) {
+    if (import_node_fs4.default.existsSync(candidate)) {
+      foundPath = candidate;
+      break;
+    }
+  }
+  if (!foundPath) {
+    const targetPath = import_node_path4.default.join(baseDir, "instrumentation.ts");
+    import_node_fs4.default.writeFileSync(targetPath, FULL_CONTENT, "utf8");
+    console.log(`    Created: ${import_node_path4.default.relative(process.cwd(), targetPath)}
+`);
+    return;
+  }
+  const content = import_node_fs4.default.readFileSync(foundPath, "utf8");
+  if (content.includes("onRequestError")) {
+    console.log("    onRequestError already present in instrumentation. Skipping.\n");
+    console.log("    To add PulseKit error reporting manually, add:\n");
+    console.log(`    ${IMPORT_LINE}`);
+    console.log("");
+    console.log("    export const onRequestError = createPulseErrorReporter({");
+    console.log("      supabase,");
+    console.log('      siteId: "default",');
+    console.log("    });\n");
+    return;
+  }
+  const importRegex = /^import\s.+$/gm;
+  let lastImportEnd = -1;
+  let match;
+  while ((match = importRegex.exec(content)) !== null) {
+    lastImportEnd = match.index + match[0].length;
+  }
+  let updated;
+  if (lastImportEnd === -1) {
+    updated = IMPORT_LINE + "\n" + content + EXPORT_BLOCK;
+  } else {
+    updated = content.slice(0, lastImportEnd) + "\n" + IMPORT_LINE + content.slice(lastImportEnd) + EXPORT_BLOCK;
+  }
+  import_node_fs4.default.writeFileSync(foundPath, updated, "utf8");
+  console.log(`    Modified: ${import_node_path4.default.relative(process.cwd(), foundPath)}
+`);
+}
+
+// src/migration.ts
+var import_node_fs5 = __toESM(require("fs"));
+var import_node_path5 = __toESM(require("path"));
 var SQL_MAP = JSON.parse(
-  `{"001_init_pulse.sql":"create schema if not exists analytics;\\n\\n-- Add analytics to the schemas exposed by PostgREST\\nalter role authenticator set pgrst.db_schemas = 'public, graphql_public, analytics';\\n\\n-- Schema-level access\\ngrant usage on schema analytics to anon, authenticated, service_role;\\nalter default privileges in schema analytics grant all on tables to anon, authenticated, service_role;\\n\\ncreate table if not exists analytics.pulse_events (\\n  id bigserial primary key,\\n  site_id text not null,\\n  session_id text,\\n  path text not null,\\n  event_type text not null,\\n  meta jsonb,\\n  created_at timestamptz not null default now()\\n);\\n\\ncreate index if not exists idx_pulse_events_site_created_at\\n  on analytics.pulse_events (site_id, created_at);\\n\\ncreate index if not exists idx_pulse_events_site_path_created_at\\n  on analytics.pulse_events (site_id, path, created_at);\\n\\nalter table analytics.pulse_events enable row level security;                                                                                                                       \\n                                                                                                                                                                                      \\n-- Allow the anon key (API route) to insert events\\ndrop policy if exists \\"Allow anon insert on pulse_events\\" on analytics.pulse_events;\\ncreate policy \\"Allow anon insert on pulse_events\\"\\n  on analytics.pulse_events\\n  for insert\\n  to anon\\n  with check (true);\\n\\n-- Only authenticated users (dashboard) can read events\\ndrop policy if exists \\"Allow authenticated select on pulse_events\\" on analytics.pulse_events;\\ncreate policy \\"Allow authenticated select on pulse_events\\"\\n  on analytics.pulse_events\\n  for select\\n  to authenticated\\n  using (true);\\n\\ncreate table if not exists analytics.pulse_aggregates (\\n  date date not null,\\n  site_id text not null,\\n  path text not null,\\n  total_views integer not null default 0,\\n  unique_visitors integer not null default 0,\\n  primary key (date, site_id, path)\\n);\\n\\n-- Grant table-level access (must be after table creation)\\ngrant all on all tables in schema analytics to anon, authenticated, service_role;\\ngrant all on all sequences in schema analytics to anon, authenticated, service_role;\\n\\nalter table analytics.pulse_aggregates enable row level security;\\n\\n-- Allow reading aggregates (dashboard)\\ndrop policy if exists \\"Allow authenticated select on pulse_aggregates\\" on analytics.pulse_aggregates;\\ncreate policy \\"Allow authenticated select on pulse_aggregates\\"\\n    on analytics.pulse_aggregates\\n    for select\\n    to authenticated\\n    using (true);\\n\\ndrop policy if exists \\"Allow anon select on pulse_aggregates\\" on analytics.pulse_aggregates;\\ncreate policy \\"Allow anon select on pulse_aggregates\\"\\n    on analytics.pulse_aggregates\\n    for select\\n    to anon\\n    using (true);\\n\\n-- Reload PostgREST config and schema cache (must be last)\\nnotify pgrst, 'reload config';\\nnotify pgrst, 'reload schema';\\n","002_aggregation_function.sql":"-- Aggregation function: rolls up raw events into daily aggregates\\ncreate or replace function analytics.pulse_refresh_aggregates(days_back integer default 7)\\nreturns void\\nlanguage sql\\nsecurity definer\\nas $$\\n  insert into analytics.pulse_aggregates (date, site_id, path, total_views, unique_visitors)\\n  select\\n    date_trunc('day', created_at)::date as date,\\n    site_id,\\n    path,\\n    count(*) as total_views,\\n    count(distinct session_id) as unique_visitors\\n  from analytics.pulse_events\\n  where created_at >= now() - (days_back || ' days')::interval\\n  group by 1, 2, 3\\n  on conflict (date, site_id, path) do update\\n  set\\n    total_views = excluded.total_views,\\n    unique_visitors = excluded.unique_visitors;\\n$$;\\n\\n-- Allow all roles to execute the aggregation function\\n-- security definer ensures it runs with the owner's privileges regardless of caller\\ngrant execute on function analytics.pulse_refresh_aggregates(integer) to anon, authenticated, service_role;\\n","003_geo_and_timezone.sql":"-- Add geo columns to pulse_events\\nalter table analytics.pulse_events\\n  add column if not exists country text,\\n  add column if not exists region text,\\n  add column if not exists city text,\\n  add column if not exists timezone text,\\n  add column if not exists latitude double precision,\\n  add column if not exists longitude double precision;\\n\\n-- Timezone-aware stats: queries raw events with AT TIME ZONE\\n-- so the dashboard can display data bucketed by the viewer's local day.\\ncreate or replace function analytics.pulse_stats_by_timezone(\\n  p_site_id text,\\n  p_timezone text default 'UTC',\\n  p_days_back integer default 7\\n)\\nreturns table (\\n  date date,\\n  path text,\\n  total_views bigint,\\n  unique_visitors bigint\\n)\\nlanguage sql\\nsecurity definer\\nstable\\nas $$\\n  select\\n    date_trunc('day', created_at at time zone p_timezone)::date as date,\\n    path,\\n    count(*) as total_views,\\n    count(distinct session_id) as unique_visitors\\n  from analytics.pulse_events\\n  where site_id = p_site_id\\n    and created_at >= now() - make_interval(days => p_days_back + 1)\\n  group by 1, 2;\\n$$;\\n\\ngrant execute on function analytics.pulse_stats_by_timezone(text, text, integer)\\n  to anon, authenticated, service_role;\\n\\n-- Drop first so return type can change (CREATE OR REPLACE cannot alter return columns)\\ndrop function if exists analytics.pulse_location_stats(text, integer);\\n\\n-- Location stats: visitor counts grouped by country + city, with averaged coordinates\\ncreate or replace function analytics.pulse_location_stats(\\n  p_site_id text,\\n  p_days_back integer default 7\\n)\\nreturns table (\\n  country text,\\n  city text,\\n  latitude double precision,\\n  longitude double precision,\\n  total_views bigint,\\n  unique_visitors bigint\\n)\\nlanguage sql\\nsecurity definer\\nstable\\nas $$\\n  select\\n    country,\\n    city,\\n    avg(latitude) as latitude,\\n    avg(longitude) as longitude,\\n    count(*) as total_views,\\n    count(distinct session_id) as unique_visitors\\n  from analytics.pulse_events\\n  where site_id = p_site_id\\n    and created_at >= now() - make_interval(days => p_days_back)\\n    and country is not null\\n  group by 1, 2\\n  order by total_views desc;\\n$$;\\n\\ngrant execute on function analytics.pulse_location_stats(text, integer)\\n  to anon, authenticated, service_role;\\n","004_web_vitals.sql":"-- 004_web_vitals.sql\\n-- Partial index + RPC for Web Vitals p75 aggregation\\n\\n-- Partial index: only covers vitals events, stays small\\nCREATE INDEX IF NOT EXISTS idx_pulse_events_vitals\\n  ON analytics.pulse_events (site_id, created_at)\\n  WHERE event_type = 'vitals';\\n\\n-- RPC: returns per-metric p75 for each page + site-wide (__overall__)\\nCREATE OR REPLACE FUNCTION analytics.pulse_vitals_stats(\\n  p_site_id  TEXT,\\n  p_days_back INT DEFAULT 7\\n)\\nRETURNS TABLE (\\n  path         TEXT,\\n  metric       TEXT,\\n  p75          DOUBLE PRECISION,\\n  sample_count BIGINT\\n)\\nLANGUAGE sql SECURITY DEFINER STABLE\\nAS $$\\n  WITH vitals_raw AS (\\n    SELECT\\n      e.path,\\n      kv.key   AS metric,\\n      kv.value::double precision AS val\\n    FROM analytics.pulse_events e,\\n         LATERAL jsonb_each_text(e.meta) AS kv(key, value)\\n    WHERE e.site_id    = p_site_id\\n      AND e.event_type = 'vitals'\\n      AND e.created_at >= NOW() - (p_days_back || ' days')::interval\\n      AND kv.key IN ('lcp', 'inp', 'cls', 'fcp', 'ttfb')\\n  )\\n  -- Per-page stats\\n  SELECT\\n    vr.path,\\n    vr.metric,\\n    percentile_cont(0.75) WITHIN GROUP (ORDER BY vr.val) AS p75,\\n    count(*)::bigint AS sample_count\\n  FROM vitals_raw vr\\n  GROUP BY vr.path, vr.metric\\n\\n  UNION ALL\\n\\n  -- Site-wide stats\\n  SELECT\\n    '__overall__'::text AS path,\\n    vr.metric,\\n    percentile_cont(0.75) WITHIN GROUP (ORDER BY vr.val) AS p75,\\n    count(*)::bigint AS sample_count\\n  FROM vitals_raw vr\\n  GROUP BY vr.metric;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_vitals_stats(TEXT, INT)\\n  TO anon, authenticated, service_role;\\n"}`
+  `{"001_init_pulse.sql":"create schema if not exists analytics;\\n\\n-- Add analytics to the schemas exposed by PostgREST\\nalter role authenticator set pgrst.db_schemas = 'public, graphql_public, analytics';\\n\\n-- Schema-level access\\ngrant usage on schema analytics to anon, authenticated, service_role;\\nalter default privileges in schema analytics grant all on tables to anon, authenticated, service_role;\\n\\ncreate table if not exists analytics.pulse_events (\\n  id bigserial primary key,\\n  site_id text not null,\\n  session_id text,\\n  path text not null,\\n  event_type text not null,\\n  meta jsonb,\\n  created_at timestamptz not null default now()\\n);\\n\\ncreate index if not exists idx_pulse_events_site_created_at\\n  on analytics.pulse_events (site_id, created_at);\\n\\ncreate index if not exists idx_pulse_events_site_path_created_at\\n  on analytics.pulse_events (site_id, path, created_at);\\n\\nalter table analytics.pulse_events enable row level security;                                                                                                                       \\n                                                                                                                                                                                      \\n-- Allow the anon key (API route) to insert events\\ndrop policy if exists \\"Allow anon insert on pulse_events\\" on analytics.pulse_events;\\ncreate policy \\"Allow anon insert on pulse_events\\"\\n  on analytics.pulse_events\\n  for insert\\n  to anon\\n  with check (true);\\n\\n-- Only authenticated users (dashboard) can read events\\ndrop policy if exists \\"Allow authenticated select on pulse_events\\" on analytics.pulse_events;\\ncreate policy \\"Allow authenticated select on pulse_events\\"\\n  on analytics.pulse_events\\n  for select\\n  to authenticated\\n  using (true);\\n\\ncreate table if not exists analytics.pulse_aggregates (\\n  date date not null,\\n  site_id text not null,\\n  path text not null,\\n  total_views integer not null default 0,\\n  unique_visitors integer not null default 0,\\n  primary key (date, site_id, path)\\n);\\n\\n-- Grant table-level access (must be after table creation)\\ngrant all on all tables in schema analytics to anon, authenticated, service_role;\\ngrant all on all sequences in schema analytics to anon, authenticated, service_role;\\n\\nalter table analytics.pulse_aggregates enable row level security;\\n\\n-- Allow reading aggregates (dashboard)\\ndrop policy if exists \\"Allow authenticated select on pulse_aggregates\\" on analytics.pulse_aggregates;\\ncreate policy \\"Allow authenticated select on pulse_aggregates\\"\\n    on analytics.pulse_aggregates\\n    for select\\n    to authenticated\\n    using (true);\\n\\ndrop policy if exists \\"Allow anon select on pulse_aggregates\\" on analytics.pulse_aggregates;\\ncreate policy \\"Allow anon select on pulse_aggregates\\"\\n    on analytics.pulse_aggregates\\n    for select\\n    to anon\\n    using (true);\\n\\n-- Reload PostgREST config and schema cache (must be last)\\nnotify pgrst, 'reload config';\\nnotify pgrst, 'reload schema';\\n","002_aggregation_function.sql":"-- Aggregation function: rolls up raw events into daily aggregates\\ncreate or replace function analytics.pulse_refresh_aggregates(days_back integer default 7)\\nreturns void\\nlanguage sql\\nsecurity definer\\nas $$\\n  insert into analytics.pulse_aggregates (date, site_id, path, total_views, unique_visitors)\\n  select\\n    date_trunc('day', created_at)::date as date,\\n    site_id,\\n    path,\\n    count(*) as total_views,\\n    count(distinct session_id) as unique_visitors\\n  from analytics.pulse_events\\n  where created_at >= now() - (days_back || ' days')::interval\\n  group by 1, 2, 3\\n  on conflict (date, site_id, path) do update\\n  set\\n    total_views = excluded.total_views,\\n    unique_visitors = excluded.unique_visitors;\\n$$;\\n\\n-- Allow all roles to execute the aggregation function\\n-- security definer ensures it runs with the owner's privileges regardless of caller\\ngrant execute on function analytics.pulse_refresh_aggregates(integer) to anon, authenticated, service_role;\\n","003_geo_and_timezone.sql":"-- Add geo columns to pulse_events\\nalter table analytics.pulse_events\\n  add column if not exists country text,\\n  add column if not exists region text,\\n  add column if not exists city text,\\n  add column if not exists timezone text,\\n  add column if not exists latitude double precision,\\n  add column if not exists longitude double precision;\\n\\n-- Timezone-aware stats: queries raw events with AT TIME ZONE\\n-- so the dashboard can display data bucketed by the viewer's local day.\\ncreate or replace function analytics.pulse_stats_by_timezone(\\n  p_site_id text,\\n  p_timezone text default 'UTC',\\n  p_days_back integer default 7\\n)\\nreturns table (\\n  date date,\\n  path text,\\n  total_views bigint,\\n  unique_visitors bigint\\n)\\nlanguage sql\\nsecurity definer\\nstable\\nas $$\\n  select\\n    date_trunc('day', created_at at time zone p_timezone)::date as date,\\n    path,\\n    count(*) as total_views,\\n    count(distinct session_id) as unique_visitors\\n  from analytics.pulse_events\\n  where site_id = p_site_id\\n    and created_at >= now() - make_interval(days => p_days_back + 1)\\n  group by 1, 2;\\n$$;\\n\\ngrant execute on function analytics.pulse_stats_by_timezone(text, text, integer)\\n  to anon, authenticated, service_role;\\n\\n-- Drop first so return type can change (CREATE OR REPLACE cannot alter return columns)\\ndrop function if exists analytics.pulse_location_stats(text, integer);\\n\\n-- Location stats: visitor counts grouped by country + city, with averaged coordinates\\ncreate or replace function analytics.pulse_location_stats(\\n  p_site_id text,\\n  p_days_back integer default 7\\n)\\nreturns table (\\n  country text,\\n  city text,\\n  latitude double precision,\\n  longitude double precision,\\n  total_views bigint,\\n  unique_visitors bigint\\n)\\nlanguage sql\\nsecurity definer\\nstable\\nas $$\\n  select\\n    country,\\n    city,\\n    avg(latitude) as latitude,\\n    avg(longitude) as longitude,\\n    count(*) as total_views,\\n    count(distinct session_id) as unique_visitors\\n  from analytics.pulse_events\\n  where site_id = p_site_id\\n    and created_at >= now() - make_interval(days => p_days_back)\\n    and country is not null\\n  group by 1, 2\\n  order by total_views desc;\\n$$;\\n\\ngrant execute on function analytics.pulse_location_stats(text, integer)\\n  to anon, authenticated, service_role;\\n","004_web_vitals.sql":"-- 004_web_vitals.sql\\n-- Partial index + RPC for Web Vitals p75 aggregation\\n\\n-- Partial index: only covers vitals events, stays small\\nCREATE INDEX IF NOT EXISTS idx_pulse_events_vitals\\n  ON analytics.pulse_events (site_id, created_at)\\n  WHERE event_type = 'vitals';\\n\\n-- RPC: returns per-metric p75 for each page + site-wide (__overall__)\\nCREATE OR REPLACE FUNCTION analytics.pulse_vitals_stats(\\n  p_site_id  TEXT,\\n  p_days_back INT DEFAULT 7\\n)\\nRETURNS TABLE (\\n  path         TEXT,\\n  metric       TEXT,\\n  p75          DOUBLE PRECISION,\\n  sample_count BIGINT\\n)\\nLANGUAGE sql SECURITY DEFINER STABLE\\nAS $$\\n  WITH vitals_raw AS (\\n    SELECT\\n      e.path,\\n      kv.key   AS metric,\\n      kv.value::double precision AS val\\n    FROM analytics.pulse_events e,\\n         LATERAL jsonb_each_text(e.meta) AS kv(key, value)\\n    WHERE e.site_id    = p_site_id\\n      AND e.event_type = 'vitals'\\n      AND e.created_at >= NOW() - (p_days_back || ' days')::interval\\n      AND kv.key IN ('lcp', 'inp', 'cls', 'fcp', 'ttfb')\\n  )\\n  -- Per-page stats\\n  SELECT\\n    vr.path,\\n    vr.metric,\\n    percentile_cont(0.75) WITHIN GROUP (ORDER BY vr.val) AS p75,\\n    count(*)::bigint AS sample_count\\n  FROM vitals_raw vr\\n  GROUP BY vr.path, vr.metric\\n\\n  UNION ALL\\n\\n  -- Site-wide stats\\n  SELECT\\n    '__overall__'::text AS path,\\n    vr.metric,\\n    percentile_cont(0.75) WITHIN GROUP (ORDER BY vr.val) AS p75,\\n    count(*)::bigint AS sample_count\\n  FROM vitals_raw vr\\n  GROUP BY vr.metric;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_vitals_stats(TEXT, INT)\\n  TO anon, authenticated, service_role;\\n","005_error_tracking.sql":"-- 005_error_tracking.sql\\n-- Fix existing RPCs to filter by event_type = 'pageview', add error tracking\\n\\n-- \u2500\u2500 Fix pulse_refresh_aggregates: only aggregate pageview events \u2500\u2500\u2500\u2500\u2500\u2500\\nCREATE OR REPLACE FUNCTION analytics.pulse_refresh_aggregates(days_back integer default 7)\\nRETURNS void\\nLANGUAGE sql\\nSECURITY DEFINER\\nAS $$\\n  INSERT INTO analytics.pulse_aggregates (date, site_id, path, total_views, unique_visitors)\\n  SELECT\\n    date_trunc('day', created_at)::date AS date,\\n    site_id,\\n    path,\\n    count(*) AS total_views,\\n    count(distinct session_id) AS unique_visitors\\n  FROM analytics.pulse_events\\n  WHERE created_at >= now() - (days_back || ' days')::interval\\n    AND event_type = 'pageview'\\n  GROUP BY 1, 2, 3\\n  ON CONFLICT (date, site_id, path) DO UPDATE\\n  SET\\n    total_views = excluded.total_views,\\n    unique_visitors = excluded.unique_visitors;\\n$$;\\n\\n-- \u2500\u2500 Fix pulse_stats_by_timezone: only count pageview events \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\nCREATE OR REPLACE FUNCTION analytics.pulse_stats_by_timezone(\\n  p_site_id text,\\n  p_timezone text default 'UTC',\\n  p_days_back integer default 7\\n)\\nRETURNS TABLE (\\n  date date,\\n  path text,\\n  total_views bigint,\\n  unique_visitors bigint\\n)\\nLANGUAGE sql\\nSECURITY DEFINER\\nSTABLE\\nAS $$\\n  SELECT\\n    date_trunc('day', created_at AT TIME ZONE p_timezone)::date AS date,\\n    path,\\n    count(*) AS total_views,\\n    count(distinct session_id) AS unique_visitors\\n  FROM analytics.pulse_events\\n  WHERE site_id = p_site_id\\n    AND created_at >= now() - make_interval(days => p_days_back + 1)\\n    AND event_type = 'pageview'\\n  GROUP BY 1, 2;\\n$$;\\n\\n-- \u2500\u2500 Fix pulse_location_stats: only count pageview events \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\nCREATE OR REPLACE FUNCTION analytics.pulse_location_stats(\\n  p_site_id text,\\n  p_days_back integer default 7\\n)\\nRETURNS TABLE (\\n  country text,\\n  city text,\\n  latitude double precision,\\n  longitude double precision,\\n  total_views bigint,\\n  unique_visitors bigint\\n)\\nLANGUAGE sql\\nSECURITY DEFINER\\nSTABLE\\nAS $$\\n  SELECT\\n    country,\\n    city,\\n    avg(latitude) AS latitude,\\n    avg(longitude) AS longitude,\\n    count(*) AS total_views,\\n    count(distinct session_id) AS unique_visitors\\n  FROM analytics.pulse_events\\n  WHERE site_id = p_site_id\\n    AND created_at >= now() - make_interval(days => p_days_back)\\n    AND country IS NOT NULL\\n    AND event_type = 'pageview'\\n  GROUP BY 1, 2\\n  ORDER BY total_views DESC;\\n$$;\\n\\n-- \u2500\u2500 Partial index for error events \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\nCREATE INDEX IF NOT EXISTS idx_pulse_events_errors\\n  ON analytics.pulse_events (site_id, created_at)\\n  WHERE event_type IN ('error', 'server_error');\\n\\n-- \u2500\u2500 Error stats RPC \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\nCREATE OR REPLACE FUNCTION analytics.pulse_error_stats(\\n  p_site_id  TEXT,\\n  p_days_back INT DEFAULT 7\\n)\\nRETURNS TABLE (\\n  error_type   TEXT,\\n  message      TEXT,\\n  path         TEXT,\\n  total_count  BIGINT,\\n  session_count BIGINT,\\n  last_seen    TIMESTAMPTZ,\\n  first_seen   TIMESTAMPTZ,\\n  sample_meta  JSONB\\n)\\nLANGUAGE sql SECURITY DEFINER STABLE\\nAS $$\\n  WITH ranked AS (\\n    SELECT\\n      e.event_type AS error_type,\\n      e.meta->>'message' AS message,\\n      e.path,\\n      count(*) AS total_count,\\n      count(DISTINCT e.session_id) AS session_count,\\n      max(e.created_at) AS last_seen,\\n      min(e.created_at) AS first_seen,\\n      -- Get the full meta from the most recent occurrence\\n      (ARRAY_AGG(e.meta ORDER BY e.created_at DESC))[1] AS sample_meta\\n    FROM analytics.pulse_events e\\n    WHERE e.site_id = p_site_id\\n      AND e.event_type IN ('error', 'server_error')\\n      AND e.created_at >= NOW() - (p_days_back || ' days')::interval\\n    GROUP BY e.event_type, e.meta->>'message', e.path\\n  )\\n  SELECT * FROM ranked\\n  ORDER BY last_seen DESC\\n  LIMIT 50;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_error_stats(TEXT, INT)\\n  TO anon, authenticated, service_role;\\n","006_date_range_support.sql":"-- 006_date_range_support.sql\\n-- Replace p_days_back with p_start_date / p_end_date date range params.\\n-- Both default to NULL \u2192 falls back to last 7 days when not provided.\\n\\n-- \u2500\u2500 pulse_stats_by_timezone \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\nDROP FUNCTION IF EXISTS analytics.pulse_stats_by_timezone(text, text, integer);\\n\\nCREATE OR REPLACE FUNCTION analytics.pulse_stats_by_timezone(\\n  p_site_id    text,\\n  p_timezone   text    DEFAULT 'UTC',\\n  p_start_date date    DEFAULT NULL,\\n  p_end_date   date    DEFAULT NULL\\n)\\nRETURNS TABLE (\\n  date             date,\\n  path             text,\\n  total_views      bigint,\\n  unique_visitors  bigint\\n)\\nLANGUAGE sql\\nSECURITY DEFINER\\nSTABLE\\nAS $$\\n  SELECT\\n    date_trunc('day', created_at AT TIME ZONE p_timezone)::date AS date,\\n    path,\\n    count(*) AS total_views,\\n    count(DISTINCT session_id) AS unique_visitors\\n  FROM analytics.pulse_events\\n  WHERE site_id = p_site_id\\n    AND event_type = 'pageview'\\n    AND created_at >= (COALESCE(p_start_date, current_date - 7)::timestamp AT TIME ZONE p_timezone)\\n    AND created_at < ((COALESCE(p_end_date, current_date) + interval '1 day')::timestamp AT TIME ZONE p_timezone)\\n  GROUP BY 1, 2;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_stats_by_timezone(text, text, date, date)\\n  TO anon, authenticated, service_role;\\n\\n-- \u2500\u2500 pulse_location_stats \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\nDROP FUNCTION IF EXISTS analytics.pulse_location_stats(text, integer);\\n\\nCREATE OR REPLACE FUNCTION analytics.pulse_location_stats(\\n  p_site_id    text,\\n  p_start_date date DEFAULT NULL,\\n  p_end_date   date DEFAULT NULL\\n)\\nRETURNS TABLE (\\n  country          text,\\n  city             text,\\n  latitude         double precision,\\n  longitude        double precision,\\n  total_views      bigint,\\n  unique_visitors  bigint\\n)\\nLANGUAGE sql\\nSECURITY DEFINER\\nSTABLE\\nAS $$\\n  SELECT\\n    country,\\n    city,\\n    avg(latitude) AS latitude,\\n    avg(longitude) AS longitude,\\n    count(*) AS total_views,\\n    count(DISTINCT session_id) AS unique_visitors\\n  FROM analytics.pulse_events\\n  WHERE site_id = p_site_id\\n    AND event_type = 'pageview'\\n    AND country IS NOT NULL\\n    AND created_at >= COALESCE(p_start_date, current_date - 7)::timestamptz\\n    AND created_at < (COALESCE(p_end_date, current_date) + interval '1 day')::timestamptz\\n  GROUP BY 1, 2\\n  ORDER BY total_views DESC;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_location_stats(text, date, date)\\n  TO anon, authenticated, service_role;\\n\\n-- \u2500\u2500 pulse_vitals_stats \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\nDROP FUNCTION IF EXISTS analytics.pulse_vitals_stats(text, int);\\n\\nCREATE OR REPLACE FUNCTION analytics.pulse_vitals_stats(\\n  p_site_id    text,\\n  p_start_date date DEFAULT NULL,\\n  p_end_date   date DEFAULT NULL\\n)\\nRETURNS TABLE (\\n  path         text,\\n  metric       text,\\n  p75          double precision,\\n  sample_count bigint\\n)\\nLANGUAGE sql SECURITY DEFINER STABLE\\nAS $$\\n  WITH vitals_raw AS (\\n    SELECT\\n      e.path,\\n      kv.key   AS metric,\\n      kv.value::double precision AS val\\n    FROM analytics.pulse_events e,\\n         LATERAL jsonb_each_text(e.meta) AS kv(key, value)\\n    WHERE e.site_id    = p_site_id\\n      AND e.event_type = 'vitals'\\n      AND e.created_at >= COALESCE(p_start_date, current_date - 7)::timestamptz\\n      AND e.created_at < (COALESCE(p_end_date, current_date) + interval '1 day')::timestamptz\\n      AND kv.key IN ('lcp', 'inp', 'cls', 'fcp', 'ttfb')\\n  )\\n  -- Per-page stats\\n  SELECT\\n    vr.path,\\n    vr.metric,\\n    percentile_cont(0.75) WITHIN GROUP (ORDER BY vr.val) AS p75,\\n    count(*)::bigint AS sample_count\\n  FROM vitals_raw vr\\n  GROUP BY vr.path, vr.metric\\n\\n  UNION ALL\\n\\n  -- Site-wide stats\\n  SELECT\\n    '__overall__'::text AS path,\\n    vr.metric,\\n    percentile_cont(0.75) WITHIN GROUP (ORDER BY vr.val) AS p75,\\n    count(*)::bigint AS sample_count\\n  FROM vitals_raw vr\\n  GROUP BY vr.metric;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_vitals_stats(text, date, date)\\n  TO anon, authenticated, service_role;\\n\\n-- \u2500\u2500 pulse_error_stats \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\nDROP FUNCTION IF EXISTS analytics.pulse_error_stats(text, int);\\n\\nCREATE OR REPLACE FUNCTION analytics.pulse_error_stats(\\n  p_site_id    text,\\n  p_start_date date DEFAULT NULL,\\n  p_end_date   date DEFAULT NULL\\n)\\nRETURNS TABLE (\\n  error_type    text,\\n  message       text,\\n  path          text,\\n  total_count   bigint,\\n  session_count bigint,\\n  last_seen     timestamptz,\\n  first_seen    timestamptz,\\n  sample_meta   jsonb\\n)\\nLANGUAGE sql SECURITY DEFINER STABLE\\nAS $$\\n  WITH ranked AS (\\n    SELECT\\n      e.event_type AS error_type,\\n      e.meta->>'message' AS message,\\n      e.path,\\n      count(*) AS total_count,\\n      count(DISTINCT e.session_id) AS session_count,\\n      max(e.created_at) AS last_seen,\\n      min(e.created_at) AS first_seen,\\n      (ARRAY_AGG(e.meta ORDER BY e.created_at DESC))[1] AS sample_meta\\n    FROM analytics.pulse_events e\\n    WHERE e.site_id = p_site_id\\n      AND e.event_type IN ('error', 'server_error')\\n      AND e.created_at >= COALESCE(p_start_date, current_date - 7)::timestamptz\\n      AND e.created_at < (COALESCE(p_end_date, current_date) + interval '1 day')::timestamptz\\n    GROUP BY e.event_type, e.meta->>'message', e.path\\n  )\\n  SELECT * FROM ranked\\n  ORDER BY last_seen DESC\\n  LIMIT 50;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_error_stats(text, date, date)\\n  TO anon, authenticated, service_role;\\n","007_data_lifecycle.sql":"-- 007_data_lifecycle.sql\\n-- Automatic data consolidation & cleanup.\\n-- Rolls pageview counts older than retention_days into pulse_aggregates,\\n-- then deletes all old raw events (all event types).\\n\\nCREATE OR REPLACE FUNCTION analytics.pulse_consolidate_and_cleanup(\\n  retention_days int DEFAULT 30\\n)\\nRETURNS TABLE (rows_consolidated bigint, rows_deleted bigint)\\nLANGUAGE plpgsql\\nSECURITY DEFINER\\nAS $$\\nDECLARE\\n  v_cutoff timestamptz;\\n  v_consolidated bigint;\\n  v_deleted bigint;\\nBEGIN\\n  v_cutoff := now() - make_interval(days => retention_days);\\n\\n  -- Step 1: Roll up old pageview events into daily aggregates\\n  WITH inserted AS (\\n    INSERT INTO analytics.pulse_aggregates (date, site_id, path, total_views, unique_visitors)\\n    SELECT\\n      date_trunc('day', created_at)::date AS date,\\n      site_id,\\n      path,\\n      count(*)::int AS total_views,\\n      count(DISTINCT session_id)::int AS unique_visitors\\n    FROM analytics.pulse_events\\n    WHERE created_at < v_cutoff\\n      AND event_type = 'pageview'\\n    GROUP BY 1, 2, 3\\n    ON CONFLICT (date, site_id, path) DO UPDATE SET\\n      total_views     = GREATEST(analytics.pulse_aggregates.total_views, excluded.total_views),\\n      unique_visitors = GREATEST(analytics.pulse_aggregates.unique_visitors, excluded.unique_visitors)\\n    RETURNING 1\\n  )\\n  SELECT count(*) INTO v_consolidated FROM inserted;\\n\\n  -- Step 2: Delete all old events (pageviews, vitals, errors, etc.)\\n  WITH deleted AS (\\n    DELETE FROM analytics.pulse_events\\n    WHERE created_at < v_cutoff\\n    RETURNING 1\\n  )\\n  SELECT count(*) INTO v_deleted FROM deleted;\\n\\n  RETURN QUERY SELECT v_consolidated, v_deleted;\\nEND;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_consolidate_and_cleanup(int)\\n  TO anon, authenticated, service_role;\\n\\n-- \u2500\u2500 Replace pulse_stats_by_timezone to union raw events + aggregates \u2500\u2500\\nDROP FUNCTION IF EXISTS analytics.pulse_stats_by_timezone(text, text, date, date);\\n\\nCREATE OR REPLACE FUNCTION analytics.pulse_stats_by_timezone(\\n  p_site_id    text,\\n  p_timezone   text    DEFAULT 'UTC',\\n  p_start_date date    DEFAULT NULL,\\n  p_end_date   date    DEFAULT NULL\\n)\\nRETURNS TABLE (\\n  date             date,\\n  path             text,\\n  total_views      bigint,\\n  unique_visitors  bigint\\n)\\nLANGUAGE sql\\nSECURITY DEFINER\\nSTABLE\\nAS $$\\n  WITH\\n    -- Find the earliest raw pageview date for this site\\n    oldest_raw AS (\\n      SELECT min(date_trunc('day', created_at AT TIME ZONE p_timezone)::date) AS min_date\\n      FROM analytics.pulse_events\\n      WHERE site_id = p_site_id\\n        AND event_type = 'pageview'\\n    ),\\n    -- Aggregated data for dates before the oldest raw event\\n    from_aggregates AS (\\n      SELECT\\n        a.date,\\n        a.path,\\n        a.total_views::bigint,\\n        a.unique_visitors::bigint\\n      FROM analytics.pulse_aggregates a, oldest_raw o\\n      WHERE a.site_id = p_site_id\\n        AND a.date >= COALESCE(p_start_date, current_date - 7)\\n        AND a.date < COALESCE(p_end_date, current_date) + 1\\n        AND (o.min_date IS NULL OR a.date < o.min_date)\\n    ),\\n    -- Raw events for recent data\\n    from_raw AS (\\n      SELECT\\n        date_trunc('day', created_at AT TIME ZONE p_timezone)::date AS date,\\n        path,\\n        count(*) AS total_views,\\n        count(DISTINCT session_id) AS unique_visitors\\n      FROM analytics.pulse_events\\n      WHERE site_id = p_site_id\\n        AND event_type = 'pageview'\\n        AND created_at >= (COALESCE(p_start_date, current_date - 7)::timestamp AT TIME ZONE p_timezone)\\n        AND created_at < ((COALESCE(p_end_date, current_date) + interval '1 day')::timestamp AT TIME ZONE p_timezone)\\n      GROUP BY 1, 2\\n    )\\n  SELECT * FROM from_aggregates\\n  UNION ALL\\n  SELECT * FROM from_raw;\\n$$;\\n\\nGRANT EXECUTE ON FUNCTION analytics.pulse_stats_by_timezone(text, text, date, date)\\n  TO anon, authenticated, service_role;\\n"}`
 );
 function writeMigration() {
   console.log("  Writing database migration...\n");
-  const supabaseDir = import_node_path4.default.join(process.cwd(), "supabase", "migrations");
-  import_node_fs4.default.mkdirSync(supabaseDir, { recursive: true });
+  const supabaseDir = import_node_path5.default.join(process.cwd(), "supabase", "migrations");
+  import_node_fs5.default.mkdirSync(supabaseDir, { recursive: true });
   const files = Object.keys(SQL_MAP).sort();
   const combined = files.map((file) => `-- ${file}
 ${SQL_MAP[file]}`).join("\n\n");
   const filename = "20250101000000_pulse_analytics.sql";
-  const fullPath = import_node_path4.default.join(supabaseDir, filename);
-  if (import_node_fs4.default.existsSync(fullPath)) {
+  const fullPath = import_node_path5.default.join(supabaseDir, filename);
+  if (import_node_fs5.default.existsSync(fullPath)) {
     console.log(`    Skipped (already exists): supabase/migrations/${filename}
 `);
     return;
   }
-  import_node_fs4.default.writeFileSync(fullPath, combined, "utf8");
+  import_node_fs5.default.writeFileSync(fullPath, combined, "utf8");
   console.log(`    Created: supabase/migrations/${filename}
 `);
 }
@@ -273,6 +396,7 @@ async function main() {
   await installPackages(pm);
   scaffoldFiles();
   await injectPulseTracker();
+  await injectInstrumentation();
   writeMigration();
   console.log("\n  Done! PulseKit has been added to your project.\n");
   console.log("  To finish setup:");

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "create-pulsekit",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Set up PulseKit analytics in your Next.js project",
   "bin": "./dist/index.js",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
   "scripts": {
     "prebuild": "cp ../core/sql/*.sql src/sql/",
     "build": "tsup",
     "clean": "rm -rf dist"
-  },
-  "devDependencies": {
-    "tsup": "^8.0.0",
-    "typescript": "^5.7.0"
   }
-}
+}