@nodewrite-labs/analytics-sdk 0.2.0 → 0.3.0

package/dist/payload/index.d.ts

@@ -1,6 +1,6 @@
 import { Access, Config, Payload } from 'payload';
-import { AnalyticsModules, AnalyticsServerOptions, ReadGeoFromHeaders } 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,38 +13,54 @@ 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. */
@@ -53,10 +69,22 @@ interface AnalyticsEndpointOptions extends AnalyticsServerOptions {
 
 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: AnalyticsPluginOptions): (config: Config) => Config;
 
@@ -73,5 +101,5 @@ declare class PayloadAnalyticsEventStore implements AnalyticsEventStore {
     summarizeAnalytics(query: AnalyticsSummaryQuery, modules: AnalyticsModules): Promise<AnalyticsSummary>;
 }
 
-export { PayloadAnalyticsEventStore, adminSections, analyticsEventsAccess, analyticsPlugin };
-export type { AnalyticsEndpointOptions, AnalyticsPluginOptions };
+export { ENGLISH_ANALYTICS_LABELS, PayloadAnalyticsEventStore, analyticsEventsAccess, analyticsPlugin };
+export type { AnalyticsEndpointOptions, AnalyticsLabelKey, AnalyticsLabels, AnalyticsPluginOptions, AnalyticsTranslation, AnalyticsTranslations };

package/dist/payload/index.js

@@ -3,12 +3,19 @@ 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
@@ -64,6 +71,14 @@ function headerRecord(headers) {
 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 ?? {};
@@ -72,8 +87,13 @@ function analyticsPlugin(options) {
       ...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: {
@@ -98,17 +118,14 @@ function analyticsPlugin(options) {
       },
       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.js

@@ -1,7 +1,29 @@
+"use client";
+
 // src/payload/admin/nav-link.tsx
-import { jsx } from "react/jsx-runtime";
+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 }) {
-  return /* @__PURE__ */ jsx("a", { href, children: "Analytics" });
+  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/package.json

@@ -1,90 +1,113 @@
-{
-  "name": "@nodewrite-labs/analytics-sdk",
-  "version": "0.2.0",
-  "description": "Analytics SDK for page views and named clicks, with Postgres storage and a Payload admin screen.",
-  "publishConfig": {
-    "access": "public"
-  },
-  "packageManager": "pnpm@12.11.2",
-  "engines": {
-    "node": ">=22"
-  },
-  "workspaces": [
-    "playground"
-  ],
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./client": {
-      "types": "./dist/client/index.d.ts",
-      "import": "./dist/client/index.js"
-    },
-    "./server": {
-      "types": "./dist/server/index.d.ts",
-      "import": "./dist/server/index.js"
-    },
-    "./postgres": {
-      "types": "./dist/postgres/index.d.ts",
-      "import": "./dist/postgres/index.js"
-    },
-    "./payload": {
-      "types": "./dist/payload/index.d.ts",
-      "import": "./dist/payload/index.js"
-    },
-    "./payload/admin-view": {
-      "types": "./dist/payload/admin-view.d.ts",
-      "import": "./dist/payload/admin-view.js"
-    },
-    "./payload/nav-link": {
-      "types": "./dist/payload/nav-link.d.ts",
-      "import": "./dist/payload/nav-link.js"
-    }
-  },
-  "files": [
-    "dist",
-    "src/postgres/schema.sql",
-    "README.md"
-  ],
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "build": "tsup"
-  },
-  "peerDependencies": {
-    "@payloadcms/next": "*",
-    "payload": "*",
-    "pg": "*"
-  },
-  "peerDependenciesMeta": {
-    "@payloadcms/next": {
-      "optional": true
-    },
-    "payload": {
-      "optional": true
-    },
-    "pg": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@payloadcms/next": "3.92.0",
-    "@types/node": "^22.20.5",
-    "@types/pg": "^8.23.1",
-    "@types/react": "19.2.14",
-    "esbuild": "^0.28.2",
-    "graphql": "^16.14.2",
-    "jsdom": "^30.1.3",
-    "payload": "3.92.0",
-    "pg": "^8.23.1",
-    "react": "^19.3.1",
-    "tsup": "^9.0.0",
-    "typescript": "6.0.3",
-    "vite": "^8.3.5",
-    "vitest": "^5.0.5"
-  }
-}
+{
+  "name": "@nodewrite-labs/analytics-sdk",
+  "version": "0.3.0",
+  "description": "Analytics SDK for page views and named clicks, with Postgres storage and a Payload admin screen.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@12.11.2",
+  "engines": {
+    "node": ">=22"
+  },
+  "workspaces": [
+    "playground"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgres/index.d.ts",
+      "import": "./dist/postgres/index.js"
+    },
+    "./payload": {
+      "types": "./dist/payload/index.d.ts",
+      "import": "./dist/payload/index.js"
+    },
+    "./payload/admin-view": {
+      "types": "./dist/payload/admin-view.d.ts",
+      "import": "./dist/payload/admin-view.js"
+    },
+    "./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": [
+    "dist",
+    "src/postgres/schema.sql",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsup"
+  },
+  "peerDependencies": {
+    "@payloadcms/next": "*",
+    "@payloadcms/ui": "*",
+    "next": "*",
+    "payload": "*",
+    "pg": "*",
+    "react": "*"
+  },
+  "peerDependenciesMeta": {
+    "@payloadcms/next": {
+      "optional": true
+    },
+    "@payloadcms/ui": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "payload": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "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"
+  }
+}