@nodewrite-labs/analytics-sdk 0.2.0 → 0.3.0

package/dist/chunk-MOCOVYQK.js

@@ -0,0 +1,108 @@
+// src/core/period.ts
+var AnalyticsPeriod = {
+  LAST_24_HOURS: "24h",
+  LAST_7_DAYS: "7d",
+  LAST_30_DAYS: "30d",
+  LAST_12_MONTHS: "12m"
+};
+var ANALYTICS_PERIODS = Object.values(AnalyticsPeriod);
+var DEFAULT_ANALYTICS_PERIOD = AnalyticsPeriod.LAST_7_DAYS;
+var AnalyticsBucketUnit = {
+  HOUR: "hour",
+  DAY: "day",
+  MONTH: "month"
+};
+var PERIOD_BUCKETS = {
+  [AnalyticsPeriod.LAST_24_HOURS]: { unit: AnalyticsBucketUnit.HOUR, count: 24 },
+  [AnalyticsPeriod.LAST_7_DAYS]: { unit: AnalyticsBucketUnit.DAY, count: 7 },
+  [AnalyticsPeriod.LAST_30_DAYS]: { unit: AnalyticsBucketUnit.DAY, count: 30 },
+  [AnalyticsPeriod.LAST_12_MONTHS]: { unit: AnalyticsBucketUnit.MONTH, count: 12 }
+};
+function isAnalyticsPeriod(value) {
+  return typeof value === "string" && ANALYTICS_PERIODS.includes(value);
+}
+function assertTimeZone(timeZone) {
+  zonedFormatter(timeZone);
+}
+function analyticsPeriodRange(period, now, timeZone) {
+  const { unit, count } = PERIOD_BUCKETS[period];
+  const wall = zonedParts(now.getTime(), timeZone);
+  const starts = [];
+  for (let back = count - 1; back >= -1; back -= 1) {
+    starts.push(wallToInstant(bucketWallStart(unit, wall, back), timeZone));
+  }
+  const buckets = [];
+  for (let index = 0; index < count; index += 1) {
+    buckets.push({ start: iso(starts[index]), end: iso(starts[index + 1]) });
+  }
+  return {
+    period,
+    unit,
+    from: iso(starts[0]),
+    to: now.toISOString(),
+    buckets
+  };
+}
+function bucketWallStart(unit, wall, back) {
+  if (unit === AnalyticsBucketUnit.HOUR) {
+    return Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour - back);
+  }
+  if (unit === AnalyticsBucketUnit.DAY) {
+    return Date.UTC(wall.year, wall.month - 1, wall.day - back);
+  }
+  return Date.UTC(wall.year, wall.month - 1 - back, 1);
+}
+function wallToInstant(wall, timeZone) {
+  const guess = wall - zoneOffsetMs(wall, timeZone);
+  return wall - zoneOffsetMs(guess, timeZone);
+}
+function zoneOffsetMs(instant, timeZone) {
+  const parts = zonedParts(instant, timeZone);
+  const asUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+  return asUtc - Math.floor(instant / 1e3) * 1e3;
+}
+var formatters = /* @__PURE__ */ new Map();
+function zonedFormatter(timeZone) {
+  const cached = formatters.get(timeZone);
+  if (cached) return cached;
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+  formatters.set(timeZone, formatter);
+  return formatter;
+}
+function zonedParts(instant, timeZone) {
+  const parts = {};
+  for (const part of zonedFormatter(timeZone).formatToParts(new Date(instant))) {
+    if (part.type !== "literal") parts[part.type] = Number(part.value);
+  }
+  return {
+    year: parts.year ?? 0,
+    month: parts.month ?? 1,
+    day: parts.day ?? 1,
+    hour: parts.hour ?? 0,
+    minute: parts.minute ?? 0,
+    second: parts.second ?? 0
+  };
+}
+function iso(instant) {
+  if (instant === void 0) throw new RangeError("A period bucket has no start");
+  return new Date(instant).toISOString();
+}
+
+export {
+  AnalyticsPeriod,
+  ANALYTICS_PERIODS,
+  DEFAULT_ANALYTICS_PERIOD,
+  AnalyticsBucketUnit,
+  isAnalyticsPeriod,
+  assertTimeZone,
+  analyticsPeriodRange
+};

package/dist/{chunk-GVOESWHZ.js → chunk-QPHMFHRE.js}

@@ -1,7 +1,7 @@
 import {
   acceptDurationSeconds,
   summarizeAnalyticsEvents
-} from "./chunk-Q4JRXZ6M.js";
+} from "./chunk-YAC3MRH3.js";
 import {
   AnalyticsEventKind
 } from "./chunk-F7BY2JQ3.js";
@@ -17,42 +17,85 @@ function analyticsEventsAccess(read) {
   };
 }
 
-// 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 ?? [] });
-    }
+// src/payload/admin/translations.ts
+var ANALYTICS_TRANSLATION_NAMESPACE = "analytics";
+var ENGLISH_ANALYTICS_LABELS = {
+  navGroup: "Statistics",
+  navLabel: "Analytics",
+  title: "Analytics",
+  period: "Period",
+  period_24h: "Last 24 hours",
+  period_7d: "Last 7 days",
+  period_30d: "Last 30 days",
+  period_12m: "Last 12 months",
+  country: "Country",
+  allCountries: "All countries",
+  views: "Views",
+  averageTime: "Average time on page",
+  clicks: "Clicks",
+  viewsOverTime: "Views over time",
+  topPages: "Top pages",
+  allPages: "All pages",
+  showAllPages: "Show all pages",
+  showTopPages: "Show top pages only",
+  page: "Page",
+  pageFilter: "Page: {{path}}",
+  clearFilter: "Clear",
+  countries: "Countries",
+  cities: "Cities",
+  city: "City",
+  event: "Event",
+  count: "Count",
+  sessions: "Sessions",
+  session: "Session",
+  started: "Started",
+  pages: "Pages",
+  sessionEvents: "Session events",
+  allSessions: "All sessions",
+  time: "Time",
+  kind: "Kind",
+  kindView: "View",
+  kindClick: "Click",
+  empty: "Nothing in this period."
+};
+function withAnalyticsTranslations(i18n, translations = {}) {
+  const existing = i18n?.translations ?? {};
+  const languages = /* @__PURE__ */ new Set([
+    "en",
+    ...Object.keys(i18n?.supportedLanguages ?? {}),
+    ...Object.keys(translations)
+  ]);
+  const merged = { ...existing };
+  for (const language of languages) {
+    const current = existing[language] ?? {};
+    const host = translations[language] ?? {};
+    merged[language] = {
+      ...current,
+      [ANALYTICS_TRANSLATION_NAMESPACE]: {
+        ...ENGLISH_ANALYTICS_LABELS,
+        ...host,
+        events: { ...host.events }
+      }
+    };
   }
-  return blocks;
+  return { ...i18n, translations: merged };
 }
-function sessionText(value) {
-  if (typeof value !== "string") return null;
-  const trimmed = value.trim();
-  return trimmed.length === 0 ? null : trimmed;
+function analyticsLabel(t, key, vars) {
+  return t(`${ANALYTICS_TRANSLATION_NAMESPACE}:${key}`, vars);
 }
-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;
-  });
+function analyticsEventLabel(translations, eventName) {
+  const namespace = property(translations, ANALYTICS_TRANSLATION_NAMESPACE);
+  const label = property(property(namespace, "events"), eventName);
+  return typeof label === "string" && label.length > 0 ? label : eventName;
 }
+function property(value, key) {
+  if (typeof value !== "object" || value === null) return void 0;
+  return value[key];
+}
+
+// src/payload/admin/component-paths.ts
+var ANALYTICS_FILTERS_PATH = "@nodewrite-labs/analytics-sdk/payload/admin-filters#AnalyticsFilters";
+var ANALYTICS_FILTERS_DEPENDENCY = "nodewriteAnalyticsFilters";
 
 // src/payload/collection.ts
 var ANALYTICS_EVENTS_SLUG = "analytics-events";
@@ -242,29 +285,42 @@ function timeText(value) {
 
 // src/payload/stored-modules.ts
 var ANALYTICS_CUSTOM_KEY = "analytics";
-function analyticsModulesFromConfig(config) {
+var DEFAULT_ANALYTICS_TIME_ZONE = "UTC";
+var MODULES_OFF = { country: false, city: false, sessions: false, clicks: false };
+function analyticsAdminSettingsFromConfig(config) {
   const stored = config.custom?.[ANALYTICS_CUSTOM_KEY];
-  if (!isAnalyticsCustom(stored)) {
-    return { country: false, city: false, sessions: false, clicks: false };
+  if (!isRecord2(stored) || !isModules(stored.modules)) {
+    return { modules: MODULES_OFF, timeZone: DEFAULT_ANALYTICS_TIME_ZONE, formatLocales: {} };
   }
-  return stored.modules;
+  return {
+    modules: stored.modules,
+    timeZone: typeof stored.timeZone === "string" ? stored.timeZone : DEFAULT_ANALYTICS_TIME_ZONE,
+    formatLocales: isStringRecord(stored.formatLocales) ? stored.formatLocales : {}
+  };
+}
+function isModules(value) {
+  if (!isRecord2(value)) return false;
+  return typeof value.country === "boolean" && typeof value.city === "boolean" && typeof value.sessions === "boolean" && typeof value.clicks === "boolean";
 }
-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 isStringRecord(value) {
+  return isRecord2(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
-function hasBoolean(value, key) {
-  const record = value;
-  return typeof record[key] === "boolean";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 export {
   analyticsEventsAccess,
-  adminSections,
+  ENGLISH_ANALYTICS_LABELS,
+  withAnalyticsTranslations,
+  analyticsLabel,
+  analyticsEventLabel,
+  ANALYTICS_FILTERS_PATH,
+  ANALYTICS_FILTERS_DEPENDENCY,
+  ANALYTICS_EVENTS_SLUG,
   analyticsEventsCollection,
   PayloadAnalyticsEventStore,
   ANALYTICS_CUSTOM_KEY,
-  analyticsModulesFromConfig
+  DEFAULT_ANALYTICS_TIME_ZONE,
+  analyticsAdminSettingsFromConfig
 };

package/dist/{chunk-Q4JRXZ6M.js → chunk-YAC3MRH3.js}

@@ -20,6 +20,9 @@ function summarizeAnalyticsEvents(rows, query, modules) {
     averageDurationSeconds: meanDuration(views),
     byPath: groupByPath(views)
   };
+  if (query.buckets) {
+    summary.viewsOverTime = countViewsByBucket(views, query.buckets);
+  }
   if (modules.country) {
     summary.byCountry = groupByCountry(views);
   }
@@ -61,6 +64,17 @@ function meanDuration(views) {
   if (count === 0) return 0;
   return total / count;
 }
+function countViewsByBucket(views, buckets) {
+  const counts = buckets.map(() => 0);
+  const ends = buckets.map((bucket) => Date.parse(bucket.end));
+  const starts = buckets.map((bucket) => Date.parse(bucket.start));
+  for (const view of views) {
+    const at = Date.parse(view.occurredAt);
+    const index = starts.findIndex((start, position) => at >= start && at < (ends[position] ?? start));
+    if (index >= 0) counts[index] = (counts[index] ?? 0) + 1;
+  }
+  return buckets.map((bucket, index) => ({ start: bucket.start, views: counts[index] ?? 0 }));
+}
 function groupByPath(views) {
   const groups = /* @__PURE__ */ new Map();
   for (const view of views) {

package/dist/client/index.js

@@ -199,7 +199,9 @@ async function postJson(url, body) {
   return fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body)
+    body: JSON.stringify(body),
+    // A tel: or mailto: click can hand the page to another app before the request finishes.
+    keepalive: true
   });
 }
 async function readViewId(response) {

package/dist/{event-store-BH-ZR3yD.d.ts → event-store-BkSuP4ZE.d.ts}

@@ -21,16 +21,55 @@ interface StoredAnalyticsEvent extends NewAnalyticsEvent {
     occurredAt: string;
 }
 
+declare const AnalyticsPeriod: {
+    readonly LAST_24_HOURS: "24h";
+    readonly LAST_7_DAYS: "7d";
+    readonly LAST_30_DAYS: "30d";
+    readonly LAST_12_MONTHS: "12m";
+};
+type AnalyticsPeriod = (typeof AnalyticsPeriod)[keyof typeof AnalyticsPeriod];
+declare const ANALYTICS_PERIODS: readonly AnalyticsPeriod[];
+declare const DEFAULT_ANALYTICS_PERIOD: AnalyticsPeriod;
+declare const AnalyticsBucketUnit: {
+    readonly HOUR: "hour";
+    readonly DAY: "day";
+    readonly MONTH: "month";
+};
+type AnalyticsBucketUnit = (typeof AnalyticsBucketUnit)[keyof typeof AnalyticsBucketUnit];
+/** One step of the chart. `start` is inclusive and `end` exclusive, both ISO instants. */
+interface AnalyticsBucket {
+    start: string;
+    end: string;
+}
+interface AnalyticsPeriodRange {
+    period: AnalyticsPeriod;
+    unit: AnalyticsBucketUnit;
+    from: string;
+    to: string;
+    buckets: AnalyticsBucket[];
+}
+/**
+ * The period that ends now: the current hour, day or month plus the ones before it, counted on
+ * the wall clock of `timeZone`, so a day starts at that zone's midnight.
+ */
+declare function analyticsPeriodRange(period: AnalyticsPeriod, now: Date, timeZone: string): AnalyticsPeriodRange;
+
 interface AnalyticsSummaryQuery {
     from: string;
     to: string;
     country: string | null;
     path: string | null;
     sessionId: string | null;
+    /** When set, the summary counts views per bucket in `viewsOverTime`. */
+    buckets?: readonly AnalyticsBucket[];
 }
 interface AnalyticsSummary {
     totalViews: number;
     averageDurationSeconds: number;
+    viewsOverTime?: {
+        start: string;
+        views: number;
+    }[];
     byPath: {
         path: string;
         views: number;
@@ -68,5 +107,5 @@ interface AnalyticsEventStore {
     summarizeAnalytics(query: AnalyticsSummaryQuery, modules: AnalyticsModules): Promise<AnalyticsSummary>;
 }
 
-export { AnalyticsEventKind as c };
-export type { AnalyticsSummaryQuery as A, NewAnalyticsEvent as N, StoredAnalyticsEvent as S, AnalyticsSummary as a, AnalyticsEventStore as b };
+export { DEFAULT_ANALYTICS_PERIOD as D, ANALYTICS_PERIODS as c, AnalyticsBucketUnit as e, AnalyticsEventKind as f, AnalyticsPeriod as g, analyticsPeriodRange as i };
+export type { AnalyticsSummaryQuery as A, NewAnalyticsEvent as N, StoredAnalyticsEvent as S, AnalyticsSummary as a, AnalyticsEventStore as b, AnalyticsBucket as d, AnalyticsPeriodRange as h };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as StoredAnalyticsEvent, A as AnalyticsSummaryQuery, a as AnalyticsSummary, b as AnalyticsEventStore, N as NewAnalyticsEvent } from './event-store-BH-ZR3yD.js';
-export { c as AnalyticsEventKind } from './event-store-BH-ZR3yD.js';
+import { S as StoredAnalyticsEvent, A as AnalyticsSummaryQuery, a as AnalyticsSummary, b as AnalyticsEventStore, N as NewAnalyticsEvent } from './event-store-BkSuP4ZE.js';
+export { c as ANALYTICS_PERIODS, d as AnalyticsBucket, e as AnalyticsBucketUnit, f as AnalyticsEventKind, g as AnalyticsPeriod, h as AnalyticsPeriodRange, D as DEFAULT_ANALYTICS_PERIOD, i as analyticsPeriodRange } from './event-store-BkSuP4ZE.js';
 import { a as AnalyticsModules } from './options-Dpx2vs4R.js';
 export { A as AnalyticsClientConfig, b as AnalyticsServerOptions, R as ReadGeoFromHeaders, c as RequestGeo } from './options-Dpx2vs4R.js';
 export { A as AnalyticsEventBody } from './event-body-fpV2mYpY.js';

package/dist/index.js

@@ -1,7 +1,14 @@
+import {
+  ANALYTICS_PERIODS,
+  AnalyticsBucketUnit,
+  AnalyticsPeriod,
+  DEFAULT_ANALYTICS_PERIOD,
+  analyticsPeriodRange
+} from "./chunk-MOCOVYQK.js";
 import {
   acceptDurationSeconds,
   summarizeAnalyticsEvents
-} from "./chunk-Q4JRXZ6M.js";
+} from "./chunk-YAC3MRH3.js";
 import {
   AnalyticsEventKind
 } from "./chunk-F7BY2JQ3.js";
@@ -42,8 +49,13 @@ var MemoryAnalyticsEventStore = class {
   }
 };
 export {
+  ANALYTICS_PERIODS,
+  AnalyticsBucketUnit,
   AnalyticsEventKind,
+  AnalyticsPeriod,
+  DEFAULT_ANALYTICS_PERIOD,
   MemoryAnalyticsEventStore,
   acceptDurationSeconds,
+  analyticsPeriodRange,
   summarizeAnalyticsEvents
 };

package/dist/payload/admin-filters.d.ts

@@ -0,0 +1,24 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** A type alias, not an interface, so it fits Payload's index-signature `Option`. */
+type AnalyticsFilterOption = {
+    value: string;
+    label: string;
+};
+interface AnalyticsFilter {
+    /** The id ties the visible label to its dropdown. */
+    id: string;
+    label: string;
+    options: AnalyticsFilterOption[];
+    value: string;
+    /** The report URL for each option's value, built on the server. */
+    hrefs: Record<string, string>;
+}
+interface AnalyticsFiltersProps {
+    filters: AnalyticsFilter[];
+}
+/** Payload's own dropdowns. Choosing an option loads that report URL. */
+declare function AnalyticsFilters({ filters }: AnalyticsFiltersProps): react_jsx_runtime.JSX.Element;
+
+export { AnalyticsFilters };
+export type { AnalyticsFilter, AnalyticsFilterOption, AnalyticsFiltersProps };

package/dist/payload/admin-filters.js

@@ -0,0 +1,33 @@
+"use client";
+
+// src/payload/admin/filters.tsx
+import { ReactSelect } from "@payloadcms/ui";
+import { useRouter } from "next/navigation.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function AnalyticsFilters({ filters }) {
+  const router = useRouter();
+  return /* @__PURE__ */ jsx("div", { className: "nwa-filters", children: filters.map((filter) => /* @__PURE__ */ jsxs("div", { className: "nwa-filter", children: [
+    /* @__PURE__ */ jsx("label", { className: "nwa-filter__label", htmlFor: filter.id, children: filter.label }),
+    /* @__PURE__ */ jsx(
+      ReactSelect,
+      {
+        inputId: filter.id,
+        isClearable: false,
+        isSearchable: filter.options.length > 8,
+        options: filter.options,
+        value: filter.options.find((option) => option.value === filter.value),
+        onChange: (selected) => {
+          const href = filter.hrefs[optionValue(selected)];
+          if (href) router.push(href);
+        }
+      }
+    )
+  ] }, filter.id)) });
+}
+function optionValue(selected) {
+  const option = Array.isArray(selected) ? selected[0] : selected;
+  return typeof option?.value === "string" ? option.value : "";
+}
+export {
+  AnalyticsFilters
+};

package/dist/payload/admin-view.d.ts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { AdminViewServerProps } from 'payload';
 
-declare function AnalyticsAdminView(props: AdminViewServerProps): Promise<react_jsx_runtime.JSX.Element | null>;
+/** The analytics screen inside Payload's own admin frame, sidebar included. */
+declare function AnalyticsAdminView(props: AdminViewServerProps): Promise<react_jsx_runtime.JSX.Element>;
 
 export { AnalyticsAdminView };