@summalytics/js

Privacy-first analytics SDK for JavaScript and TypeScript. Works in any browser environment — no cookies, no PII.

Install

npm install @summalytics/js

Usage

import { createSummalytics } from '@summalytics/js'

const analytics = createSummalytics({
  writeKey: 'YOUR_WRITE_KEY',
  // endpoint defaults to https://summalytics.ai/api/ingest
})

// Track a custom event
analytics.track('signup_completed', { value: 1 })

// Track a pageview manually
analytics.pageview({ path: '/pricing' })

// Track a tagged landing URL
analytics.pageview({ path: '/?utm_source=quizgeniusai&utm_medium=referral&utm_campaign=footer' })

Server-side crawler capture (Next.js middleware / edge)

Track pageviews from server/edge requests so crawler traffic is captured even when bots do not execute JavaScript.

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server'
import { isAiCrawlerUserAgent, trackServerPageview } from '@summalytics/js'

export async function middleware(request: NextRequest) {
  const ua = request.headers.get('user-agent')

  if (isAiCrawlerUserAgent(ua)) {
    // fire-and-forget to avoid impacting response latency
    void trackServerPageview(
      {
        writeKey: process.env.NEXT_PUBLIC_SUMMALYTICS_KEY!,
        endpoint: 'https://summalytics.ai/api/ingest',
      },
      {
        url: request.url,
        userAgent: ua,
        referrer: request.headers.get('referer'),
        ip: request.headers.get('x-forwarded-for'),
        country: request.headers.get('x-vercel-ip-country'),
        city: request.headers.get('x-vercel-ip-city'),
        onlyIfAiCrawler: true,
      },
    )
  }

  return NextResponse.next()
}

trackServerPageview forwards:

• x-summalytics-origin (for domain allow-list validation)
• original user-agent (for crawler classification)
• optional IP/country/city headers for geo enrichment

By default, one pageview is fired automatically on createSummalytics() in browser environments using pathname + search (query string included). Disable it with autoPageview: false.

const analytics = createSummalytics({
  writeKey: 'YOUR_WRITE_KEY',
  autoPageview: false,
})

Config

| Option | Type | Default | Description | |---|---|---|---| | writeKey | string | required | Your project write key | | endpoint | string | https://summalytics.ai/api/ingest | Ingest endpoint | | autoPageview | boolean | true | Fire a pageview on init |

Additional exports:

• isAiCrawlerUserAgent(userAgent) — checks UA against known AI crawler signatures
• trackServerPageview(config, payload) — sends pageviews from server/edge environments

Self-hosting

If you run your own Summalytics instance, pass your endpoint:

const analytics = createSummalytics({
  writeKey: 'YOUR_WRITE_KEY',
  endpoint: 'https://yourapp.com/api/ingest',
})

License

MIT