@nodewrite-labs/analytics-sdk 0.1.0 → 0.3.0

package/dist/payload/index.d.ts

@@ -1,6 +1,6 @@
 import { Access, Config, Payload } from 'payload';
-import { AnalyticsModules, AnalyticsServerOptions } from '../index.js';
-import { AnalyticsSummary, AnalyticsEventStore, NewAnalyticsEvent, StoredAnalyticsEvent, AnalyticsSummaryQuery } from '../index.js';
+import { AnalyticsServerOptions, ReadGeoFromHeaders, AnalyticsModules } from '../index.js';
+import { AnalyticsEventStore, NewAnalyticsEvent, StoredAnalyticsEvent, AnalyticsSummaryQuery, AnalyticsSummary } from '../index.js';
 
 /**
  * Read is allowed for a signed-in user, or by the function the plugin was given.
@@ -13,46 +13,80 @@ declare function analyticsEventsAccess(read?: Access): {
     delete: Access;
 };
 
-interface AdminSectionsQuery {
-    session?: string | null;
-}
-type AdminSection = {
-    kind: "totals";
-    totalViews: number;
-    averageDurationSeconds: number;
-} | {
-    kind: "paths";
-    rows: AnalyticsSummary["byPath"];
-} | {
-    kind: "countries";
-    rows: NonNullable<AnalyticsSummary["byCountry"]>;
-} | {
-    kind: "cities";
-    rows: NonNullable<AnalyticsSummary["byCity"]>;
-} | {
-    kind: "namedClicks";
-    rows: NonNullable<AnalyticsSummary["byEventName"]>;
-} | {
-    kind: "sessions";
-    rows: NonNullable<AnalyticsSummary["sessions"]>;
-} | {
-    kind: "trail";
-    events: NonNullable<AnalyticsSummary["events"]>;
+/** The English labels, shown in every admin language the host does not translate. */
+declare const ENGLISH_ANALYTICS_LABELS: {
+    readonly navGroup: "Statistics";
+    readonly navLabel: "Analytics";
+    readonly title: "Analytics";
+    readonly period: "Period";
+    readonly period_24h: "Last 24 hours";
+    readonly period_7d: "Last 7 days";
+    readonly period_30d: "Last 30 days";
+    readonly period_12m: "Last 12 months";
+    readonly country: "Country";
+    readonly allCountries: "All countries";
+    readonly views: "Views";
+    readonly averageTime: "Average time on page";
+    readonly clicks: "Clicks";
+    readonly viewsOverTime: "Views over time";
+    readonly topPages: "Top pages";
+    readonly allPages: "All pages";
+    readonly showAllPages: "Show all pages";
+    readonly showTopPages: "Show top pages only";
+    readonly page: "Page";
+    readonly pageFilter: "Page: {{path}}";
+    readonly clearFilter: "Clear";
+    readonly countries: "Countries";
+    readonly cities: "Cities";
+    readonly city: "City";
+    readonly event: "Event";
+    readonly count: "Count";
+    readonly sessions: "Sessions";
+    readonly session: "Session";
+    readonly started: "Started";
+    readonly pages: "Pages";
+    readonly sessionEvents: "Session events";
+    readonly allSessions: "All sessions";
+    readonly time: "Time";
+    readonly kind: "Kind";
+    readonly kindView: "View";
+    readonly kindClick: "Click";
+    readonly empty: "Nothing in this period.";
 };
-/**
- * Blocks for the admin screen, in display order.
- * A module that is off contributes no block.
- * A session query replaces the session list with one trail of that session's events, in time order.
- */
-declare function adminSections(summary: AnalyticsSummary, modules: AnalyticsModules, query: AdminSectionsQuery): AdminSection[];
+type AnalyticsLabelKey = keyof typeof ENGLISH_ANALYTICS_LABELS;
+type AnalyticsLabels = Record<AnalyticsLabelKey, string>;
+/** One admin language's labels. Missing keys show English. `events` names named clicks. */
+type AnalyticsTranslation = Partial<AnalyticsLabels> & {
+    events?: Record<string, string>;
+};
+/** Keyed by Payload admin language, such as `en` or `rs-latin`. */
+type AnalyticsTranslations = Record<string, AnalyticsTranslation>;
 
+interface AnalyticsEndpointOptions extends AnalyticsServerOptions {
+    /** Without it, the country and city modules store null. */
+    geo?: ReadGeoFromHeaders;
+}
+
+interface AnalyticsPluginOptions extends AnalyticsEndpointOptions {
+    read?: Access;
+    /** IANA time zone the report's hours, days and months follow. Defaults to UTC. */
+    timeZone?: string;
+    /**
+     * Labels per Payload admin language, over the English defaults. A language with no entry
+     * shows English, so the package never needs to know the host's languages.
+     */
+    translations?: AnalyticsTranslations;
+    /**
+     * The BCP 47 tag per admin language for numbers, dates and country names, for languages whose
+     * Payload code is not one (`rs-latin` → `sr-Latn`). Others use Payload's date locale.
+     */
+    formatLocales?: Record<string, string>;
+}
 /**
- * Adds the analytics collection, the ingest endpoint, and the admin screen.
- * Existing collections, endpoints, and views stay in place.
+ * Adds the analytics collection, the ingest endpoint, the admin screen, and its sidebar link.
+ * Existing collections, endpoints, views, and translations stay in place.
  */
-declare function analyticsPlugin(options: AnalyticsServerOptions & {
-    read?: Access;
-}): (config: Config) => Config;
+declare function analyticsPlugin(options: AnalyticsPluginOptions): (config: Config) => Config;
 
 /**
  * AnalyticsEventStore on Payload's Local API.
@@ -67,4 +101,5 @@ declare class PayloadAnalyticsEventStore implements AnalyticsEventStore {
     summarizeAnalytics(query: AnalyticsSummaryQuery, modules: AnalyticsModules): Promise<AnalyticsSummary>;
 }
 
-export { PayloadAnalyticsEventStore, adminSections, analyticsEventsAccess, analyticsPlugin };
+export { ENGLISH_ANALYTICS_LABELS, PayloadAnalyticsEventStore, analyticsEventsAccess, analyticsPlugin };
+export type { AnalyticsEndpointOptions, AnalyticsLabelKey, AnalyticsLabels, AnalyticsPluginOptions, AnalyticsTranslation, AnalyticsTranslations };

package/dist/payload/index.js

@@ -3,18 +3,31 @@ import {
 } from "../chunk-GWOVVKP3.js";
 import {
   ANALYTICS_CUSTOM_KEY,
+  ANALYTICS_FILTERS_DEPENDENCY,
+  ANALYTICS_FILTERS_PATH,
+  DEFAULT_ANALYTICS_TIME_ZONE,
+  ENGLISH_ANALYTICS_LABELS,
   PayloadAnalyticsEventStore,
-  adminSections,
   analyticsEventsAccess,
-  analyticsEventsCollection
-} from "../chunk-GVOESWHZ.js";
-import "../chunk-Q4JRXZ6M.js";
+  analyticsEventsCollection,
+  withAnalyticsTranslations
+} from "../chunk-QPHMFHRE.js";
+import {
+  assertTimeZone
+} from "../chunk-MOCOVYQK.js";
+import "../chunk-YAC3MRH3.js";
 import "../chunk-F7BY2JQ3.js";
 
 // src/payload/endpoint.ts
+var NO_GEO = { country: null, city: null };
 async function handleAnalyticsEvent(request, deps) {
   const result = await recordAnalyticsEvent(
-    { body: request.body, headers: headerRecord(request.headers) },
+    {
+      body: request.body,
+      headers: headerRecord(request.headers),
+      country: request.country ?? null,
+      city: request.city ?? null
+    },
     deps
   );
   if (result.status === 204 || result.body === null) {
@@ -37,7 +50,11 @@ async function handlePayloadAnalyticsEvent(req, options) {
   } catch {
     body = void 0;
   }
-  return handleAnalyticsEvent({ body, headers: req.headers }, { store, options });
+  const geo = options.geo ? options.geo(req.headers) : NO_GEO;
+  return handleAnalyticsEvent(
+    { body, headers: req.headers, country: geo.country, city: geo.city },
+    { store, options }
+  );
 }
 function headerRecord(headers) {
   if (headers instanceof Headers) {
@@ -51,16 +68,32 @@ function headerRecord(headers) {
 }
 
 // src/payload/plugin.ts
+var DEFAULT_ADMIN_ROUTE = "/admin";
+var ANALYTICS_VIEW_PATH = "/analytics";
 function analyticsPlugin(options) {
+  const timeZone = options.timeZone ?? DEFAULT_ANALYTICS_TIME_ZONE;
+  assertTimeZone(timeZone);
+  const custom = {
+    enabled: options.enabled,
+    modules: options.modules,
+    timeZone,
+    formatLocales: options.formatLocales ?? {}
+  };
   return (config) => {
+    const adminRoute = config.routes?.admin ?? DEFAULT_ADMIN_ROUTE;
     const admin = config.admin ?? {};
     const components = admin.components ?? {};
     return {
       ...config,
       collections: [...config.collections ?? [], analyticsEventsCollection(options.read)],
       endpoints: [...config.endpoints ?? [], analyticsEventsEndpoint(options)],
+      i18n: withAnalyticsTranslations(config.i18n, options.translations),
       admin: {
         ...admin,
+        dependencies: {
+          ...admin.dependencies,
+          [ANALYTICS_FILTERS_DEPENDENCY]: { type: "component", path: ANALYTICS_FILTERS_PATH }
+        },
         components: {
           ...components,
           views: {
@@ -70,31 +103,29 @@ function analyticsPlugin(options) {
                 path: "@nodewrite-labs/analytics-sdk/payload/admin-view",
                 exportName: "AnalyticsAdminView"
               },
-              path: "/analytics"
+              path: ANALYTICS_VIEW_PATH
             }
           },
           afterNavLinks: [
             ...components.afterNavLinks ?? [],
             {
               path: "@nodewrite-labs/analytics-sdk/payload/nav-link",
-              exportName: "AnalyticsNavLink"
+              exportName: "AnalyticsNavLink",
+              clientProps: { href: `${adminRoute}${ANALYTICS_VIEW_PATH}` }
             }
           ]
         }
       },
       custom: {
         ...config.custom,
-        [ANALYTICS_CUSTOM_KEY]: {
-          enabled: options.enabled,
-          modules: options.modules
-        }
+        [ANALYTICS_CUSTOM_KEY]: custom
       }
     };
   };
 }
 export {
+  ENGLISH_ANALYTICS_LABELS,
   PayloadAnalyticsEventStore,
-  adminSections,
   analyticsEventsAccess,
   analyticsPlugin
 };

package/dist/payload/nav-link.d.ts

@@ -1,5 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-declare function AnalyticsNavLink(): react_jsx_runtime.JSX.Element;
+interface AnalyticsNavLinkProps {
+    /** The analytics view under the app's admin route; the plugin sets it. */
+    href: string;
+}
+declare function AnalyticsNavLink({ href }: AnalyticsNavLinkProps): react_jsx_runtime.JSX.Element;
 
 export { AnalyticsNavLink };
+export type { AnalyticsNavLinkProps };

package/dist/payload/nav-link.js

@@ -1,7 +1,29 @@
+"use client";
+
 // src/payload/admin/nav-link.tsx
-import { jsx } from "react/jsx-runtime";
-function AnalyticsNavLink() {
-  return /* @__PURE__ */ jsx("a", { href: "/admin/analytics", children: "Analytics" });
+import { Link, NavGroup, useTranslation } from "@payloadcms/ui";
+import { usePathname } from "next/navigation.js";
+
+// src/payload/admin/translations.ts
+var ANALYTICS_TRANSLATION_NAMESPACE = "analytics";
+function analyticsLabel(t, key, vars) {
+  return t(`${ANALYTICS_TRANSLATION_NAMESPACE}:${key}`, vars);
+}
+
+// src/payload/admin/nav-link.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var NAV_LINK_CLASS = "nav__link";
+var NAV_LINK_ID = "nav-analytics";
+function AnalyticsNavLink({ href }) {
+  const { t } = useTranslation();
+  const pathname = usePathname();
+  const translate = t;
+  const isActive = pathname === href || pathname.startsWith(`${href}/`);
+  const label = /* @__PURE__ */ jsxs(Fragment, { children: [
+    isActive ? /* @__PURE__ */ jsx("div", { className: "nav__link-indicator" }) : null,
+    /* @__PURE__ */ jsx("span", { className: "nav__link-label", children: analyticsLabel(translate, "navLabel") })
+  ] });
+  return /* @__PURE__ */ jsx(NavGroup, { label: analyticsLabel(translate, "navGroup"), children: pathname === href ? /* @__PURE__ */ jsx("div", { className: NAV_LINK_CLASS, id: NAV_LINK_ID, children: label }) : /* @__PURE__ */ jsx(Link, { className: NAV_LINK_CLASS, href, id: NAV_LINK_ID, prefetch: false, children: label }) });
 }
 export {
   AnalyticsNavLink

package/dist/postgres/index.js

@@ -1,7 +1,7 @@
 import {
   acceptDurationSeconds,
   summarizeAnalyticsEvents
-} from "../chunk-Q4JRXZ6M.js";
+} from "../chunk-YAC3MRH3.js";
 import {
   AnalyticsEventKind
 } from "../chunk-F7BY2JQ3.js";

package/dist/server/index.d.ts

@@ -1,10 +1,7 @@
-import { AnalyticsEventStore } from '../index.js';
+import { c as RequestGeo } from '../options-Dpx2vs4R.js';
 import { AnalyticsServerOptions } from '../index.js';
+import { AnalyticsEventStore } from '../index.js';
 
-interface RequestGeo {
-    country: string | null;
-    city: string | null;
-}
 /** Reads `country` and `city` from the request object the app passed in. */
 declare function readRequestGeo(request: object): RequestGeo;
 
@@ -40,5 +37,5 @@ interface RecordAnalyticsEventResult {
  */
 declare function recordAnalyticsEvent(request: AnalyticsEventRequest | Request, deps: RecordAnalyticsEventDeps): Promise<RecordAnalyticsEventResult>;
 
-export { readRequestGeo, recordAnalyticsEvent };
-export type { AnalyticsEventRequest, AnalyticsHeaderBag, RecordAnalyticsEventDeps, RecordAnalyticsEventResult, RequestGeo };
+export { RequestGeo, readRequestGeo, recordAnalyticsEvent };
+export type { AnalyticsEventRequest, AnalyticsHeaderBag, RecordAnalyticsEventDeps, RecordAnalyticsEventResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodewrite-labs/analytics-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Analytics SDK for page views and named clicks, with Postgres storage and a Payload admin screen.",
   "publishConfig": {
     "access": "public"
@@ -43,6 +43,10 @@
     "./payload/nav-link": {
       "types": "./dist/payload/nav-link.d.ts",
       "import": "./dist/payload/nav-link.js"
+    },
+    "./payload/admin-filters": {
+      "types": "./dist/payload/admin-filters.d.ts",
+      "import": "./dist/payload/admin-filters.js"
     }
   },
   "files": [
@@ -53,17 +57,29 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "build": "tsup"
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsup"
   },
   "peerDependencies": {
     "@payloadcms/next": "*",
+    "@payloadcms/ui": "*",
+    "next": "*",
     "payload": "*",
-    "pg": "*"
+    "pg": "*",
+    "react": "*"
   },
   "peerDependenciesMeta": {
     "@payloadcms/next": {
       "optional": true
     },
+    "@payloadcms/ui": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
     "payload": {
       "optional": true
     },
@@ -73,18 +89,25 @@
   },
   "devDependencies": {
     "@payloadcms/next": "3.92.0",
+    "@payloadcms/ui": "3.92.0",
     "@types/node": "^22.20.5",
     "@types/pg": "^8.23.1",
     "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
     "esbuild": "^0.28.2",
     "graphql": "^16.14.2",
     "jsdom": "^30.1.3",
+    "next": "16.3.3",
     "payload": "3.92.0",
     "pg": "^8.23.1",
     "react": "^19.3.1",
+    "react-dom": "19.3.1",
     "tsup": "^9.0.0",
     "typescript": "6.0.3",
     "vite": "^8.3.5",
     "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "country-flag-icons": "1.6.20"
   }
 }

package/src/postgres/schema.sql

@@ -1,12 +1,12 @@
-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
-);
+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
+);

package/dist/options-D3s0dcJ-.d.ts

@@ -1,19 +0,0 @@
-interface AnalyticsModules {
-    country: boolean;
-    city: boolean;
-    sessions: boolean;
-    clicks: boolean;
-}
-interface AnalyticsServerOptions {
-    enabled: boolean;
-    modules: AnalyticsModules;
-}
-interface AnalyticsClientConfig {
-    endpoint: string;
-    enabled: boolean;
-    locale?: string;
-    sessions: boolean;
-    clicks: boolean;
-}
-
-export type { AnalyticsClientConfig as A, AnalyticsModules as a, AnalyticsServerOptions as b };