@nodewrite-labs/analytics-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nodewrite-hq
+
+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

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @nodewrite-labs/analytics-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Records page views and named clicks. The browser sends an event. The server checks it and writes it through a store. Country and city come from the caller. A value on the JSON body is ignored.
+
+`payload` and `pg` are optional peer dependencies. Install one only when that entry is used.
+
+## Entries
+
+| Import                              | What it exports                                                                                           |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@nodewrite-labs/analytics-sdk`          | Event types, module flags, `AnalyticsEventStore`, `MemoryAnalyticsEventStore`, `summarizeAnalyticsEvents` |
+| `@nodewrite-labs/analytics-sdk/client`   | `startAnalytics`, `recordNamedClick`                                                                      |
+| `@nodewrite-labs/analytics-sdk/server`   | `recordAnalyticsEvent`, `readRequestGeo`                                                                  |
+| `@nodewrite-labs/analytics-sdk/postgres` | `PostgresAnalyticsEventStore`, `schema.sql`                                                               |
+| `@nodewrite-labs/analytics-sdk/payload`  | Payload collection, ingest, and admin screen                                                              |
+
+## Events
+
+A view is `{ type: "view", path, locale, sessionId }`.
+
+A duration is `{ type: "duration", id, durationSeconds }`. A duration is kept only inside 0..1800 seconds.
+
+A click is `{ type: "click", path, locale, sessionId, eventName }`. `eventName` is lowercase letters, digits, and underscores.
+
+`path` starts with `/`. The query string is removed before the row is stored.
+
+## Modules
+
+`country`, `city`, `sessions`, and `clicks`. A module that is off stores null for its field. The summary omits that breakdown.
+
+## Browser
+
+Call `startAnalytics` after the visitor has consented. `enabled: false` sends nothing.
+
+```ts
+import { startAnalytics } from "@nodewrite-labs/analytics-sdk/client";
+
+startAnalytics({
+  endpoint: "/analytics/events",
+  enabled: true,
+  locale: "en",
+  sessions: true,
+  clicks: true,
+});
+```
+
+A named click is an element with `data-analytics`. The attribute value is the event name. Clicks are sent only when `clicks` is true.
+
+```html
+<button type="button" data-analytics="cta_clicked">Continue</button>
+```
+
+`recordNamedClick(name)` sends one named click when clicks are on.
+
+## Server
+
+`recordAnalyticsEvent` checks one event and writes it through an `AnalyticsEventStore`.
+
+Pass `{ body, country, city }`, or `{ request, country, city }` when `request` is a Fetch `Request` and `body` is omitted. Country and city are those properties. `readRequestGeo` reads the same two properties.
+
+```ts
+import { recordAnalyticsEvent } from "@nodewrite-labs/analytics-sdk/server";
+
+const result = await recordAnalyticsEvent(
+  { body, country, city },
+  {
+    store,
+    options: {
+      enabled: true,
+      modules: { country: true, city: true, sessions: true, clicks: true },
+    },
+  },
+);
+```
+
+`enabled: false` writes nothing and returns status 204. A stored view or click returns status 200 and `{ id }`. A recorded duration returns 204. An event that cannot be stored returns 400.
+
+## Store
+
+`AnalyticsEventStore` is three methods: `insertAnalyticsEvent`, `recordAnalyticsDuration`, and `summarizeAnalytics`.
+
+`MemoryAnalyticsEventStore` keeps the rows in memory. `PostgresAnalyticsEventStore` reads and writes `analytics_event`. The SQL shipped with this package is `src/postgres/schema.sql`:
+
+```sql
+CREATE TABLE IF NOT EXISTS analytics_event (
+  id uuid primary key,
+  kind text not null,
+  path text not null,
+  locale text,
+  occurred_at timestamptz not null,
+  duration_seconds integer,
+  country text,
+  city text,
+  session_id text,
+  event_name text
+);
+```
+
+`applyAnalyticsSchema(pool)` runs that file. `summarizeAnalyticsEvents` groups the stored rows for one time range: total views, average duration, and counts by path. Country, city, sessions, and named clicks are included only when that module is on.

package/dist/chunk-F7BY2JQ3.js

@@ -0,0 +1,9 @@
+// src/core/event-kind.ts
+var AnalyticsEventKind = {
+  VIEW: "view",
+  CLICK: "click"
+};
+
+export {
+  AnalyticsEventKind
+};

package/dist/chunk-GVOESWHZ.js

@@ -0,0 +1,270 @@
+import {
+  acceptDurationSeconds,
+  summarizeAnalyticsEvents
+} from "./chunk-Q4JRXZ6M.js";
+import {
+  AnalyticsEventKind
+} from "./chunk-F7BY2JQ3.js";
+
+// src/payload/access.ts
+var deny = () => false;
+function analyticsEventsAccess(read) {
+  return {
+    read: (args) => read ? read(args) : Boolean(args.req.user),
+    create: deny,
+    update: deny,
+    delete: deny
+  };
+}
+
+// src/payload/admin/sections.ts
+function adminSections(summary, modules, query) {
+  const blocks = [
+    {
+      kind: "totals",
+      totalViews: summary.totalViews,
+      averageDurationSeconds: summary.averageDurationSeconds
+    },
+    { kind: "paths", rows: summary.byPath }
+  ];
+  if (modules.country) blocks.push({ kind: "countries", rows: summary.byCountry ?? [] });
+  if (modules.city) blocks.push({ kind: "cities", rows: summary.byCity ?? [] });
+  if (modules.clicks) blocks.push({ kind: "namedClicks", rows: summary.byEventName ?? [] });
+  if (modules.sessions) {
+    if (sessionText(query.session)) {
+      blocks.push({ kind: "trail", events: orderedEvents(summary.events ?? []) });
+    } else {
+      blocks.push({ kind: "sessions", rows: summary.sessions ?? [] });
+    }
+  }
+  return blocks;
+}
+function sessionText(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+function orderedEvents(events) {
+  return events.slice().sort((left, right) => {
+    if (left.occurredAt < right.occurredAt) return -1;
+    if (left.occurredAt > right.occurredAt) return 1;
+    if (left.id < right.id) return -1;
+    if (left.id > right.id) return 1;
+    return 0;
+  });
+}
+
+// src/payload/collection.ts
+var ANALYTICS_EVENTS_SLUG = "analytics-events";
+function analyticsEventsCollection(read) {
+  return {
+    slug: ANALYTICS_EVENTS_SLUG,
+    labels: {
+      singular: "Analytics event",
+      plural: "Analytics events"
+    },
+    admin: {
+      hidden: true
+    },
+    timestamps: false,
+    versions: false,
+    access: analyticsEventsAccess(read),
+    fields: [
+      {
+        name: "kind",
+        type: "select",
+        required: true,
+        options: [
+          { label: "View", value: "view" },
+          { label: "Click", value: "click" }
+        ]
+      },
+      {
+        name: "path",
+        type: "text",
+        required: true,
+        maxLength: 2048
+      },
+      {
+        name: "locale",
+        type: "text",
+        maxLength: 35
+      },
+      {
+        name: "occurredAt",
+        type: "date",
+        required: true
+      },
+      {
+        name: "durationSeconds",
+        type: "number",
+        min: 0,
+        max: 1800
+      },
+      {
+        name: "country",
+        type: "text",
+        maxLength: 2
+      },
+      {
+        name: "city",
+        type: "text",
+        maxLength: 80
+      },
+      {
+        name: "sessionId",
+        type: "text",
+        maxLength: 36
+      },
+      {
+        name: "eventName",
+        type: "text",
+        maxLength: 64
+      }
+    ]
+  };
+}
+
+// src/payload/store.ts
+var PayloadAnalyticsEventStore = class {
+  constructor(payload, modules) {
+    this.payload = payload;
+    this.modules = modules;
+  }
+  payload;
+  modules;
+  async insertAnalyticsEvent(event, occurredAt) {
+    const data = {
+      kind: event.kind,
+      path: event.path,
+      locale: event.locale,
+      occurredAt,
+      durationSeconds: event.durationSeconds,
+      country: this.modules.country ? event.country : null,
+      city: this.modules.city ? event.city : null,
+      sessionId: this.modules.sessions ? event.sessionId : null,
+      eventName: this.modules.clicks ? event.eventName : null
+    };
+    const doc = await this.payload.create({
+      collection: ANALYTICS_EVENTS_SLUG,
+      data,
+      overrideAccess: true
+    });
+    const stored = mapDoc(doc, occurredAt);
+    if (!stored) throw new Error("analytics-events create did not return a row");
+    return stored;
+  }
+  async recordAnalyticsDuration(id, durationSeconds) {
+    const accepted = acceptDurationSeconds(durationSeconds);
+    if (accepted === null) return;
+    await this.payload.update({
+      collection: ANALYTICS_EVENTS_SLUG,
+      where: {
+        and: [{ id: { equals: id } }, { kind: { equals: AnalyticsEventKind.VIEW } }]
+      },
+      data: { durationSeconds: accepted },
+      overrideAccess: true
+    });
+  }
+  async summarizeAnalytics(query, modules) {
+    const result = await this.payload.find({
+      collection: ANALYTICS_EVENTS_SLUG,
+      where: summaryWhere(query),
+      pagination: false,
+      depth: 0,
+      overrideAccess: true
+    });
+    const rows = [];
+    for (const doc of result.docs) {
+      const mapped = mapDoc(doc);
+      if (mapped) rows.push(mapped);
+    }
+    return summarizeAnalyticsEvents(rows, query, modules);
+  }
+};
+function summaryWhere(query) {
+  const and = [
+    { occurredAt: { greater_than_equal: query.from } },
+    { occurredAt: { less_than_equal: query.to } }
+  ];
+  if (query.country !== null) and.push({ country: { equals: query.country } });
+  if (query.path !== null) and.push({ path: { equals: query.path } });
+  if (query.sessionId !== null) and.push({ sessionId: { equals: query.sessionId } });
+  return { and };
+}
+function mapDoc(doc, occurredAtFallback) {
+  if (!isRecord(doc)) return null;
+  const kind = doc.kind;
+  const path = doc.path;
+  if (!isId(doc.id) || kind !== AnalyticsEventKind.VIEW && kind !== AnalyticsEventKind.CLICK) {
+    return null;
+  }
+  if (typeof path !== "string") return null;
+  const occurredAt = timeText(doc.occurredAt) ?? occurredAtFallback ?? null;
+  if (occurredAt === null) return null;
+  return {
+    id: String(doc.id),
+    kind,
+    path,
+    locale: textOrNull(doc.locale),
+    occurredAt,
+    durationSeconds: numberOrNull(doc.durationSeconds),
+    country: textOrNull(doc.country),
+    city: textOrNull(doc.city),
+    sessionId: textOrNull(doc.sessionId),
+    eventName: textOrNull(doc.eventName)
+  };
+}
+function isId(value) {
+  return typeof value === "string" || typeof value === "number";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function textOrNull(value) {
+  return typeof value === "string" ? value : null;
+}
+function numberOrNull(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const numeric = Number(value);
+    if (Number.isFinite(numeric)) return numeric;
+  }
+  return null;
+}
+function timeText(value) {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+  if (typeof value !== "string" || value.length === 0) return null;
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) return null;
+  return parsed.toISOString();
+}
+
+// src/payload/stored-modules.ts
+var ANALYTICS_CUSTOM_KEY = "analytics";
+function analyticsModulesFromConfig(config) {
+  const stored = config.custom?.[ANALYTICS_CUSTOM_KEY];
+  if (!isAnalyticsCustom(stored)) {
+    return { country: false, city: false, sessions: false, clicks: false };
+  }
+  return stored.modules;
+}
+function isAnalyticsCustom(value) {
+  if (typeof value !== "object" || value === null || !("modules" in value)) return false;
+  const modules = value.modules;
+  if (typeof modules !== "object" || modules === null) return false;
+  return hasBoolean(modules, "country") && hasBoolean(modules, "city") && hasBoolean(modules, "sessions") && hasBoolean(modules, "clicks");
+}
+function hasBoolean(value, key) {
+  const record = value;
+  return typeof record[key] === "boolean";
+}
+
+export {
+  analyticsEventsAccess,
+  adminSections,
+  analyticsEventsCollection,
+  PayloadAnalyticsEventStore,
+  ANALYTICS_CUSTOM_KEY,
+  analyticsModulesFromConfig
+};

package/dist/chunk-GWOVVKP3.js

@@ -0,0 +1,179 @@
+import {
+  AnalyticsEventKind
+} from "./chunk-F7BY2JQ3.js";
+
+// src/server/read-request-geo.ts
+function readRequestGeo(request) {
+  const fields = request;
+  return {
+    country: textField(fields.country),
+    city: textField(fields.city)
+  };
+}
+function textField(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+
+// src/server/record-analytics-event.ts
+var PATH_MAX = 2048;
+var LOCALE_MAX = 35;
+var SESSION_ID_MAX = 36;
+var EVENT_NAME_MAX = 64;
+var COUNTRY_MAX = 8;
+var CITY_MAX = 80;
+var DURATION_ID_MAX = 64;
+var EVENT_NAME = /^[a-z0-9_]+$/;
+async function recordAnalyticsEvent(request, deps) {
+  if (!deps.options.enabled) return { status: 204, body: null };
+  const incoming = await incomingRequest(request);
+  const body = incoming.body;
+  if (!isRecord(body) || typeof body.type !== "string") return invalid();
+  if (body.type === "view") return recordView(body, incoming, deps);
+  if (body.type === "duration") return recordDuration(body, deps);
+  if (body.type === "click") return recordClick(body, incoming, deps);
+  return invalid();
+}
+async function recordView(body, request, deps) {
+  const parsed = parseLocation(body);
+  if (!parsed) return invalid();
+  const sessionId = sessionFor(body.sessionId, deps);
+  if (sessionId === void 0) return invalid();
+  const accepted = {
+    type: "view",
+    path: parsed.path,
+    locale: parsed.locale,
+    sessionId
+  };
+  const stored = await deps.store.insertAnalyticsEvent(newEvent(accepted, request, deps), clock(deps));
+  return { status: 200, body: { id: stored.id } };
+}
+async function recordDuration(body, deps) {
+  if (typeof body.id !== "string" || body.id.length === 0 || body.id.length > DURATION_ID_MAX) {
+    return invalid();
+  }
+  if (typeof body.durationSeconds !== "number") return invalid();
+  const accepted = {
+    type: "duration",
+    id: body.id,
+    durationSeconds: body.durationSeconds
+  };
+  await deps.store.recordAnalyticsDuration(accepted.id, accepted.durationSeconds);
+  return { status: 204, body: null };
+}
+async function recordClick(body, request, deps) {
+  if (!deps.options.modules.clicks) return { status: 204, body: null };
+  const parsed = parseLocation(body);
+  const eventName = body.eventName;
+  if (!parsed || !validEventName(eventName)) return invalid();
+  const sessionId = sessionFor(body.sessionId, deps);
+  if (sessionId === void 0) return invalid();
+  const accepted = {
+    type: "click",
+    path: parsed.path,
+    locale: parsed.locale,
+    sessionId,
+    eventName
+  };
+  const stored = await deps.store.insertAnalyticsEvent(newEvent(accepted, request, deps), clock(deps));
+  return { status: 200, body: { id: stored.id } };
+}
+function newEvent(body, request, deps) {
+  const modules = deps.options.modules;
+  const geo = readGeo(request);
+  return {
+    kind: body.type === "click" ? AnalyticsEventKind.CLICK : AnalyticsEventKind.VIEW,
+    path: body.path,
+    locale: body.locale,
+    durationSeconds: null,
+    country: modules.country ? geo.country : null,
+    city: modules.city ? geo.city : null,
+    sessionId: modules.sessions ? body.sessionId : null,
+    eventName: body.type === "click" ? body.eventName : null
+  };
+}
+async function incomingRequest(request) {
+  if (isWebRequest(request)) {
+    return { body: await readJsonBody(request), headers: request.headers };
+  }
+  const source = request.request;
+  const body = request.body !== void 0 ? request.body : source ? await readJsonBody(source) : void 0;
+  return {
+    body,
+    headers: request.headers ?? source?.headers,
+    country: request.country,
+    city: request.city
+  };
+}
+function isWebRequest(request) {
+  return typeof Request !== "undefined" && request instanceof Request;
+}
+async function readJsonBody(request) {
+  try {
+    return await request.json();
+  } catch {
+    return void 0;
+  }
+}
+function readGeo(request) {
+  const read = readRequestGeo(request);
+  return {
+    country: boundedText(read.country, COUNTRY_MAX),
+    city: boundedText(read.city, CITY_MAX)
+  };
+}
+function parseLocation(body) {
+  if (typeof body.path !== "string") return null;
+  const path = normalizePath(body.path);
+  if (path === null) return null;
+  const locale = readLocale(body.locale);
+  if (locale === void 0) return null;
+  return { path, locale };
+}
+function sessionFor(value, deps) {
+  if (!deps.options.modules.sessions) return null;
+  if (value === void 0 || value === null || value === "") return null;
+  if (typeof value !== "string" || value.length > SESSION_ID_MAX) return void 0;
+  return value;
+}
+function readLocale(value) {
+  if (value === void 0 || value === null || value === "") return null;
+  if (typeof value !== "string" || value.length > LOCALE_MAX) return void 0;
+  return value;
+}
+function normalizePath(path) {
+  if (!path.startsWith("/")) return null;
+  if (path.includes("://")) return null;
+  const queryIndex = path.indexOf("?");
+  const withoutQuery = queryIndex === -1 ? path : path.slice(0, queryIndex);
+  const hashIndex = withoutQuery.indexOf("#");
+  const bare = hashIndex === -1 ? withoutQuery : withoutQuery.slice(0, hashIndex);
+  if (bare.length === 0 || bare.length > PATH_MAX) return null;
+  if (!bare.startsWith("/")) return null;
+  if (/[\u0000-\u001F\u007F]/.test(bare)) return null;
+  return bare;
+}
+function validEventName(value) {
+  return typeof value === "string" && value.length <= EVENT_NAME_MAX && EVENT_NAME.test(value);
+}
+function boundedText(value, max) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > max) return null;
+  return trimmed;
+}
+function clock(deps) {
+  return deps.now ? deps.now() : (/* @__PURE__ */ new Date()).toISOString();
+}
+function invalid() {
+  return { status: 400, body: null };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export {
+  readRequestGeo,
+  recordAnalyticsEvent
+};