@nodewrite-labs/analytics-sdk 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +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.
+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

@@ -75,6 +75,27 @@ const result = await recordAnalyticsEvent(
 
 `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.
 
+## Payload
+
+`analyticsPlugin` adds the hidden `analytics-events` collection, the ingest endpoint at `/analytics/events` under the Payload API route (`/api/analytics/events` by default), and an admin screen at `/analytics` under the admin route. The nav link follows `routes.admin`.
+
+The package names no host's geo headers. Pass `geo` to read country and city from the request headers your host sets. Without `geo`, the country and city modules store null.
+
+```ts
+import { analyticsPlugin } from "@nodewrite-labs/analytics-sdk/payload";
+
+analyticsPlugin({
+  enabled: true,
+  modules: { country: true, city: false, sessions: false, clicks: true },
+  // Vercel, for example. Cloudflare sends `cf-ipcountry`.
+  geo: (headers) => ({ country: headers.get("x-vercel-ip-country"), city: null }),
+});
+```
+
+The browser then posts to the Payload endpoint: `startAnalytics({ endpoint: "/api/analytics/events", … })`.
+
+The plugin adds a collection, so a Payload project with migrations needs a new one (`payload migrate:create`).
+
 ## Store
 
 `AnalyticsEventStore` is three methods: `insertAnalyticsEvent`, `recordAnalyticsDuration`, and `summarizeAnalytics`.

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-import { A as AnalyticsClientConfig } from '../options-D3s0dcJ-.js';
+import { A as AnalyticsClientConfig } from '../options-Dpx2vs4R.js';
 export { A as AnalyticsEventBody } from '../event-body-fpV2mYpY.js';
 
 declare function recordNamedClick(name: string): void;

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

@@ -1,4 +1,4 @@
-import { a as AnalyticsModules } from './options-D3s0dcJ-.js';
+import { a as AnalyticsModules } from './options-Dpx2vs4R.js';
 
 declare const AnalyticsEventKind: {
     readonly VIEW: "view";

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { S as StoredAnalyticsEvent, A as AnalyticsSummaryQuery, a as AnalyticsSummary, b as AnalyticsEventStore, N as NewAnalyticsEvent } from './event-store-BhisLdw_.js';
-export { c as AnalyticsEventKind } from './event-store-BhisLdw_.js';
-import { a as AnalyticsModules } from './options-D3s0dcJ-.js';
-export { A as AnalyticsClientConfig, b as AnalyticsServerOptions } from './options-D3s0dcJ-.js';
+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 { 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';
 
 /** Keeps a duration inside 0..1800. NaN and infinities are rejected. */

package/dist/options-Dpx2vs4R.d.ts

@@ -0,0 +1,29 @@
+interface AnalyticsModules {
+    country: boolean;
+    city: boolean;
+    sessions: boolean;
+    clicks: boolean;
+}
+interface AnalyticsServerOptions {
+    enabled: boolean;
+    modules: AnalyticsModules;
+}
+/** Country and city for one request, as the host reports them. */
+interface RequestGeo {
+    country: string | null;
+    city: string | null;
+}
+/**
+ * Reads the visitor's country and city from the request headers. The app supplies it, because
+ * each host names its geo headers differently.
+ */
+type ReadGeoFromHeaders = (headers: Headers) => RequestGeo;
+interface AnalyticsClientConfig {
+    endpoint: string;
+    enabled: boolean;
+    locale?: string;
+    sessions: boolean;
+    clicks: boolean;
+}
+
+export type { AnalyticsClientConfig as A, ReadGeoFromHeaders as R, AnalyticsModules as a, AnalyticsServerOptions as b, RequestGeo as c };

package/dist/payload/index.d.ts

@@ -1,5 +1,5 @@
 import { Access, Config, Payload } from 'payload';
-import { AnalyticsModules, AnalyticsServerOptions } from '../index.js';
+import { AnalyticsModules, AnalyticsServerOptions, ReadGeoFromHeaders } from '../index.js';
 import { AnalyticsSummary, AnalyticsEventStore, NewAnalyticsEvent, StoredAnalyticsEvent, AnalyticsSummaryQuery } from '../index.js';
 
 /**
@@ -46,13 +46,19 @@ type AdminSection = {
  */
 declare function adminSections(summary: AnalyticsSummary, modules: AnalyticsModules, query: AdminSectionsQuery): AdminSection[];
 
+interface AnalyticsEndpointOptions extends AnalyticsServerOptions {
+    /** Without it, the country and city modules store null. */
+    geo?: ReadGeoFromHeaders;
+}
+
+interface AnalyticsPluginOptions extends AnalyticsEndpointOptions {
+    read?: Access;
+}
 /**
  * Adds the analytics collection, the ingest endpoint, and the admin screen.
  * Existing collections, endpoints, and views 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.
@@ -68,3 +74,4 @@ declare class PayloadAnalyticsEventStore implements AnalyticsEventStore {
 }
 
 export { PayloadAnalyticsEventStore, adminSections, analyticsEventsAccess, analyticsPlugin };
+export type { AnalyticsEndpointOptions, AnalyticsPluginOptions };

package/dist/payload/index.js

@@ -12,9 +12,15 @@ import "../chunk-Q4JRXZ6M.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 +43,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,8 +61,11 @@ function headerRecord(headers) {
 }
 
 // src/payload/plugin.ts
+var DEFAULT_ADMIN_ROUTE = "/admin";
+var ANALYTICS_VIEW_PATH = "/analytics";
 function analyticsPlugin(options) {
   return (config) => {
+    const adminRoute = config.routes?.admin ?? DEFAULT_ADMIN_ROUTE;
     const admin = config.admin ?? {};
     const components = admin.components ?? {};
     return {
@@ -70,14 +83,15 @@ 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}` }
             }
           ]
         }

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,7 @@
 // src/payload/admin/nav-link.tsx
 import { jsx } from "react/jsx-runtime";
-function AnalyticsNavLink() {
-  return /* @__PURE__ */ jsx("a", { href: "/admin/analytics", children: "Analytics" });
+function AnalyticsNavLink({ href }) {
+  return /* @__PURE__ */ jsx("a", { href, children: "Analytics" });
 }
 export {
   AnalyticsNavLink

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,90 +1,90 @@
-{
-  "name": "@nodewrite-labs/analytics-sdk",
-  "version": "0.1.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.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"
+  }
+}

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 };