@carlonicora/nextjs-jsonapi 3.24.2 → 3.25.0

package/src/features/analytics/data/analytics-session.ts

@@ -0,0 +1,144 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { UserInterface } from "../../user/data/user.interface";
+import { AnalyticsSessionInterface } from "./analytics-session.interface";
+import { AnalyticsSessionInput } from "./analytics.types";
+
+/** One visit: a run of page views from one visitor with no 30-minute gap. */
+export class AnalyticsSession extends AbstractApiData implements AnalyticsSessionInterface {
+  private _visitorId: string = "";
+  private _consented: boolean = false;
+  private _startedAt: Date = new Date(0);
+  private _lastSeenAt: Date = new Date(0);
+  private _pageViews: number = 0;
+  private _section: string = "";
+  private _landingRoute: string = "";
+  private _referrerHost?: string;
+  private _utmSource?: string;
+  private _utmMedium?: string;
+  private _utmCampaign?: string;
+  private _utmTerm?: string;
+  private _utmContent?: string;
+  private _deviceType: string = "";
+  private _user?: UserInterface;
+
+  get visitorId(): string {
+    return this._visitorId;
+  }
+
+  get consented(): boolean {
+    return this._consented;
+  }
+
+  get startedAt(): Date {
+    return this._startedAt;
+  }
+
+  get lastSeenAt(): Date {
+    return this._lastSeenAt;
+  }
+
+  get pageViews(): number {
+    return this._pageViews;
+  }
+
+  get section(): string {
+    return this._section;
+  }
+
+  get landingRoute(): string {
+    return this._landingRoute;
+  }
+
+  get referrerHost(): string | undefined {
+    return this._referrerHost;
+  }
+
+  get utmSource(): string | undefined {
+    return this._utmSource;
+  }
+
+  get utmMedium(): string | undefined {
+    return this._utmMedium;
+  }
+
+  get utmCampaign(): string | undefined {
+    return this._utmCampaign;
+  }
+
+  get utmTerm(): string | undefined {
+    return this._utmTerm;
+  }
+
+  get utmContent(): string | undefined {
+    return this._utmContent;
+  }
+
+  get deviceType(): string {
+    return this._deviceType;
+  }
+
+  get user(): UserInterface | undefined {
+    return this._user;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._visitorId = attrs.visitorId ?? "";
+    this._consented = attrs.consented ?? false;
+    // Wire format is an ISO 8601 instant; the interface promises a Date.
+    this._startedAt = attrs.startedAt ? new Date(attrs.startedAt) : new Date(0);
+    this._lastSeenAt = attrs.lastSeenAt ? new Date(attrs.lastSeenAt) : new Date(0);
+    this._pageViews = attrs.pageViews ?? 0;
+    this._section = attrs.section ?? "";
+    this._landingRoute = attrs.landingRoute ?? "";
+    this._referrerHost = attrs.referrerHost ?? undefined;
+    this._utmSource = attrs.utmSource ?? undefined;
+    this._utmMedium = attrs.utmMedium ?? undefined;
+    this._utmCampaign = attrs.utmCampaign ?? undefined;
+    this._utmTerm = attrs.utmTerm ?? undefined;
+    this._utmContent = attrs.utmContent ?? undefined;
+    this._deviceType = attrs.deviceType ?? "";
+
+    this._user = this._readIncluded(data, "user", Modules.User) as UserInterface | undefined;
+
+    return this;
+  }
+
+  createJsonApi(data: AnalyticsSessionInput) {
+    const response: any = {
+      data: {
+        type: Modules.AnalyticsSession.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.visitorId !== undefined) response.data.attributes.visitorId = data.visitorId;
+    if (data.consented !== undefined) response.data.attributes.consented = data.consented;
+    // Both are type: "datetime" on the backend descriptor: ISO 8601 instants.
+    if (data.startedAt !== undefined) response.data.attributes.startedAt = data.startedAt.toISOString();
+    if (data.lastSeenAt !== undefined) response.data.attributes.lastSeenAt = data.lastSeenAt.toISOString();
+    if (data.pageViews !== undefined) response.data.attributes.pageViews = data.pageViews;
+    if (data.section !== undefined) response.data.attributes.section = data.section;
+    if (data.landingRoute !== undefined) response.data.attributes.landingRoute = data.landingRoute;
+    if (data.referrerHost !== undefined) response.data.attributes.referrerHost = data.referrerHost;
+    if (data.utmSource !== undefined) response.data.attributes.utmSource = data.utmSource;
+    if (data.utmMedium !== undefined) response.data.attributes.utmMedium = data.utmMedium;
+    if (data.utmCampaign !== undefined) response.data.attributes.utmCampaign = data.utmCampaign;
+    if (data.utmTerm !== undefined) response.data.attributes.utmTerm = data.utmTerm;
+    if (data.utmContent !== undefined) response.data.attributes.utmContent = data.utmContent;
+    if (data.deviceType !== undefined) response.data.attributes.deviceType = data.deviceType;
+
+    if (data.userId) {
+      response.data.relationships.user = {
+        data: { type: Modules.User.name, id: data.userId },
+      };
+    }
+
+    return response;
+  }
+}

package/src/features/analytics/data/analytics-summary.interface.ts

@@ -0,0 +1,11 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface AnalyticsSummaryInterface extends ApiDataInterface {
+  get section(): string;
+  get window(): string;
+  get visitors(): number;
+  get sessions(): number;
+  get pageViews(): number;
+  get pagesPerSession(): number;
+  get consentShare(): number;
+}

package/src/features/analytics/data/analytics-summary.ts

@@ -0,0 +1,79 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AnalyticsSummaryInterface } from "./analytics-summary.interface";
+import { AnalyticsSummaryInput } from "./analytics.types";
+
+/** One (section, window) row of the headline tiles: current or previous period. */
+export class AnalyticsSummary extends AbstractApiData implements AnalyticsSummaryInterface {
+  private _section: string = "";
+  private _window: string = "";
+  private _visitors: number = 0;
+  private _sessions: number = 0;
+  private _pageViews: number = 0;
+  private _pagesPerSession: number = 0;
+  private _consentShare: number = 0;
+
+  get section(): string {
+    return this._section;
+  }
+
+  get window(): string {
+    return this._window;
+  }
+
+  get visitors(): number {
+    return this._visitors;
+  }
+
+  get sessions(): number {
+    return this._sessions;
+  }
+
+  get pageViews(): number {
+    return this._pageViews;
+  }
+
+  get pagesPerSession(): number {
+    return this._pagesPerSession;
+  }
+
+  get consentShare(): number {
+    return this._consentShare;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._section = attrs.section ?? "";
+    this._window = attrs.window ?? "";
+    this._visitors = attrs.visitors ?? 0;
+    this._sessions = attrs.sessions ?? 0;
+    this._pageViews = attrs.pageViews ?? 0;
+    this._pagesPerSession = attrs.pagesPerSession ?? 0;
+    this._consentShare = attrs.consentShare ?? 0;
+
+    return this;
+  }
+
+  createJsonApi(data: AnalyticsSummaryInput) {
+    const response: any = {
+      data: {
+        type: Modules.AnalyticsSummary.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.section !== undefined) response.data.attributes.section = data.section;
+    if (data.window !== undefined) response.data.attributes.window = data.window;
+    if (data.visitors !== undefined) response.data.attributes.visitors = data.visitors;
+    if (data.sessions !== undefined) response.data.attributes.sessions = data.sessions;
+    if (data.pageViews !== undefined) response.data.attributes.pageViews = data.pageViews;
+    if (data.pagesPerSession !== undefined) response.data.attributes.pagesPerSession = data.pagesPerSession;
+    if (data.consentShare !== undefined) response.data.attributes.consentShare = data.consentShare;
+
+    return response;
+  }
+}

package/src/features/analytics/data/analytics-timeline.interface.ts

@@ -0,0 +1,10 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface AnalyticsTimelineInterface extends ApiDataInterface {
+  /** Backend declares this `type: "date"`, so it is a Date in memory. */
+  get bucket(): Date;
+  get section(): string;
+  get visitors(): number;
+  get sessions(): number;
+  get pageViews(): number;
+}

package/src/features/analytics/data/analytics-timeline.ts

@@ -0,0 +1,67 @@
+import { AbstractApiData, formatLocalDate, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AnalyticsTimelineInterface } from "./analytics-timeline.interface";
+import { AnalyticsTimelineInput } from "./analytics.types";
+
+/** One (bucket, section) point of the visitors-over-time chart. */
+export class AnalyticsTimeline extends AbstractApiData implements AnalyticsTimelineInterface {
+  private _bucket: Date = new Date(0);
+  private _section: string = "";
+  private _visitors: number = 0;
+  private _sessions: number = 0;
+  private _pageViews: number = 0;
+
+  get bucket(): Date {
+    return this._bucket;
+  }
+
+  get section(): string {
+    return this._section;
+  }
+
+  get visitors(): number {
+    return this._visitors;
+  }
+
+  get sessions(): number {
+    return this._sessions;
+  }
+
+  get pageViews(): number {
+    return this._pageViews;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    // Wire format is "YYYY-MM-DD"; the interface promises a Date.
+    this._bucket = attrs.bucket ? new Date(attrs.bucket) : new Date(0);
+    this._section = attrs.section ?? "";
+    this._visitors = attrs.visitors ?? 0;
+    this._sessions = attrs.sessions ?? 0;
+    this._pageViews = attrs.pageViews ?? 0;
+
+    return this;
+  }
+
+  createJsonApi(data: AnalyticsTimelineInput) {
+    const response: any = {
+      data: {
+        type: Modules.AnalyticsTimeline.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    // `bucket` is type: "date" on the backend descriptor: formatLocalDate, never the raw Date.
+    if (data.bucket !== undefined) response.data.attributes.bucket = formatLocalDate(data.bucket);
+    if (data.section !== undefined) response.data.attributes.section = data.section;
+    if (data.visitors !== undefined) response.data.attributes.visitors = data.visitors;
+    if (data.sessions !== undefined) response.data.attributes.sessions = data.sessions;
+    if (data.pageViews !== undefined) response.data.attributes.pageViews = data.pageViews;
+
+    return response;
+  }
+}

package/src/features/analytics/data/analytics.types.ts

@@ -0,0 +1,97 @@
+// Each value list is the single source of its union type: components iterate
+// the constant, and the type is derived from it so the two cannot drift.
+
+export const ANALYTICS_SECTIONS = ["all", "public", "app"] as const;
+export type AnalyticsSection = (typeof ANALYTICS_SECTIONS)[number];
+
+export const ANALYTICS_GRANULARITIES = ["day", "week", "month"] as const;
+export type AnalyticsGranularity = (typeof ANALYTICS_GRANULARITIES)[number];
+
+export const ANALYTICS_DIMENSIONS = ["source", "medium", "campaign", "referrer", "route", "landing"] as const;
+export type AnalyticsDimension = (typeof ANALYTICS_DIMENSIONS)[number];
+
+export type AnalyticsFilters = {
+  /** ISO 8601 instant. */
+  from: string;
+  /** ISO 8601 instant. */
+  to: string;
+  section: AnalyticsSection;
+};
+
+/** One page view, as the tracker posts it to `analytics/events`. */
+export type AnalyticsEventInput = {
+  id: string;
+  path: string;
+  section: "public" | "app";
+  referrer?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  visitorId?: string;
+  screenWidth?: number;
+};
+
+// Input types for the read-only models' createJsonApi(). `id` is always
+// required — JSON:API resource objects are identified.
+
+export type AnalyticsSummaryInput = {
+  id: string;
+  section: string;
+  window: string;
+  visitors: number;
+  sessions: number;
+  pageViews: number;
+  pagesPerSession: number;
+  consentShare: number;
+};
+
+export type AnalyticsTimelineInput = {
+  id: string;
+  /** Backend field type is "date" — emitted via formatLocalDate, never raw. */
+  bucket: Date;
+  section: string;
+  visitors: number;
+  sessions: number;
+  pageViews: number;
+};
+
+export type AnalyticsBreakdownInput = {
+  id: string;
+  dimension: string;
+  key: string;
+  visitors: number;
+  sessions: number;
+  pageViews: number;
+};
+
+export type AnalyticsSessionInput = {
+  id: string;
+  visitorId: string;
+  consented: boolean;
+  /** Backend field type is "datetime" — emitted via toISOString(). */
+  startedAt: Date;
+  /** Backend field type is "datetime" — emitted via toISOString(). */
+  lastSeenAt: Date;
+  pageViews: number;
+  section: string;
+  landingRoute: string;
+  referrerHost?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  deviceType: string;
+  userId?: string;
+};
+
+export type AnalyticsPageViewInput = {
+  id: string;
+  /** Backend field type is "datetime" — emitted via toISOString(). */
+  createdAt: Date;
+  path: string;
+  route: string;
+  section: string;
+};

package/src/features/analytics/data/index.ts

@@ -0,0 +1,15 @@
+export * from "./analytics.types";
+export { AnalyticsEvent } from "./analytics-event";
+export type { AnalyticsEventInterface } from "./analytics-event.interface";
+export { AnalyticsSummary } from "./analytics-summary";
+export type { AnalyticsSummaryInterface } from "./analytics-summary.interface";
+export { AnalyticsTimeline } from "./analytics-timeline";
+export type { AnalyticsTimelineInterface } from "./analytics-timeline.interface";
+export { AnalyticsBreakdown } from "./analytics-breakdown";
+export type { AnalyticsBreakdownInterface } from "./analytics-breakdown.interface";
+export { AnalyticsSession } from "./analytics-session";
+export type { AnalyticsSessionInterface } from "./analytics-session.interface";
+export { AnalyticsPageView } from "./analytics-page-view";
+export type { AnalyticsPageViewInterface } from "./analytics-page-view.interface";
+export { AnalyticsService } from "./AnalyticsService";
+export { AnalyticsAdminService } from "./AnalyticsAdminService";

package/src/features/analytics/i18n-keys.ts

@@ -0,0 +1,76 @@
+/**
+ * The fixed namespace of i18n keys the administrative analytics feature reads
+ * via useTranslations. Consuming apps must define each entry in their
+ * messages/<locale>.json — this list is the contract between the package and
+ * the app.
+ *
+ * The description key is read by the consuming app's page metadata only, not by
+ * a component in this package, which is why the contract spec lists it among
+ * the keys declared for app-rendered surfaces.
+ */
+export const ANALYTICS_ADMIN_I18N_KEYS = [
+  // Page
+  "analytics.admin.title",
+  "analytics.admin.description",
+
+  // KPI tiles
+  "analytics.admin.tiles.visitors",
+  "analytics.admin.tiles.sessions",
+  "analytics.admin.tiles.page_views",
+  "analytics.admin.tiles.pages_per_session",
+  "analytics.admin.tiles.consent_share",
+  "analytics.admin.tiles.vs_previous",
+  "analytics.admin.tiles.summarised_note",
+
+  // Filter bar
+  "analytics.admin.filter.section",
+  "analytics.admin.filter.section_all",
+  "analytics.admin.filter.section_public",
+  "analytics.admin.filter.section_app",
+  "analytics.admin.filter.granularity",
+  "analytics.admin.filter.granularity_day",
+  "analytics.admin.filter.granularity_week",
+  "analytics.admin.filter.granularity_month",
+
+  // Panel titles
+  "analytics.admin.panels.over_time",
+  "analytics.admin.panels.breakdown",
+  "analytics.admin.panels.sessions",
+  "analytics.admin.panels.journey",
+  "analytics.admin.panels.other_sessions",
+
+  // Breakdown tabs
+  "analytics.admin.dimensions.source",
+  "analytics.admin.dimensions.medium",
+  "analytics.admin.dimensions.campaign",
+  "analytics.admin.dimensions.referrer",
+  "analytics.admin.dimensions.route",
+  "analytics.admin.dimensions.landing",
+
+  // Table columns
+  "analytics.admin.columns.key",
+  "analytics.admin.columns.visitors",
+  "analytics.admin.columns.sessions",
+  "analytics.admin.columns.page_views",
+  "analytics.admin.columns.started",
+  "analytics.admin.columns.visitor",
+  "analytics.admin.columns.source",
+  "analytics.admin.columns.landing",
+  "analytics.admin.columns.pages",
+  "analytics.admin.columns.device",
+  "analytics.admin.columns.time",
+  "analytics.admin.columns.gap",
+  "analytics.admin.columns.path",
+
+  // Shared states and markers
+  "analytics.admin.anonymous",
+  "analytics.admin.consented",
+  "analytics.admin.not_consented",
+  "analytics.admin.load_more",
+  "analytics.admin.no_data",
+  "analytics.admin.other",
+
+  // Timeline chart series
+  "analytics.admin.series.visitors",
+  "analytics.admin.series.page_views",
+] as const;

package/src/features/analytics/index.ts

@@ -0,0 +1,31 @@
+// Client-only public barrel for the first-party analytics feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/analytics`. Tsup adds a top-level
+// "use client" directive to the bundled output via clientEntries.
+//
+// Deliberately NOT re-exported from `src/index.ts` — keeping the feature off the
+// main barrel is what keeps its chart (recharts) out of the main client bundle,
+// exactly as the `help` and `tokenusage` features do.
+//
+// The feature is inert until the app mounts `AnalyticsTracker` and registers
+// `analyticsModules` in its bootstrapper.
+
+export { AnalyticsTracker } from "./components/AnalyticsTracker";
+
+export { AnalyticsAdminProvider, useAnalyticsAdmin } from "./contexts/AnalyticsAdminContext";
+export type { AnalyticsAdminContextType, AnalyticsAdminFilterState } from "./contexts/AnalyticsAdminContext";
+
+export { AnalyticsAdminContainer } from "./components/AnalyticsAdminContainer";
+export { AnalyticsAdminFilterBar } from "./components/AnalyticsAdminFilterBar";
+export { AnalyticsAdminTiles } from "./components/AnalyticsAdminTiles";
+export { AnalyticsTimelineChart } from "./components/AnalyticsTimelineChart";
+export { AnalyticsBreakdownTable } from "./components/AnalyticsBreakdownTable";
+export { AnalyticsSessionsTable } from "./components/AnalyticsSessionsTable";
+export { AnalyticsJourneyContainer } from "./components/AnalyticsJourneyContainer";
+export { AnalyticsAdminPageContainer } from "./components/AnalyticsAdminPageContainer";
+export { AnalyticsJourneyPageContainer } from "./components/AnalyticsJourneyPageContainer";
+
+export * from "./data";
+
+export { analyticsModules } from "./analytics.modules";
+
+export { ANALYTICS_ADMIN_I18N_KEYS } from "./i18n-keys";

package/src/features/analytics/lib/__tests__/utm.spec.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { readUtm } from "../utm";
+
+describe("readUtm", () => {
+  it("reads the utm parameters and ignores everything else", () => {
+    expect(readUtm("?utm_source=linkedin&utm_medium=social&utm_campaign=launch&x=1")).toEqual({
+      utmSource: "linkedin",
+      utmMedium: "social",
+      utmCampaign: "launch",
+    });
+  });
+
+  it("returns an empty object for an empty query string", () => {
+    expect(readUtm("")).toEqual({});
+  });
+
+  it("truncates a value to 255 characters", () => {
+    expect(readUtm("?utm_term=" + "a".repeat(300)).utmTerm).toHaveLength(255);
+  });
+});

package/src/features/analytics/lib/__tests__/visitorCookie.spec.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// Records every setCookie call while still writing the real cookie to jsdom,
+// so the options (SameSite, maxAge) and document.cookie can both be asserted.
+const recorded = vi.hoisted(() => ({ calls: [] as unknown[][] }));
+
+vi.mock("cookies-next", async () => {
+  const actual = await vi.importActual<typeof import("cookies-next")>("cookies-next");
+  return {
+    ...actual,
+    setCookie: (...args: unknown[]) => {
+      recorded.calls.push(args);
+      return (actual.setCookie as (...a: unknown[]) => unknown)(...args);
+    },
+  };
+});
+
+import { ANALYTICS_VISITOR_COOKIE, clearVisitorCookie, ensureVisitorCookie, readVisitorCookie } from "../visitorCookie";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+describe("visitorCookie", () => {
+  afterEach(() => {
+    clearVisitorCookie();
+    recorded.calls = [];
+  });
+
+  it("names the cookie analytics_visitor", () => {
+    expect(ANALYTICS_VISITOR_COOKIE).toBe("analytics_visitor");
+  });
+
+  it("creates a UUID and writes it with SameSite=Lax and a ~395-day expiry", () => {
+    const id = ensureVisitorCookie();
+
+    expect(id).toMatch(UUID);
+    expect(document.cookie).toContain(`analytics_visitor=${id}`);
+
+    expect(recorded.calls).toHaveLength(1);
+    const [name, value, options] = recorded.calls[0] as [string, string, Record<string, unknown>];
+    expect(name).toBe("analytics_visitor");
+    expect(value).toBe(id);
+    expect(options.sameSite).toBe("lax");
+    expect(options.path).toBe("/");
+    expect(options.maxAge).toBe(395 * 24 * 3600);
+  });
+
+  it("returns the same id on a second call without rewriting the cookie", () => {
+    const first = ensureVisitorCookie();
+    const second = ensureVisitorCookie();
+
+    expect(second).toBe(first);
+    expect(recorded.calls).toHaveLength(1);
+  });
+
+  it("clears the cookie so readVisitorCookie returns undefined", () => {
+    ensureVisitorCookie();
+    expect(readVisitorCookie()).toBeDefined();
+
+    clearVisitorCookie();
+
+    expect(readVisitorCookie()).toBeUndefined();
+  });
+});

package/src/features/analytics/lib/utm.ts

@@ -0,0 +1,29 @@
+import { AnalyticsEventInput } from "../data/analytics.types";
+
+type UtmFields = Pick<AnalyticsEventInput, "utmSource" | "utmMedium" | "utmCampaign" | "utmTerm" | "utmContent">;
+
+const MAX_LENGTH = 255;
+
+const UTM_PARAMS: [string, keyof UtmFields][] = [
+  ["utm_source", "utmSource"],
+  ["utm_medium", "utmMedium"],
+  ["utm_campaign", "utmCampaign"],
+  ["utm_term", "utmTerm"],
+  ["utm_content", "utmContent"],
+];
+
+/**
+ * Reads the five utm_* parameters from a query string. Absent or empty values
+ * are left out; every value is cut to 255 characters.
+ */
+export function readUtm(search: string): UtmFields {
+  const params = new URLSearchParams(search);
+  const response: UtmFields = {};
+
+  for (const [param, field] of UTM_PARAMS) {
+    const value = params.get(param);
+    if (value) response[field] = value.slice(0, MAX_LENGTH);
+  }
+
+  return response;
+}

package/src/features/analytics/lib/visitorCookie.ts

@@ -0,0 +1,32 @@
+import { deleteCookie, getCookie, setCookie } from "cookies-next";
+import { v4 } from "uuid";
+
+export const ANALYTICS_VISITOR_COOKIE = "analytics_visitor";
+
+/** 395 days: the 13-month retention window. */
+const MAX_AGE_SECONDS = 395 * 24 * 3600;
+
+export function readVisitorCookie(): string | undefined {
+  const value = getCookie(ANALYTICS_VISITOR_COOKIE);
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** Returns the existing visitor id, or creates and stores a new one. */
+export function ensureVisitorCookie(): string {
+  const existing = readVisitorCookie();
+  if (existing) return existing;
+
+  const id = v4();
+  setCookie(ANALYTICS_VISITOR_COOKIE, id, {
+    maxAge: MAX_AGE_SECONDS,
+    sameSite: "lax",
+    path: "/",
+    secure: typeof location !== "undefined" && location.protocol === "https:",
+  });
+
+  return id;
+}
+
+export function clearVisitorCookie(): void {
+  deleteCookie(ANALYTICS_VISITOR_COOKIE, { path: "/" });
+}