@degreesign/analytics

Privacy-first, self-hosted web analytics for Node.js and the browser — capture pageviews, clicks and in-view events, resolve visitor countries from IP ranges, and generate traffic reports without cookies, third-party trackers, or an external analytics service.

Table of Contents

• Introduction
• Why DegreeSign Analytics
• Installation
• Quick Start
• API Reference
  • IP Management and Rate Limiting
  • Server-Side Analytics
  • Traffic Analysis
  • Browser Tracking
  • TypeScript Types
• FAQ
• Keywords
• License

Introduction

@degreesign/analytics is a lightweight, TypeScript-first analytics SDK that gives you ownership of your own traffic data. The browser bundle records pageviews, click and in-view interaction events, then hands each payload to your record callback so you can send it to your own endpoint. The Node.js bundle receives those payloads, rate-limits abusive IPs, resolves each visitor's country from an IPv4 range database, and stores everything as plain JSON files on your server. From there it aggregates visits, unique visitors, bounce rate, durations, referrers, countries, devices, time-series charts and per-tag click/in-view metrics — no cookies, no third-party service, no data leaving your infrastructure.

Why DegreeSign Analytics

• Privacy-first and self-hosted — every visit is stored on your own server; nothing is sent to a third party.
• Cookie-free tracking — visitors are identified by a random, rotating statsId in localStorage, not a tracking cookie.
• Works in Node.js and the browser — one package ships a CommonJS Node 18+ build and a UMD browser build.
• TypeScript-native — written in TypeScript with complete type declarations, enums and typed callback inputs.
• Built-in spam protection — IP rate limits, black/white/priority lists, and statistical visit-spam filtering.
• Rich metrics out of the box — visits, visitors, bounce, mean duration, referrers, countries, devices, screen dimensions, charts, and click/in-view tags.
• Tiny dependency footprint — only two small internal @degreesign helpers, no third-party runtime libraries.
• Framework agnostic — drop it into React, Vue, Svelte, Angular, Solid, or plain HTML/JS.
• Zero-config defaults — sensible intervals, rate limits and folder layout work immediately; every option is overridable.

Installation

Install with your package manager:

# npm
npm install @degreesign/analytics

# yarn
yarn add @degreesign/analytics

# pnpm
pnpm add @degreesign/analytics

Or load the browser build straight from a CDN (UMD global: dsAnalytics):

<script src="https://cdn.jsdelivr.net/npm/@degreesign/analytics@1.1.5/dist/browser/degreesign.min.js"></script>

Quick Start

1. Track visits in the browser

import {
    setWebConfig,
    webAnalytics,
    recordEvent,
    StatsEventType,
} from '@degreesign/analytics';

// Optional: how often a running visit is reported (default 5000 ms)
setWebConfig({ checkInterval: 5e3 });

// Start the page-visit heartbeat.
// `record` fires periodically, and once more with `final === true` on dismissal.
webAnalytics({
    logged: false,
    record: (data, final) => {
        const body = JSON.stringify(data);
        if (final && navigator.sendBeacon) {
            navigator.sendBeacon('/api/analytics', body); // dismissal send
        } else {
            fetch('/api/analytics', { method: 'POST', body, keepalive: true });
        }
    },
});

// Tag a specific interaction (tag is required for click / inview)
recordEvent({ eventType: StatsEventType.click, tag: 'signup-cta' });
recordEvent({ eventType: StatsEventType.inview, tag: 'pricing-table' });

2. Receive and store visits on the server

import {
    startAnalyticsServer,
    ipCheck,
    recordStats,
    ipData,
} from '@degreesign/analytics';

// Configure storage and start IP + persistence services once at boot.
await startAnalyticsServer({
    trafficDir: 'traffic',
    thisDomain: 'example.com',
    searchEngines: ['google', 'bing'],
    excludeURIs: ['admin', 'health'],
});

// Inside your POST /api/analytics handler:
const requestIP = (req.headers['x-forwarded-for'] as string) || req.socket.remoteAddress || '';

if (ipCheck(requestIP)) {
    recordStats({
        ipRange: ipData.ipRange,
        ips: requestIP,
        data: req.body, // the PageVisitPayload sent by the browser
    });
}

3. Read traffic reports

import {
    compare24hr,
    compareStats,
    dateStandard,
} from '@degreesign/analytics';

// Last 24 hours vs. the previous 24 hours
const [today, yesterday] = compare24hr() || [];
console.log(today?.visitors, today?.pages);

// A date range vs. the immediately preceding period
const [thisPeriod, previousPeriod] = compareStats({
    startDay: dateStandard('2026-01-01'),
    endDay: dateStandard('2026-01-31'),
}) || [];
console.log(thisPeriod?.total, thisPeriod?.countries, thisPeriod?.clicks);

4. CDN version (no bundler)

<script src="https://cdn.jsdelivr.net/npm/@degreesign/analytics@1.1.5/dist/browser/degreesign.min.js"></script>
<script>
    dsAnalytics.setWebConfig({ checkInterval: 5e3 });

    dsAnalytics.webAnalytics({
        logged: false,
        record: (data, final) => {
            const body = JSON.stringify(data);
            if (final && navigator.sendBeacon) {
                navigator.sendBeacon('/api/analytics', body);
            } else {
                fetch('/api/analytics', { method: 'POST', body, keepalive: true });
            }
        },
    });
</script>

API Reference

IP Management and Rate Limiting

Rate-limit and geolocate visitors by IP address. Default thresholds are generalAccess: 100, whiteListed: 500 and priorityAccess: 3000.

Export	Signature	Description
ipCheck	(ips: string) => 1 | 0 | undefined	Validate a raw IP string against the black, general, white and priority lists. Returns 1 when allowed and 0 when blocked (and blacklisted).
ipWhiteList	(ips: string) => void	Add one or more IPs to the trusted white list.
ipPriorityList	(ips: string) => void	Add one or more IPs to the high-rate-limit priority list.
ipResetLimits	() => IPList	Return a fresh, empty IP list structure with zeroed counters.
ipRateLimits	RateLimits	The active rate-limit thresholds object.
ipRangeUpdate	() => Promise<void>	Download the IPv4 → country range database and persist it to ip_range.json.
ipNumericalValue	(ip: string) => number	Convert a dotted IPv4 address to its numeric value.
ipArray	(ips: string) => string[]	Parse a comma-separated or ::ffff:-prefixed IP string into an array.
ipCountryCode	({ code, ips, ipRange }) => CountryCode	Resolve the ISO country code for an IP, falling back to the supplied code or UN.
ipData	IPData	Live store holding the current ipList and ipRange arrays.
ipStart	(config: IPConfig) => Promise<void>	Load cached IP ranges, then schedule background range refresh and limit resets.

Server-Side Analytics

Call these from your Node.js backend to bootstrap the service, record incoming visits and persist them to disk.

Export	Signature	Description
startAnalyticsServer	(config: ServiceConfig) => Promise<void>	One-call bootstrap: start the IP service, apply the stats config and start persistence.
configStats	(config: StatsConfig) => void	Configure trafficDir, thisDomain, excludeURIs, searchEngines and uriAlias.
recordStats	({ ipRange, ips, data }) => void	Store a PageVisitPayload under today's bucket; merges duration updates for the same session.
startStats	() => void	Create the traffic folder and flush cached stats to disk every 15 seconds.
dateStandard	(date) => string	Normalize a Date, timestamp or date string to the YYYY-MM-DD bucket key.

Traffic Analysis

Aggregate raw stored visits into reports, charts and per-tag interaction metrics.

Export	Signature	Description
compare24hr	(includeRaw?: boolean) => (StatsAnalysisResult | undefined)[] | undefined	Analyze the last 24 hours against the previous 24 hours (returns [today, yesterday]).
compareStats	({ startDay, endDay?, includeRaw? }) => (StatsAnalysisResult | undefined)[] | undefined	Analyze a date range against the immediately preceding period.
analyseStats	(params: StatsReqParams) => StatsAnalysisResult | undefined	Low-level analyzer turning raw day data into totals, pages, countries, devices, referrers, charts and click/in-view metrics.
combineStats	(days: string[]) => TrafficDataDay	Merge several stored days of traffic into a single dataset.
compareDateStrings	({ startDay, endDay? }) => string[] | undefined	Build the current and previous period date buckets used by the comparators.
statsPeriodStr	({ days, endTime? }) => { thisPeriod, prvPeriod }	Generate comma-separated day lists for a period and its predecessor.
statsAddOne	({ typeName, visitsObj, visitorsObj, visitId }) => void	Increment visit and unique-visitor counts for one dimension value.
formatVisits	({ visitors, visits }) => VisitorVisitsType[]	Convert visitor/visit maps into [value, visitors, visits] tuples sorted by visitors.

Browser Tracking

Exported from the browser/UMD bundle and the package entry point. Also available on the CDN global dsAnalytics.

Export	Signature	Description
webAnalytics	({ logged, record }) => void	Start the page-visit heartbeat; calls record(data, final?) on each interval and on dismissal.
setWebConfig	(config: WebConfig) => void	Set the browser check interval (default 5000 ms).
recordEvent	(input: RecordEventPageViewInput | RecordEventInteractionInput) => PageVisitPayload	Build a payload for a pageview, click or inview event. tag is required for interactions.
webData	(logged?: boolean) => PageVisitPayload	Deprecated — build a pageview payload directly; use recordEvent instead.
getCountryCode	() => CountryCode	Derive an approximate country code from the browser language.

TypeScript Types

All public types are exported and shipped as declaration files.

Type	Description
ServiceConfig	Combined server configuration (IPConfig & StatsConfig).
StatsConfig	Stats storage options: trafficDir, thisDomain, excludeURIs, searchEngines, uriAlias.
IPConfig	IP service intervals: ipRangeRefreshInterval, ipLimitResetInterval.
WebConfig	Browser options: checkInterval.
RecordCallback	(data: PageVisitPayload, final?: boolean) => any — the browser record callback.
PageVisitPayload	Full visit record plus uri, as sent by the browser.
PageVisitRecord	Stored visit record (statsId, event, window size, referrer, duration, country, tag).
PageVisitInitiation	Local visit basics (session, timestamp, uri, logged).
StatsAnalysisResult	Full analysis output: totals, pages, countries, devices, charts, clicks, inviews and optional raw data.
StatsReqParams	Input accepted by analyseStats.
StatsEventType	Enum of tracked events: pageview, click, inview.
StatsDevice	Enum of device types: mobile, desktop.
StatsDeviceType	Union of the StatsDevice keys.
StatsDeviceObj<T>	Object keyed by every StatsDevice.
RecordEventPageViewInput	recordEvent input for a pageview.
RecordEventInteractionInput	recordEvent input for a click/inview (requires tag).
StatsTagMetricSet	Aggregated metrics for a single interaction tag.
StatsTagMetricSets	Interaction metrics grouped by tag.
VisitorVisitsType	[value, visitors, visits] tuple.
DeviceWidthHeight	[width, height] tuple.
PageDeviceDimensions	Per-page device dimension map.
TrafficData / TrafficDataDay	Stored traffic keyed by date, then by page URI.
PageTrafficData / PageTrafficDataObj	Per-page traffic metrics and their map.
PageTrafficDataFinal / PageTrafficDataObjFinal	Finalized per-page metrics including durMean and verifiedVisits.
StatsFreqVisitors / StatsFreqVisits	Frequent-visitor summaries and raw inputs.
CountryCode	ISO country code union.
IPList	IP list structure (p, w, b, l).
IPData	IP store: ipList and ipRange.
IPRange	[startNum, endNum, countryCode] tuple.
IPCountryRange	Raw start/end/country record from the range database.
RateLimits	Rate-limit thresholds: generalAccess, whiteListed, priorityAccess.

FAQ

What is @degreesign/analytics? It is a privacy-first, self-hosted web analytics SDK. The browser bundle records visits and interaction events, and the Node.js bundle receives, rate-limits, geolocates, stores and analyzes them on your own server.

Is it free? Yes. It is released under the MIT License and free to use in personal and commercial projects.

Does it work in Node.js and the browser? Yes. The package ships two builds: a CommonJS bundle targeting Node.js 18+ (dist/node) and a UMD browser bundle (dist/browser) that exposes the global dsAnalytics.

Does it have any dependencies? Only two small internal helpers, @degreesign/cache for JSON persistence and @degreesign/utils for shared utilities. There are no third-party runtime libraries.

Is it written in TypeScript? Yes. The entire SDK is authored in TypeScript and ships .d.ts declarations for every public export, including enums and typed callback inputs.

Which frameworks does it support? It is framework agnostic. Because it is plain JavaScript/TypeScript, it works with React, Vue, Svelte, Angular, Solid, or vanilla HTML. Browser features require navigator, localStorage and document; server features require a Node.js 18+ runtime with fetch.

Does it use cookies? No. Visitors are identified by a random statsId kept in localStorage and rotated over time — there are no tracking cookies.

Where is my data stored? On your own server. Visit records are written as JSON files under the configurable trafficDir (default traffic), and the IP-to-country range database is cached as ip_range.json.

Keywords

web analytics, privacy-first analytics, self-hosted analytics, cookieless analytics, cookie-free tracking, pageview tracking, click tracking, in-view tracking, traffic analysis, visitor analytics, IP geolocation, IP rate limiting, spam filtering, Node.js analytics, browser analytics, TypeScript analytics SDK, UMD bundle, React analytics, Vue analytics, framework agnostic

License

MIT © DegreeSign