@unifeather/server 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,30 @@
+# @unifeather/server
+
+Framework-agnostic tracking endpoint for
+[unifeather](https://github.com/dennishendricks/unifeather). `createHandler` returns a
+plain Web `(request) => Response`, so the same code runs on Cloudflare
+Workers/Pages and on Node (`node:http`, Express, …). Ships two storage adapters:
+Cloudflare Analytics Engine and Drizzle-backed SQL (Postgres/SQLite/MySQL).
+
+```sh
+bun add @unifeather/server   # or: npm i @unifeather/server
+```
+
+```ts
+import { createHandler } from "@unifeather/server";
+import { sqlAdapter } from "@unifeather/server/sql";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+
+const db = drizzle(new Pool({ connectionString: process.env.DATABASE_URL }));
+const handler = createHandler({ adapter: sqlAdapter({ db }), cors: true });
+```
+
+Subpath exports: `@unifeather/server` (handler), `./sql` (Drizzle adapter),
+`./analytics-engine` (Cloudflare adapter). `drizzle-orm` is an optional peer —
+importing the Analytics Engine adapter never pulls it in.
+
+See the [main README](https://github.com/dennishendricks/unifeather#readme) for the
+Cloudflare setup, query-side sampling and the multi-dialect SQL adapter.
+
+MIT © Dennis Hendricks

package/dist/adapters/analytics-engine.d.ts

@@ -0,0 +1,26 @@
+import type { Adapter } from "@unifeather/core";
+/** Minimal shape of the Analytics Engine Workers binding (`env.<NAME>`). */
+export interface AnalyticsEngineDataset {
+    writeDataPoint(point: {
+        indexes?: string[];
+        blobs?: (string | null)[];
+        doubles?: number[];
+    }): void;
+}
+export interface AnalyticsEngineOptions {
+    /** The Workers binding used for ingestion (`env.AE`). Required to `insert`. */
+    readonly dataset?: AnalyticsEngineDataset;
+    /** Cloudflare account id — required for `stats` (the SQL API). */
+    readonly accountId?: string;
+    /** API token with Analytics read permission — required for `stats`. */
+    readonly apiToken?: string;
+    /** The dataset name as referenced in SQL (the wrangler `dataset` value). */
+    readonly datasetName?: string;
+}
+/**
+ * Cloudflare Analytics Engine adapter. Ingestion is cheap and unlimited via the
+ * Workers binding; querying uses the SQL API. Analytics Engine applies adaptive
+ * sampling automatically and stores `_sample_interval` per row, so all counts
+ * are `SUM(_sample_interval)` to extrapolate back to true totals.
+ */
+export declare const analyticsEngineAdapter: (options: AnalyticsEngineOptions) => Adapter;

package/dist/adapters/analytics-engine.js

@@ -0,0 +1,97 @@
+// src/adapters/analytics-engine.ts
+var BLOBS = [
+  "name",
+  // blob1
+  "path",
+  // blob2
+  "hostname",
+  // blob3
+  "referrerHost",
+  // blob4
+  "language",
+  // blob5
+  "browserName",
+  // blob6
+  "browserVersion",
+  // blob7
+  "osName",
+  // blob8
+  "osVersion",
+  // blob9
+  "country",
+  // blob10
+  "userId",
+  // blob11
+  "sessionId"
+  // blob12
+];
+var SQL_URL = (accountId) => `https://api.cloudflare.com/client/v4/accounts/${accountId}/analytics_engine/sql`;
+var analyticsEngineAdapter = (options) => {
+  const insert = async (event) => {
+    if (!options.dataset) throw new Error("analyticsEngineAdapter: `dataset` binding required to insert");
+    options.dataset.writeDataPoint({
+      indexes: [event.path],
+      // sampling key
+      blobs: BLOBS.map((key) => {
+        const value = event[key];
+        return value == null ? null : String(value);
+      }),
+      doubles: [event.activeSeconds, event.screenWidth ?? 0, event.screenHeight ?? 0]
+    });
+  };
+  const runSql = async (sql) => {
+    const { accountId, apiToken } = options;
+    if (!accountId || !apiToken) {
+      throw new Error("analyticsEngineAdapter: `accountId` and `apiToken` required for stats");
+    }
+    const res = await fetch(SQL_URL(accountId), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${apiToken}`, "Content-Type": "text/plain" },
+      body: sql
+    });
+    if (!res.ok) throw new Error(`Analytics Engine SQL error ${res.status}: ${await res.text()}`);
+    return (await res.json()).data;
+  };
+  const stats = async (query) => {
+    const table = options.datasetName;
+    if (!table) throw new Error("analyticsEngineAdapter: `datasetName` required for stats");
+    const fromSec = Math.floor(query.from / 1e3);
+    const toSec = Math.floor(query.to / 1e3);
+    const limit = query.limit ?? 10;
+    const unit = query.interval === "hour" ? "1 HOUR" : "1 DAY";
+    const where = `timestamp >= toDateTime(${fromSec}) AND timestamp < toDateTime(${toSec}) AND blob1 = 'pageview'`;
+    const [totals, pages, referrers, series] = await Promise.all([
+      runSql(
+        // visitors = distinct user ids (blob11); requires the cookieId/userId tracker option.
+        `SELECT SUM(_sample_interval) AS views, COUNT(DISTINCT blob11) AS visitors, AVG(double1) AS avgActive FROM ${table} WHERE ${where}`
+      ),
+      runSql(`SELECT blob2 AS path, SUM(_sample_interval) AS views FROM ${table} WHERE ${where} GROUP BY path ORDER BY views DESC LIMIT ${limit}`),
+      runSql(
+        `SELECT blob4 AS referrer, SUM(_sample_interval) AS views FROM ${table} WHERE ${where} AND blob4 != '' GROUP BY referrer ORDER BY views DESC LIMIT ${limit}`
+      ),
+      runSql(
+        `SELECT toStartOfInterval(timestamp, INTERVAL ${unit}) AS bucket, SUM(_sample_interval) AS views FROM ${table} WHERE ${where} GROUP BY bucket ORDER BY bucket ASC`
+      )
+    ]);
+    const total = totals[0];
+    const timeseries = series.map((row) => ({
+      date: row.bucket,
+      views: Number(row.views)
+    }));
+    return {
+      totals: {
+        views: Number(total?.views ?? 0),
+        visitors: total?.visitors ? Number(total.visitors) : void 0,
+        avgActiveSeconds: total?.avgActive ? Math.round(Number(total.avgActive)) : void 0
+      },
+      topPages: pages.map((p) => ({ path: p.path, views: Number(p.views) })),
+      topReferrers: referrers.map((r) => ({ referrer: r.referrer, views: Number(r.views) })),
+      timeseries,
+      // Analytics Engine samples adaptively; counts are already extrapolated.
+      sampled: true
+    };
+  };
+  return { insert, stats };
+};
+
+export { analyticsEngineAdapter };

package/dist/adapters/sql.d.ts

@@ -0,0 +1,382 @@
+import type { Adapter } from "@unifeather/core";
+/**
+ * Drizzle table definition for the events table. Use it with drizzle-kit to
+ * generate migrations, or run {@link CREATE_TABLE_SQL} directly.
+ *
+ * Postgres-first (works with node-postgres, Neon, pglite, Supabase, Timescale).
+ * For SQLite/D1/MySQL, mirror these columns with the matching drizzle core and
+ * pass your table + the right `dialect` to {@link sqlAdapter}.
+ */
+export declare const unifeatherEvents: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "unifeather_events";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "unifeather_events";
+            dataType: "number";
+            columnType: "PgSerial";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        eventId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "event_id";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        ts: import("drizzle-orm/pg-core").PgColumn<{
+            name: "ts";
+            tableName: "unifeather_events";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        hostname: import("drizzle-orm/pg-core").PgColumn<{
+            name: "hostname";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        path: import("drizzle-orm/pg-core").PgColumn<{
+            name: "path";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        referrerHost: import("drizzle-orm/pg-core").PgColumn<{
+            name: "referrer_host";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        language: import("drizzle-orm/pg-core").PgColumn<{
+            name: "language";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        activeSeconds: import("drizzle-orm/pg-core").PgColumn<{
+            name: "active_seconds";
+            tableName: "unifeather_events";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        browserName: import("drizzle-orm/pg-core").PgColumn<{
+            name: "browser_name";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        browserVersion: import("drizzle-orm/pg-core").PgColumn<{
+            name: "browser_version";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        osName: import("drizzle-orm/pg-core").PgColumn<{
+            name: "os_name";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        osVersion: import("drizzle-orm/pg-core").PgColumn<{
+            name: "os_version";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        screenWidth: import("drizzle-orm/pg-core").PgColumn<{
+            name: "screen_width";
+            tableName: "unifeather_events";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        screenHeight: import("drizzle-orm/pg-core").PgColumn<{
+            name: "screen_height";
+            tableName: "unifeather_events";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        country: import("drizzle-orm/pg-core").PgColumn<{
+            name: "country";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "user_id";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sessionId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "session_id";
+            tableName: "unifeather_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        properties: import("drizzle-orm/pg-core").PgColumn<{
+            name: "properties";
+            tableName: "unifeather_events";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>;
+/** Ready-to-run DDL for the events table (Postgres). */
+export declare const CREATE_TABLE_SQL = "\nCREATE TABLE IF NOT EXISTS unifeather_events (\n  id             BIGSERIAL PRIMARY KEY,\n  event_id       TEXT NOT NULL,\n  name           TEXT NOT NULL,\n  ts             TIMESTAMPTZ NOT NULL,\n  hostname       TEXT NOT NULL,\n  path           TEXT NOT NULL,\n  referrer_host  TEXT,\n  language       TEXT,\n  active_seconds INTEGER NOT NULL DEFAULT 0,\n  browser_name   TEXT,\n  browser_version TEXT,\n  os_name        TEXT,\n  os_version     TEXT,\n  screen_width   INTEGER,\n  screen_height  INTEGER,\n  country        TEXT,\n  user_id        TEXT,\n  session_id     TEXT,\n  properties     JSONB\n);\nCREATE INDEX IF NOT EXISTS unifeather_events_ts_idx ON unifeather_events (ts);\nCREATE INDEX IF NOT EXISTS unifeather_events_path_ts_idx ON unifeather_events (path, ts);\n";
+/** SQL dialect of the drizzle `db` — selects the timeseries date-bucket and random-order syntax. */
+export type SqlDialect = "pg" | "sqlite" | "mysql";
+/** Query-side sampling — extrapolate from a sample on very large tables. */
+export interface SamplingOptions {
+    /** Enable sampling. Defaults to true. */
+    readonly enabled?: boolean;
+    /** Row-estimate above which sampling kicks in. Defaults to 1,000,000. */
+    readonly threshold?: number;
+    /** Fraction of rows to scan when sampling (0–1). Defaults to 0.1 (10%). */
+    readonly rate?: number;
+}
+/**
+ * Any drizzle db exposing the query builder + insert. Typed loosely on purpose:
+ * the builder API (`select`/`insert`/`from`/`where`/`groupBy`/…) is identical
+ * across dialects, but drizzle does not unify the per-dialect db classes.
+ */
+export interface DrizzleLike {
+    select(...args: unknown[]): any;
+    insert(...args: unknown[]): any;
+}
+export interface SqlAdapterOptions {
+    readonly db: DrizzleLike;
+    /** Drizzle table object for events. Defaults to the built-in Postgres {@link unifeatherEvents}. */
+    readonly table?: unknown;
+    /** DB dialect — selects date-bucket + random-order SQL. Defaults to "pg". */
+    readonly dialect?: SqlDialect;
+    readonly sampling?: SamplingOptions;
+}
+/**
+ * Universal SQL adapter backed by Drizzle's query builder — one code path for
+ * every dialect drizzle supports. Pass the matching drizzle db, table object and
+ * `dialect`; only the date-bucket and random-order snippets vary per dialect.
+ *
+ * On tables past the configured threshold, aggregations run against a portable
+ * `ORDER BY random()/rand() LIMIT n` sample and counts are scaled back up. The
+ * sample size itself comes from a size estimate: Postgres uses a cheap
+ * `TABLESAMPLE SYSTEM (1)` page sample to avoid a full `count`; other dialects
+ * count the range directly. (TABLESAMPLE can't back the aggregation itself — a
+ * raw-SQL `FROM` is incompatible with the builder's typed column selection.)
+ */
+export declare const sqlAdapter: (options: SqlAdapterOptions) => Adapter;

package/dist/adapters/sql.js

@@ -0,0 +1,147 @@
+import { and, gte, lt, eq, sql, count, countDistinct, avg, desc, isNotNull } from 'drizzle-orm';
+import { pgTable, jsonb, text, integer, timestamp, serial } from 'drizzle-orm/pg-core';
+
+// src/adapters/sql.ts
+var unifeatherEvents = pgTable("unifeather_events", {
+  id: serial("id").primaryKey(),
+  eventId: text("event_id").notNull(),
+  name: text("name").notNull(),
+  ts: timestamp("ts", { withTimezone: true }).notNull(),
+  hostname: text("hostname").notNull(),
+  path: text("path").notNull(),
+  referrerHost: text("referrer_host"),
+  language: text("language"),
+  activeSeconds: integer("active_seconds").notNull().default(0),
+  browserName: text("browser_name"),
+  browserVersion: text("browser_version"),
+  osName: text("os_name"),
+  osVersion: text("os_version"),
+  screenWidth: integer("screen_width"),
+  screenHeight: integer("screen_height"),
+  country: text("country"),
+  userId: text("user_id"),
+  sessionId: text("session_id"),
+  properties: jsonb("properties")
+});
+var CREATE_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS unifeather_events (
+  id             BIGSERIAL PRIMARY KEY,
+  event_id       TEXT NOT NULL,
+  name           TEXT NOT NULL,
+  ts             TIMESTAMPTZ NOT NULL,
+  hostname       TEXT NOT NULL,
+  path           TEXT NOT NULL,
+  referrer_host  TEXT,
+  language       TEXT,
+  active_seconds INTEGER NOT NULL DEFAULT 0,
+  browser_name   TEXT,
+  browser_version TEXT,
+  os_name        TEXT,
+  os_version     TEXT,
+  screen_width   INTEGER,
+  screen_height  INTEGER,
+  country        TEXT,
+  user_id        TEXT,
+  session_id     TEXT,
+  properties     JSONB
+);
+CREATE INDEX IF NOT EXISTS unifeather_events_ts_idx ON unifeather_events (ts);
+CREATE INDEX IF NOT EXISTS unifeather_events_path_ts_idx ON unifeather_events (path, ts);
+`;
+var num = (value) => Number(value ?? 0);
+var randomOrder = (dialect) => dialect === "mysql" ? sql`rand()` : sql`random()`;
+var dateBucket = (dialect, bucket, ts) => {
+  if (dialect === "pg") {
+    const fmt2 = bucket === "hour" ? 'YYYY-MM-DD"T"HH24:00' : "YYYY-MM-DD";
+    return sql`to_char(date_trunc(${bucket}, ${ts}), ${fmt2})`;
+  }
+  const fmt = bucket === "hour" ? "%Y-%m-%dT%H:00" : "%Y-%m-%d";
+  return dialect === "mysql" ? sql`date_format(${ts}, ${fmt})` : sql`strftime(${fmt}, ${ts}, 'unixepoch')`;
+};
+var sqlAdapter = (options) => {
+  const { db } = options;
+  const dialect = options.dialect ?? "pg";
+  const events = options.table ?? unifeatherEvents;
+  const table = events;
+  const enabled = options.sampling?.enabled ?? true;
+  const threshold = options.sampling?.threshold ?? 1e6;
+  const rate = Math.min(Math.max(options.sampling?.rate ?? 0.1, 1e-4), 1);
+  const insert = async (e) => {
+    await db.insert(events).values({
+      eventId: e.eventId,
+      name: e.name,
+      ts: new Date(e.timestamp),
+      hostname: e.hostname,
+      path: e.path,
+      referrerHost: e.referrerHost ?? null,
+      language: e.language ?? null,
+      activeSeconds: e.activeSeconds,
+      browserName: e.browserName ?? null,
+      browserVersion: e.browserVersion ?? null,
+      osName: e.osName ?? null,
+      osVersion: e.osVersion ?? null,
+      screenWidth: e.screenWidth ?? null,
+      screenHeight: e.screenHeight ?? null,
+      country: e.country ?? null,
+      userId: e.userId ?? null,
+      sessionId: e.sessionId ?? null,
+      properties: e.properties ?? null
+    });
+  };
+  const stats = async (query) => {
+    const limit = query.limit ?? 10;
+    const bucket = query.interval === "hour" ? "hour" : "day";
+    const range = and(gte(table.ts, new Date(query.from)), lt(table.ts, new Date(query.to)), eq(table.name, "pageview"));
+    let sampled = false;
+    let scale = 1;
+    let source = events;
+    let cols = table;
+    let where = range;
+    if (enabled) {
+      const size = dialect === "pg" ? num(
+        (await db.select({ n: sql`count(*)::float8 * 100` }).from(sql`${events} TABLESAMPLE SYSTEM (1)`).where(range))[0]?.n
+      ) : num((await db.select({ total: count() }).from(events).where(range))[0]?.total);
+      if (size > threshold) {
+        sampled = true;
+        const n = Math.max(1, Math.round(size * rate));
+        const sub = db.select().from(events).where(range).orderBy(randomOrder(dialect)).limit(n).as("uf_sample");
+        source = sub;
+        cols = sub;
+        where = void 0;
+        scale = size / n;
+      }
+    }
+    const scaled = (value) => Math.round(num(value) * scale);
+    const bucketExpr = dateBucket(dialect, bucket, cols.ts);
+    const [totalsRes, pagesRes, referrersRes, seriesRes] = await Promise.all([
+      db.select({ views: count(), avgActive: avg(cols.activeSeconds), visitors: countDistinct(cols.userId) }).from(source).where(where),
+      db.select({ path: cols.path, views: count() }).from(source).where(where).groupBy(cols.path).orderBy(desc(count())).limit(limit),
+      db.select({ referrer: cols.referrerHost, views: count() }).from(source).where(and(where, isNotNull(cols.referrerHost))).groupBy(cols.referrerHost).orderBy(desc(count())).limit(limit),
+      // Group/order by ordinal: the bucket expression renders differently in
+      // SELECT vs GROUP BY, so referencing it by position keeps them identical.
+      db.select({ date: bucketExpr, views: count() }).from(source).where(where).groupBy(sql`1`).orderBy(sql`1`)
+    ]);
+    const totals = totalsRes[0] ?? {};
+    return {
+      totals: {
+        views: scaled(totals.views),
+        // Distinct visitors = distinct user ids; requires the cookieId/userId
+        // tracker option. Undefined without identified visitors, or when
+        // sampling (distinct counts don't extrapolate from a sample).
+        visitors: sampled || !num(totals.visitors) ? void 0 : num(totals.visitors),
+        avgActiveSeconds: totals.avgActive != null ? Math.round(num(totals.avgActive)) : void 0
+      },
+      topPages: pagesRes.map((r) => ({ path: String(r.path), views: scaled(r.views) })),
+      topReferrers: referrersRes.map((r) => ({
+        referrer: String(r.referrer),
+        views: scaled(r.views)
+      })),
+      timeseries: seriesRes.map((r) => ({ date: String(r.date), views: scaled(r.views) })),
+      sampled,
+      sampleRate: sampled ? rate : void 0
+    };
+  };
+  return { insert, stats };
+};
+
+export { CREATE_TABLE_SQL, sqlAdapter, unifeatherEvents };

package/dist/handler.d.ts

@@ -0,0 +1,22 @@
+import { type Adapter } from "@unifeather/core";
+export interface HandlerOptions {
+    readonly adapter: Adapter;
+    /** Ingest path. Defaults to "/collect". */
+    readonly collectPath?: string;
+    /** Stats path. Defaults to "/api/stats". */
+    readonly statsPath?: string;
+    /**
+     * CORS `Access-Control-Allow-Origin`. `true` reflects the request origin,
+     * a string/array whitelists origins, `false`/omitted disables CORS.
+     */
+    readonly cors?: boolean | string | readonly string[];
+    /** Keep the query string in stored paths. Defaults to false (stripped). */
+    readonly keepQuery?: boolean;
+}
+export type FetchHandler = (request: Request) => Promise<Response>;
+/**
+ * Build a framework-agnostic fetch handler for the tracking endpoint. Works
+ * unchanged on Cloudflare Workers/Pages (`export default { fetch }`) and on
+ * Node via {@link createNodeListener}.
+ */
+export declare const createHandler: (options: HandlerOptions) => FetchHandler;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { HandlerOptions, FetchHandler } from "./handler.js";
+export { createHandler } from "./handler.js";
+export { createNodeListener } from "./node.js";
+export type { Adapter, StatsQuery, StatsResult, TrackingEvent, RawEvent } from "@unifeather/core";

package/dist/index.js

@@ -0,0 +1,108 @@
+import { normalizeEvent } from '@unifeather/core';
+
+// src/handler.ts
+var resolveOrigin = (cors, requestOrigin) => {
+  if (!cors) return void 0;
+  if (cors === true) return requestOrigin ?? "*";
+  const list = typeof cors === "string" ? [cors] : cors;
+  return requestOrigin && list.includes(requestOrigin) ? requestOrigin : void 0;
+};
+var corsHeaders = (origin) => origin ? {
+  "Access-Control-Allow-Origin": origin,
+  "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+  Vary: "Origin"
+} : {};
+var createHandler = (options) => {
+  const { adapter, collectPath = "/collect", statsPath = "/api/stats" } = options;
+  return async (request) => {
+    const url = new URL(request.url);
+    const origin = resolveOrigin(options.cors, request.headers.get("Origin"));
+    const cors = corsHeaders(origin);
+    if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: cors });
+    if (request.method === "POST" && url.pathname === collectPath) {
+      return handleCollect(request, options, cors);
+    }
+    if (request.method === "GET" && url.pathname === statsPath) {
+      return handleStats(url, adapter, cors);
+    }
+    return new Response("Not Found", { status: 404, headers: cors });
+  };
+};
+var handleCollect = async (request, options, cors) => {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return new Response("Bad Request", { status: 400, headers: cors });
+  }
+  const raws = Array.isArray(body) ? body : [body];
+  const now = Date.now();
+  const userAgent = request.headers.get("User-Agent") ?? void 0;
+  const country = request.headers.get("CF-IPCountry") ?? void 0;
+  const context = { now, userAgent, country, stripQuery: !options.keepQuery };
+  const events = raws.map((raw) => normalizeEvent(raw, context));
+  try {
+    if (options.adapter.insertBatch && events.length > 1) {
+      await options.adapter.insertBatch(events);
+    } else {
+      await Promise.all(events.map((event) => options.adapter.insert(event)));
+    }
+  } catch {
+    return new Response("Storage Error", { status: 502, headers: cors });
+  }
+  return new Response(null, { status: 204, headers: cors });
+};
+var parseInterval = (value) => value === "hour" ? "hour" : "day";
+var handleStats = async (url, adapter, cors) => {
+  const params = url.searchParams;
+  const now = Date.now();
+  const query = {
+    from: Number(params.get("from")) || now - 7 * 864e5,
+    to: Number(params.get("to")) || now,
+    limit: Number(params.get("limit")) || 10,
+    interval: parseInterval(params.get("interval"))
+  };
+  try {
+    const result = await adapter.stats(query);
+    return Response.json(result, { headers: cors });
+  } catch {
+    return new Response("Query Error", { status: 502, headers: cors });
+  }
+};
+
+// src/node.ts
+var readBody = (req) => new Promise((resolve, reject) => {
+  const chunks = [];
+  req.on("data", (chunk) => chunks.push(chunk));
+  req.on("end", () => resolve(Buffer.concat(chunks)));
+  req.on("error", reject);
+});
+var toRequest = async (req) => {
+  const host = req.headers.host ?? "localhost";
+  const proto = req.headers["x-forwarded-proto"] ?? "http";
+  const url = `${proto}://${host}${req.url ?? "/"}`;
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === void 0) continue;
+    headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+  }
+  const hasBody = req.method !== "GET" && req.method !== "HEAD";
+  const body = hasBody ? new Uint8Array(await readBody(req)) : void 0;
+  return new Request(url, { method: req.method, headers, body });
+};
+var writeResponse = async (res, response) => {
+  const headers = {};
+  response.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  res.writeHead(response.status, headers);
+  res.end(response.body ? Buffer.from(await response.arrayBuffer()) : void 0);
+};
+var createNodeListener = (handler) => async (req, res) => {
+  const request = await toRequest(req);
+  const response = await handler(request);
+  await writeResponse(res, response);
+};
+
+export { createHandler, createNodeListener };

package/dist/node.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FetchHandler } from "./handler.js";
+/**
+ * Adapt a fetch handler into a `node:http` request listener, so the exact same
+ * endpoint runs on a plain Node server, Express, etc.
+ *
+ * @example
+ * import { createServer } from "node:http";
+ * createServer(createNodeListener(handler)).listen(3000);
+ */
+export declare const createNodeListener: (handler: FetchHandler) => (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@unifeather/server",
+  "version": "0.1.0",
+  "description": "Framework-agnostic tracking endpoint (Web Request→Response) plus storage adapters for Cloudflare Analytics Engine and Drizzle-backed SQL databases.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Dennis Hendricks <dennis@hendricks.rocks>",
+  "keywords": [
+    "analytics",
+    "privacy",
+    "web-analytics",
+    "tracking",
+    "drizzle",
+    "cloudflare",
+    "analytics-engine",
+    "edge"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dennishendricks/unifeather.git",
+    "directory": "packages/server"
+  },
+  "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"
+    },
+    "./analytics-engine": {
+      "types": "./dist/adapters/analytics-engine.d.ts",
+      "import": "./dist/adapters/analytics-engine.js"
+    },
+    "./sql": {
+      "types": "./dist/adapters/sql.d.ts",
+      "import": "./dist/adapters/sql.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepublishOnly": "bun run build",
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@unifeather/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.45.2"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260715.1",
+    "@electric-sql/pglite": "^0.5.4",
+    "@types/node": "^26.1.1",
+    "drizzle-orm": "^0.45.2",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}