@unifeather/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dennis Hendricks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @unifeather/core
+
+Shared types, event normalization, UA parsing and the storage `Adapter`
+contract for [unifeather](https://github.com/dennishendricks/unifeather) — a
+lightweight, privacy-friendly, tree-shakeable website-analytics toolkit.
+
+This package is the common foundation the other `@unifeather/*` packages build
+on. You usually depend on it transitively; install it directly only when
+implementing a custom storage adapter or reusing the event schema.
+
+```sh
+bun add @unifeather/core   # or: npm i @unifeather/core
+```
+
+```ts
+import { normalizeEvent, type Adapter, type TrackingEvent } from "@unifeather/core";
+```
+
+See the [main README](https://github.com/dennishendricks/unifeather#readme) for the
+full picture and [AGENTS.md](https://github.com/dennishendricks/unifeather/blob/main/AGENTS.md)
+for the adapter contract.
+
+MIT © Dennis Hendricks

package/dist/adapter.d.ts

@@ -0,0 +1,54 @@
+import type { TrackingEvent } from "./event.js";
+/** Time-bucket granularity for the stats timeseries. */
+export type Interval = "hour" | "day";
+/** Parameters for an aggregated stats query. */
+export interface StatsQuery {
+    /** Inclusive lower bound, milliseconds since epoch. */
+    readonly from: number;
+    /** Exclusive upper bound, milliseconds since epoch. */
+    readonly to: number;
+    /** Max rows for top-N lists (pages, referrers). Defaults to 10. */
+    readonly limit?: number;
+    /** Timeseries bucket size. Defaults to "day". */
+    readonly interval?: Interval;
+}
+export interface CountedPath {
+    readonly path: string;
+    readonly views: number;
+}
+export interface CountedReferrer {
+    readonly referrer: string;
+    readonly views: number;
+}
+export interface TimeseriesPoint {
+    /** ISO date/hour label, e.g. "2026-07-13" or "2026-07-13T14:00". */
+    readonly date: string;
+    readonly views: number;
+}
+/** Aggregated result consumed by the dashboard. */
+export interface StatsResult {
+    readonly totals: {
+        readonly views: number;
+        /** Distinct visitors, when the backend can compute it. */
+        readonly visitors?: number;
+        readonly avgActiveSeconds?: number;
+    };
+    readonly topPages: readonly CountedPath[];
+    readonly topReferrers: readonly CountedReferrer[];
+    readonly timeseries: readonly TimeseriesPoint[];
+    /** True when the result was extrapolated from a sample rather than a full scan. */
+    readonly sampled: boolean;
+    /** Fraction of rows actually scanned (e.g. 0.1 = 10%), when sampled. */
+    readonly sampleRate?: number;
+}
+/**
+ * The storage contract. Every backend (Analytics Engine, SQL, and future
+ * ClickHouse/DuckDB adapters) implements this. `insert` handles ingestion;
+ * `stats` handles aggregation for the dashboard.
+ */
+export interface Adapter {
+    insert(event: TrackingEvent): Promise<void>;
+    /** Optional bulk path; the server falls back to per-event insert if absent. */
+    insertBatch?(events: readonly TrackingEvent[]): Promise<void>;
+    stats(query: StatsQuery): Promise<StatsResult>;
+}

package/dist/event.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Value types allowed in custom properties. Kept deliberately narrow so every
+ * storage backend (columnar, relational, Analytics Engine) can represent them.
+ */
+export type PropValue = string | number | boolean;
+/** Custom, caller-defined key/value pairs attached to an event. */
+export type Properties = Record<string, PropValue>;
+/**
+ * The raw payload as it leaves the browser. Intentionally minimal — everything
+ * that can be derived server-side (UA parsing, geo, visitor hashing) is NOT
+ * sent by the client, keeping the payload small and privacy-friendly.
+ *
+ * Only `eventId`, `timestamp` and `url` are guaranteed; the rest are optional
+ * and only present when the corresponding tracker option is enabled.
+ */
+export interface RawEvent {
+    /** Client-generated idempotency id. */
+    readonly eventId: string;
+    /** Event name, e.g. "pageview" (default) or a custom event. */
+    readonly name?: string;
+    /** Client clock, milliseconds since epoch. */
+    readonly timestamp: number;
+    /** Full location href at capture time. */
+    readonly url: string;
+    readonly referrer?: string;
+    readonly language?: string;
+    /** Foreground/active time on the page, in seconds. */
+    readonly activeSeconds?: number;
+    readonly screenWidth?: number;
+    readonly screenHeight?: number;
+    /** Custom id (passed by the app) or cookie-generated id — opt-in only. */
+    readonly userId?: string;
+    /** Session id — opt-in only. */
+    readonly sessionId?: string;
+    readonly properties?: Properties;
+}
+/**
+ * A fully normalized, storage-ready event. Produced by {@link normalizeEvent}
+ * after server-side enrichment. This is the single shape every {@link Adapter}
+ * persists and the shape stats queries aggregate over.
+ */
+export interface TrackingEvent {
+    readonly eventId: string;
+    readonly name: string;
+    /** Server-authoritative timestamp, milliseconds since epoch. */
+    readonly timestamp: number;
+    readonly hostname: string;
+    /** URL pathname (query string stripped unless configured otherwise). */
+    readonly path: string;
+    /** Bare referrer hostname, or undefined for direct/same-site traffic. */
+    readonly referrerHost?: string;
+    readonly language?: string;
+    readonly activeSeconds: number;
+    readonly browserName?: string;
+    readonly browserVersion?: string;
+    readonly osName?: string;
+    readonly osVersion?: string;
+    readonly screenWidth?: number;
+    readonly screenHeight?: number;
+    /** Two-letter country code, derived server-side (e.g. from CF-IPCountry). */
+    readonly country?: string;
+    /** Custom/app-provided or cookie-generated anonymous id — opt-in only. */
+    readonly userId?: string;
+    /** Session id from a session cookie — opt-in only. */
+    readonly sessionId?: string;
+    readonly properties?: Properties;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { PropValue, Properties, RawEvent, TrackingEvent } from "./event.js";
+export type { DeviceInfo } from "./ua-parser.js";
+export { parseUA } from "./ua-parser.js";
+export type { EnrichContext } from "./normalize.js";
+export { normalizeEvent } from "./normalize.js";
+export type { Adapter, Interval, StatsQuery, StatsResult, CountedPath, CountedReferrer, TimeseriesPoint } from "./adapter.js";

package/dist/index.js

@@ -0,0 +1,78 @@
+// src/ua-parser.ts
+var underscoresToDots = (version) => version.replace(/_/g, ".");
+var WINDOWS_VERSIONS = {
+  "10.0": "10/11",
+  "6.3": "8.1",
+  "6.2": "8",
+  "6.1": "7"
+};
+var BROWSER_RULES = [
+  { name: "Edge", pattern: /Edg(?:e|A|iOS)?\/(\d+)/ },
+  { name: "Opera", pattern: /OPR\/(\d+)/ },
+  { name: "Samsung Internet", pattern: /SamsungBrowser\/(\d+)/ },
+  { name: "Firefox", pattern: /(?:Firefox|FxiOS)\/(\d+)/ },
+  { name: "Chrome", pattern: /(?:Chrome|CriOS)\/(\d+)/ },
+  { name: "Safari", pattern: /Version\/(\d+).*Safari/ }
+];
+var OS_RULES = [
+  { name: "iOS", pattern: /(?:iPhone|iPad); CPU (?:iPhone )?OS (\d+[_.]\d+)/, format: underscoresToDots },
+  { name: "Android", pattern: /Android (\d+(?:\.\d+)?)/ },
+  { name: "Windows", pattern: /Windows NT (\d+\.\d+)/, format: (v) => WINDOWS_VERSIONS[v] ?? v },
+  { name: "macOS", pattern: /Mac OS X (\d+[_.]\d+(?:[_.]\d+)?)/, format: underscoresToDots },
+  { name: "Linux", pattern: /Linux/ }
+];
+var matchFirst = (ua, rules) => {
+  for (const { name, pattern, format } of rules) {
+    const match = ua.match(pattern);
+    if (!match) continue;
+    const raw = match[1];
+    return { name, version: raw ? format?.(raw) ?? raw : void 0 };
+  }
+  return {};
+};
+var parseUA = (ua) => {
+  const browser = matchFirst(ua, BROWSER_RULES);
+  const os = matchFirst(ua, OS_RULES);
+  return {
+    browserName: browser.name,
+    browserVersion: browser.version,
+    osName: os.name,
+    osVersion: os.version
+  };
+};
+
+// src/normalize.ts
+var hostOf = (value) => {
+  if (!value) return void 0;
+  try {
+    return new URL(value).hostname || void 0;
+  } catch {
+    return void 0;
+  }
+};
+var normalizeEvent = (raw, context = {}) => {
+  const url = new URL(raw.url);
+  const device = context.userAgent ? parseUA(context.userAgent) : {};
+  const stripQuery = context.stripQuery ?? true;
+  const referrerHost = hostOf(raw.referrer);
+  return {
+    eventId: raw.eventId,
+    name: raw.name ?? "pageview",
+    timestamp: context.now ?? raw.timestamp,
+    hostname: url.hostname,
+    path: stripQuery ? url.pathname : url.pathname + url.search,
+    // Same-site referrers are noise; only keep genuine external referrers.
+    referrerHost: referrerHost && referrerHost !== url.hostname ? referrerHost : void 0,
+    language: raw.language,
+    activeSeconds: raw.activeSeconds ?? 0,
+    ...device,
+    screenWidth: raw.screenWidth,
+    screenHeight: raw.screenHeight,
+    country: context.country,
+    userId: raw.userId,
+    sessionId: raw.sessionId,
+    properties: raw.properties
+  };
+};
+
+export { normalizeEvent, parseUA };

package/dist/normalize.d.ts

@@ -0,0 +1,18 @@
+import type { RawEvent, TrackingEvent } from "./event.js";
+/** Server-side context merged into a raw event during normalization. */
+export interface EnrichContext {
+    /** Server-authoritative timestamp (ms). Defaults to the client timestamp. */
+    readonly now?: number;
+    /** Raw User-Agent header, parsed into browser/OS. */
+    readonly userAgent?: string;
+    /** Two-letter country code (e.g. from the CF-IPCountry header). */
+    readonly country?: string;
+    /** Strip the query string from the stored path. Defaults to true. */
+    readonly stripQuery?: boolean;
+}
+/**
+ * Turn a browser {@link RawEvent} into a storage-ready {@link TrackingEvent}.
+ * Pure and synchronous — geo/visitor-hash derivation happens in the caller and
+ * is passed in via {@link EnrichContext}.
+ */
+export declare const normalizeEvent: (raw: RawEvent, context?: EnrichContext) => TrackingEvent;

package/dist/ua-parser.d.ts

@@ -0,0 +1,8 @@
+export interface DeviceInfo {
+    readonly browserName?: string;
+    readonly browserVersion?: string;
+    readonly osName?: string;
+    readonly osVersion?: string;
+}
+/** Parse a User-Agent string into coarse browser/OS info. Zero dependencies. */
+export declare const parseUA: (ua: string) => DeviceInfo;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@unifeather/core",
+  "version": "0.1.0",
+  "description": "Shared types, event normalization, UA parsing and the storage Adapter contract for unifeather.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Dennis Hendricks <dennis@hendricks.rocks>",
+  "keywords": [
+    "analytics",
+    "privacy",
+    "web-analytics",
+    "tracking",
+    "cookieless"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dennishendricks/unifeather.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/dennishendricks/unifeather#readme",
+  "bugs": "https://github.com/dennishendricks/unifeather/issues",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepublishOnly": "bun run build",
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}