@carlonicora/nextjs-jsonapi 3.24.2 → 3.26.0

package/src/features/analytics/data/__tests__/models.spec.ts

@@ -0,0 +1,300 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../permissions/types";
+import { AbstractApiData } from "../../../../core/abstracts/AbstractApiData";
+import { JsonApiHydratedDataInterface } from "../../../../core/interfaces/JsonApiHydratedDataInterface";
+import { analyticsModules } from "../../analytics.modules";
+import { AnalyticsBreakdown } from "../analytics-breakdown";
+import { AnalyticsEvent } from "../analytics-event";
+import { AnalyticsPageView } from "../analytics-page-view";
+import { AnalyticsSession } from "../analytics-session";
+import { AnalyticsSummary } from "../analytics-summary";
+import { AnalyticsTimeline } from "../analytics-timeline";
+
+// createJsonApi reads Modules.X.name (resolved lazily via ModuleRegistry), so
+// the modules must be registered before a model serialises — mirrors the
+// tokenusage-admin-models.spec setup. ModuleRegistry is shared across test
+// files in a worker, hence the register-if-absent guard.
+const moduleFactory: ModuleFactory = (params) =>
+  ({
+    pageUrl: params.pageUrl,
+    name: params.name,
+    model: params.model,
+  }) as ModuleWithPermissions;
+
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+// The real User model rehydrates roles and company, which needs those modules
+// registered too. The session only cares that the included user is read
+// through Modules.User, so a minimal stand-in keeps the fixture small.
+class StubUser extends AbstractApiData {
+  name = "";
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    this.name = data.jsonApi.attributes.name ?? "";
+    return this;
+  }
+}
+
+const userModule = { name: "users", model: StubUser } as ApiRequestDataTypeInterface;
+
+beforeAll(() => {
+  for (const [key, module] of Object.entries(analyticsModules(moduleFactory))) registerIfAbsent(key, module);
+  registerIfAbsent("User", userModule);
+  DataClassRegistry.registerObjectClass(userModule, StubUser);
+});
+
+const hydrate = (attributes: Record<string, unknown>, extra: Record<string, unknown> = {}) =>
+  ({ jsonApi: { id: "x", type: "t", attributes, ...extra }, included: [] }) as any;
+
+describe("analytics models — rehydrate", () => {
+  it("rehydrates every summary attribute", () => {
+    const m = new AnalyticsSummary().rehydrate(
+      hydrate({
+        section: "all",
+        window: "current",
+        visitors: 120,
+        sessions: 150,
+        pageViews: 480,
+        pagesPerSession: 3.2,
+        consentShare: 0.4,
+      }),
+    );
+    expect(m.section).toBe("all");
+    expect(m.window).toBe("current");
+    expect(m.visitors).toBe(120);
+    expect(m.sessions).toBe(150);
+    expect(m.pageViews).toBe(480);
+    expect(m.pagesPerSession).toBe(3.2);
+    expect(m.consentShare).toBe(0.4);
+  });
+
+  it("parses the timeline bucket into a Date, not the wire string", () => {
+    const m = new AnalyticsTimeline().rehydrate(
+      hydrate({ bucket: "2026-09-01", section: "public", visitors: 1, sessions: 2, pageViews: 3 }),
+    );
+    expect(m.bucket).toBeInstanceOf(Date);
+    expect(m.bucket.toISOString().slice(0, 10)).toBe("2026-09-01");
+    expect(m.section).toBe("public");
+    expect(m.visitors).toBe(1);
+    expect(m.sessions).toBe(2);
+    expect(m.pageViews).toBe(3);
+  });
+
+  it("rehydrates every breakdown attribute", () => {
+    const m = new AnalyticsBreakdown().rehydrate(
+      hydrate({ dimension: "source", key: "linkedin", visitors: 4, sessions: 5, pageViews: 6 }),
+    );
+    expect(m.dimension).toBe("source");
+    expect(m.key).toBe("linkedin");
+    expect(m.visitors).toBe(4);
+    expect(m.sessions).toBe(5);
+    expect(m.pageViews).toBe(6);
+  });
+
+  it("parses session datetimes into Dates and leaves absent optionals undefined", () => {
+    const m = new AnalyticsSession().rehydrate(
+      hydrate({
+        visitorId: "v1",
+        consented: true,
+        startedAt: "2026-09-01T10:00:00.000Z",
+        lastSeenAt: "2026-09-01T10:12:00.000Z",
+        pageViews: 4,
+        section: "app",
+        landingRoute: "/rolls/:id",
+        utmSource: "linkedin",
+        deviceType: "desktop",
+      }),
+    );
+    expect(m.visitorId).toBe("v1");
+    expect(m.consented).toBe(true);
+    expect(m.startedAt).toBeInstanceOf(Date);
+    expect(m.startedAt.toISOString()).toBe("2026-09-01T10:00:00.000Z");
+    expect(m.lastSeenAt).toBeInstanceOf(Date);
+    expect(m.lastSeenAt.toISOString()).toBe("2026-09-01T10:12:00.000Z");
+    expect(m.pageViews).toBe(4);
+    expect(m.section).toBe("app");
+    expect(m.landingRoute).toBe("/rolls/:id");
+    expect(m.utmSource).toBe("linkedin");
+    expect(m.referrerHost).toBeUndefined();
+    expect(m.utmMedium).toBeUndefined();
+    expect(m.deviceType).toBe("desktop");
+    expect(m.user).toBeUndefined();
+  });
+
+  it("reads the included user of a session", () => {
+    const m = new AnalyticsSession().rehydrate({
+      jsonApi: {
+        id: "s1",
+        type: "analytics/administration/sessions",
+        attributes: {
+          visitorId: "v1",
+          consented: true,
+          startedAt: "2026-09-01T10:00:00.000Z",
+          lastSeenAt: "2026-09-01T10:00:00.000Z",
+          pageViews: 1,
+          section: "app",
+          landingRoute: "/",
+          deviceType: "mobile",
+        },
+        relationships: { user: { data: { type: "users", id: "u1" } } },
+      },
+      included: [
+        {
+          type: "users",
+          id: "u1",
+          attributes: { name: "Marco Rossi", email: "m@example.com" },
+        },
+      ],
+    } as any);
+
+    expect(m.user).toBeDefined();
+    expect(m.user?.id).toBe("u1");
+    expect(m.user?.name).toBe("Marco Rossi");
+  });
+
+  it("parses the page view createdAt from meta into a Date (the serialiser's placement)", () => {
+    const m = new AnalyticsPageView().rehydrate(
+      hydrate(
+        { path: "/pricing", route: "/pricing", section: "public" },
+        { meta: { createdAt: "2026-09-01T10:05:00.000Z" } },
+      ),
+    );
+    expect(m.createdAt).toBeInstanceOf(Date);
+    expect(m.createdAt.toISOString()).toBe("2026-09-01T10:05:00.000Z");
+  });
+
+  it("parses the page view createdAt into a Date when sent as an attribute", () => {
+    const m = new AnalyticsPageView().rehydrate(
+      hydrate({ createdAt: "2026-09-01T10:05:00.000Z", path: "/rolls/abc", route: "/rolls/:id", section: "app" }),
+    );
+    expect(m.createdAt).toBeInstanceOf(Date);
+    expect(m.createdAt.toISOString()).toBe("2026-09-01T10:05:00.000Z");
+    expect(m.path).toBe("/rolls/abc");
+    expect(m.route).toBe("/rolls/:id");
+    expect(m.section).toBe("app");
+  });
+
+  it("reads path and section back on the event", () => {
+    const m = new AnalyticsEvent().rehydrate(hydrate({ path: "/pricing", section: "public" }));
+    expect(m.path).toBe("/pricing");
+    expect(m.section).toBe("public");
+  });
+});
+
+describe("analytics models — createJsonApi", () => {
+  it("serialises an event with the API resource type and only the attributes given", () => {
+    const doc = new AnalyticsEvent().createJsonApi({
+      id: "e1",
+      path: "/pricing",
+      section: "public",
+      utmSource: "linkedin",
+      screenWidth: 1440,
+    });
+
+    // Must equal analyticsEventMeta.type: the API DTO rejects anything else.
+    expect(doc.data.type).toBe("analytics-events");
+    expect(doc.data.id).toBe("e1");
+    expect(doc.data.attributes).toEqual({
+      path: "/pricing",
+      section: "public",
+      utmSource: "linkedin",
+      screenWidth: 1440,
+    });
+    expect(Object.keys(doc.data.relationships ?? {})).toHaveLength(0);
+  });
+
+  it("serialises a summary back to a JSON:API resource object", () => {
+    const doc = new AnalyticsSummary().createJsonApi({
+      id: "all|current",
+      section: "all",
+      window: "current",
+      visitors: 1,
+      sessions: 2,
+      pageViews: 3,
+      pagesPerSession: 1.5,
+      consentShare: 0.5,
+    });
+    expect(doc.data.type).toBe("analytics/administration/summary");
+    expect(doc.data.id).toBe("all|current");
+    expect(doc.data.attributes).toMatchObject({ section: "all", window: "current", visitors: 1, consentShare: 0.5 });
+  });
+
+  it("emits the timeline bucket as YYYY-MM-DD via formatLocalDate, never a raw Date", () => {
+    const doc = new AnalyticsTimeline().createJsonApi({
+      id: "2026-09-01|public",
+      bucket: new Date(2026, 8, 1),
+      section: "public",
+      visitors: 1,
+      sessions: 1,
+      pageViews: 1,
+    });
+    expect(doc.data.attributes.bucket).toBe("2026-09-01");
+    expect(JSON.parse(JSON.stringify(doc)).data.attributes.bucket).toBe("2026-09-01");
+  });
+
+  it("serialises a breakdown row", () => {
+    const doc = new AnalyticsBreakdown().createJsonApi({
+      id: "source|linkedin",
+      dimension: "source",
+      key: "linkedin",
+      visitors: 1,
+      sessions: 2,
+      pageViews: 3,
+    });
+    expect(doc.data.type).toBe("analytics/administration/breakdown");
+    expect(doc.data.attributes).toEqual({
+      dimension: "source",
+      key: "linkedin",
+      visitors: 1,
+      sessions: 2,
+      pageViews: 3,
+    });
+  });
+
+  it("emits session datetimes as ISO strings, omits absent optionals, and links the user", () => {
+    const doc = new AnalyticsSession().createJsonApi({
+      id: "s1",
+      visitorId: "v1",
+      consented: false,
+      startedAt: new Date("2026-09-01T10:00:00.000Z"),
+      lastSeenAt: new Date("2026-09-01T10:12:00.000Z"),
+      pageViews: 2,
+      section: "app",
+      landingRoute: "/",
+      deviceType: "tablet",
+      userId: "u1",
+    });
+    expect(doc.data.type).toBe("analytics/administration/sessions");
+    expect(doc.data.attributes.startedAt).toBe("2026-09-01T10:00:00.000Z");
+    expect(doc.data.attributes.lastSeenAt).toBe("2026-09-01T10:12:00.000Z");
+    expect("referrerHost" in doc.data.attributes).toBe(false);
+    expect("utmSource" in doc.data.attributes).toBe(false);
+    expect(doc.data.relationships.user).toEqual({ data: { type: "users", id: "u1" } });
+  });
+
+  it("emits the page view createdAt as an ISO string", () => {
+    const doc = new AnalyticsPageView().createJsonApi({
+      id: "p1",
+      createdAt: new Date("2026-09-01T10:05:00.000Z"),
+      path: "/rolls/abc",
+      route: "/rolls/:id",
+      section: "app",
+    });
+    expect(doc.data.type).toBe("pageviews");
+    expect(doc.data.attributes).toEqual({
+      createdAt: "2026-09-01T10:05:00.000Z",
+      path: "/rolls/abc",
+      route: "/rolls/:id",
+      section: "app",
+    });
+  });
+});

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

@@ -0,0 +1,9 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface AnalyticsBreakdownInterface extends ApiDataInterface {
+  get dimension(): string;
+  get key(): string;
+  get visitors(): number;
+  get sessions(): number;
+  get pageViews(): number;
+}

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

@@ -0,0 +1,65 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AnalyticsBreakdownInterface } from "./analytics-breakdown.interface";
+import { AnalyticsBreakdownInput } from "./analytics.types";
+
+/** One row of a breakdown table: a key (source, route, …) and its counts. */
+export class AnalyticsBreakdown extends AbstractApiData implements AnalyticsBreakdownInterface {
+  private _dimension: string = "";
+  private _key: string = "";
+  private _visitors: number = 0;
+  private _sessions: number = 0;
+  private _pageViews: number = 0;
+
+  get dimension(): string {
+    return this._dimension;
+  }
+
+  get key(): string {
+    return this._key;
+  }
+
+  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;
+    this._dimension = attrs.dimension ?? "";
+    this._key = attrs.key ?? "";
+    this._visitors = attrs.visitors ?? 0;
+    this._sessions = attrs.sessions ?? 0;
+    this._pageViews = attrs.pageViews ?? 0;
+
+    return this;
+  }
+
+  createJsonApi(data: AnalyticsBreakdownInput) {
+    const response: any = {
+      data: {
+        type: Modules.AnalyticsBreakdown.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.dimension !== undefined) response.data.attributes.dimension = data.dimension;
+    if (data.key !== undefined) response.data.attributes.key = data.key;
+    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-event.interface.ts

@@ -0,0 +1,7 @@
+import { ApiDataInterface } from "../../../core";
+
+/** Write-only resource: the tracker posts it, rehydrate reads the two attributes back. */
+export interface AnalyticsEventInterface extends ApiDataInterface {
+  get path(): string;
+  get section(): string;
+}

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

@@ -0,0 +1,63 @@
+import { AbstractApiData, JsonApiHydratedDataInterface } from "../../../core";
+import { AnalyticsEventInterface } from "./analytics-event.interface";
+import { AnalyticsEventInput } from "./analytics.types";
+
+/**
+ * JSON:API resource type of a posted event. It must match `analyticsEventMeta.type`
+ * in the API, whose DTO rejects any other value. It is not `Modules.AnalyticsEvent.name`:
+ * that is the endpoint path ("analytics/events"), the same split the auth models
+ * make (e.g. backup-code-verify.ts posts type "backup-codes").
+ */
+const ANALYTICS_EVENT_TYPE = "analytics-events";
+
+/**
+ * One page view as the tracker posts it. The API answers with the stored event,
+ * so rehydrate reads back the two attributes every event carries.
+ */
+export class AnalyticsEvent extends AbstractApiData implements AnalyticsEventInterface {
+  private _path: string = "";
+  private _section: string = "";
+
+  get path(): string {
+    return this._path;
+  }
+
+  get section(): string {
+    return this._section;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._path = attrs.path ?? "";
+    this._section = attrs.section ?? "";
+
+    return this;
+  }
+
+  createJsonApi(data: AnalyticsEventInput) {
+    const response: any = {
+      data: {
+        type: ANALYTICS_EVENT_TYPE,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    response.data.attributes.path = data.path;
+    response.data.attributes.section = data.section;
+    if (data.referrer !== undefined) response.data.attributes.referrer = data.referrer;
+    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.visitorId !== undefined) response.data.attributes.visitorId = data.visitorId;
+    if (data.screenWidth !== undefined) response.data.attributes.screenWidth = data.screenWidth;
+
+    return response;
+  }
+}

package/src/features/analytics/data/analytics-page-view.interface.ts

@@ -0,0 +1,9 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface AnalyticsPageViewInterface extends ApiDataInterface {
+  /** Backend declares this `type: "datetime"`, so it is a Date in memory. */
+  get createdAt(): Date;
+  get path(): string;
+  get route(): string;
+  get section(): string;
+}

package/src/features/analytics/data/analytics-page-view.ts

@@ -0,0 +1,57 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AnalyticsPageViewInterface } from "./analytics-page-view.interface";
+import { AnalyticsPageViewInput } from "./analytics.types";
+
+/** One step of a session journey. */
+export class AnalyticsPageView extends AbstractApiData implements AnalyticsPageViewInterface {
+  private _path: string = "";
+  private _route: string = "";
+  private _section: string = "";
+
+  get path(): string {
+    return this._path;
+  }
+
+  get route(): string {
+    return this._route;
+  }
+
+  get section(): string {
+    return this._section;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    // `createdAt` is inherited: the serialiser sends it in meta and
+    // super.rehydrate() parses it into a Date. Honour it as an attribute too,
+    // should the descriptor ever list it among the fields.
+    if (attrs.createdAt) this._createdAt = new Date(attrs.createdAt);
+    this._path = attrs.path ?? "";
+    this._route = attrs.route ?? "";
+    this._section = attrs.section ?? "";
+
+    return this;
+  }
+
+  createJsonApi(data: AnalyticsPageViewInput) {
+    const response: any = {
+      data: {
+        type: Modules.AnalyticsPageView.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    // type: "datetime" on the backend descriptor: an ISO 8601 instant.
+    if (data.createdAt !== undefined) response.data.attributes.createdAt = data.createdAt.toISOString();
+    if (data.path !== undefined) response.data.attributes.path = data.path;
+    if (data.route !== undefined) response.data.attributes.route = data.route;
+    if (data.section !== undefined) response.data.attributes.section = data.section;
+
+    return response;
+  }
+}

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

@@ -0,0 +1,23 @@
+import { ApiDataInterface } from "../../../core";
+import { UserInterface } from "../../user/data/user.interface";
+
+export interface AnalyticsSessionInterface extends ApiDataInterface {
+  get visitorId(): string;
+  get consented(): boolean;
+  /** Backend declares this `type: "datetime"`, so it is a Date in memory. */
+  get startedAt(): Date;
+  /** Backend declares this `type: "datetime"`, so it is a Date in memory. */
+  get lastSeenAt(): Date;
+  get pageViews(): number;
+  get section(): string;
+  get landingRoute(): string;
+  get referrerHost(): string | undefined;
+  get utmSource(): string | undefined;
+  get utmMedium(): string | undefined;
+  get utmCampaign(): string | undefined;
+  get utmTerm(): string | undefined;
+  get utmContent(): string | undefined;
+  get deviceType(): string;
+  /** Present only when the session belongs to a signed-in user. */
+  get user(): UserInterface | undefined;
+}

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