@carlonicora/nextjs-jsonapi 5.1.3 → 5.2.0

package/src/features/waitlist/data/Waitlist.ts

@@ -7,11 +7,17 @@ export class Waitlist extends AbstractApiData implements WaitlistInterface {
   private _gdprConsentAt?: string;
   private _marketingConsent?: boolean;
   private _marketingConsentAt?: string;
-  private _questionnaire?: string;
+  private _questionnaire?: Record<string, any>;
   private _status: WaitlistStatus = "pending";
   private _confirmedAt?: string;
   private _invitedAt?: string;
   private _registeredAt?: string;
+  private _sourceRef?: string;
+  private _sourceUtmSource?: string;
+  private _sourceUtmMedium?: string;
+  private _sourceUtmCampaign?: string;
+  private _sourceReferrer?: string;
+  private _sourceLandingPath?: string;
 
   get email(): string {
     return this._email ?? "";
@@ -33,7 +39,7 @@ export class Waitlist extends AbstractApiData implements WaitlistInterface {
     return this._marketingConsentAt;
   }
 
-  get questionnaire(): string | undefined {
+  get questionnaire(): Record<string, any> | undefined {
     return this._questionnaire;
   }
 
@@ -53,6 +59,30 @@ export class Waitlist extends AbstractApiData implements WaitlistInterface {
     return this._registeredAt;
   }
 
+  get sourceRef(): string | undefined {
+    return this._sourceRef;
+  }
+
+  get sourceUtmSource(): string | undefined {
+    return this._sourceUtmSource;
+  }
+
+  get sourceUtmMedium(): string | undefined {
+    return this._sourceUtmMedium;
+  }
+
+  get sourceUtmCampaign(): string | undefined {
+    return this._sourceUtmCampaign;
+  }
+
+  get sourceReferrer(): string | undefined {
+    return this._sourceReferrer;
+  }
+
+  get sourceLandingPath(): string | undefined {
+    return this._sourceLandingPath;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
 
@@ -61,11 +91,19 @@ export class Waitlist extends AbstractApiData implements WaitlistInterface {
     this._gdprConsentAt = data.jsonApi.attributes.gdprConsentAt;
     this._marketingConsent = data.jsonApi.attributes.marketingConsent;
     this._marketingConsentAt = data.jsonApi.attributes.marketingConsentAt;
-    this._questionnaire = data.jsonApi.attributes.questionnaire;
+    // The API's descriptor transform parses the stored JSON string into an object
+    const questionnaire = data.jsonApi.attributes.questionnaire;
+    this._questionnaire = questionnaire && typeof questionnaire === "object" ? questionnaire : undefined;
     this._status = data.jsonApi.attributes.status;
     this._confirmedAt = data.jsonApi.attributes.confirmedAt;
     this._invitedAt = data.jsonApi.attributes.invitedAt;
     this._registeredAt = data.jsonApi.attributes.registeredAt;
+    this._sourceRef = data.jsonApi.attributes.sourceRef;
+    this._sourceUtmSource = data.jsonApi.attributes.sourceUtmSource;
+    this._sourceUtmMedium = data.jsonApi.attributes.sourceUtmMedium;
+    this._sourceUtmCampaign = data.jsonApi.attributes.sourceUtmCampaign;
+    this._sourceReferrer = data.jsonApi.attributes.sourceReferrer;
+    this._sourceLandingPath = data.jsonApi.attributes.sourceLandingPath;
 
     return this;
   }
@@ -99,6 +137,16 @@ export class Waitlist extends AbstractApiData implements WaitlistInterface {
       response.data.attributes.questionnaire = JSON.stringify(data.questionnaire);
     }
 
+    if (data.source !== undefined) {
+      const attributes = response.data.attributes;
+      if (data.source.sourceRef !== undefined) attributes.sourceRef = data.source.sourceRef;
+      if (data.source.sourceUtmSource !== undefined) attributes.sourceUtmSource = data.source.sourceUtmSource;
+      if (data.source.sourceUtmMedium !== undefined) attributes.sourceUtmMedium = data.source.sourceUtmMedium;
+      if (data.source.sourceUtmCampaign !== undefined) attributes.sourceUtmCampaign = data.source.sourceUtmCampaign;
+      if (data.source.sourceReferrer !== undefined) attributes.sourceReferrer = data.source.sourceReferrer;
+      if (data.source.sourceLandingPath !== undefined) attributes.sourceLandingPath = data.source.sourceLandingPath;
+    }
+
     return response;
   }
 }

package/src/features/waitlist/data/WaitlistInterface.ts

@@ -1,4 +1,5 @@
 import { ApiDataInterface } from "../../../core";
+import { SignupSource } from "../../signup-source/signup-source";
 
 export type WaitlistStatus = "pending" | "confirmed" | "invited" | "registered";
 
@@ -10,6 +11,7 @@ export type WaitlistInput = {
   marketingConsent?: boolean;
   marketingConsentAt?: string; // ISO timestamp when marketing consent was given
   questionnaire?: Record<string, any>; // Object for form handling, will be JSON.stringify'd by service
+  source?: SignupSource;
 };
 
 export interface WaitlistInterface extends ApiDataInterface {
@@ -18,11 +20,17 @@ export interface WaitlistInterface extends ApiDataInterface {
   get gdprConsentAt(): string;
   get marketingConsent(): boolean | undefined;
   get marketingConsentAt(): string | undefined;
-  get questionnaire(): string | undefined; // JSON string from backend
+  get questionnaire(): Record<string, any> | undefined; // the API sends the answers already parsed
   get status(): WaitlistStatus;
   get confirmedAt(): string | undefined;
   get invitedAt(): string | undefined;
   get registeredAt(): string | undefined;
+  get sourceRef(): string | undefined;
+  get sourceUtmSource(): string | undefined;
+  get sourceUtmMedium(): string | undefined;
+  get sourceUtmCampaign(): string | undefined;
+  get sourceReferrer(): string | undefined;
+  get sourceLandingPath(): string | undefined;
   // createdAt and updatedAt inherited from ApiDataInterface
 }
 

package/src/features/waitlist/data/WaitlistService.ts

@@ -101,11 +101,12 @@ export class WaitlistService extends AbstractService {
   }
 
   /**
-   * Get statistics (admin)
+   * Get statistics (admin): GET /waitlists/stats, rehydrated as waitlist-stats
    */
   static async getStats(): Promise<WaitlistStatsInterface> {
     const endpoint = new EndpointCreator({
-      endpoint: Modules.WaitlistStats,
+      endpoint: Modules.Waitlist,
+      id: "stats",
     });
 
     return this.callApi<WaitlistStatsInterface>({

package/src/features/waitlist/data/__tests__/Waitlist.spec.ts

@@ -0,0 +1,82 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { Waitlist } from "../Waitlist";
+import { WaitlistInput } from "../WaitlistInterface";
+
+// Waitlist.createJsonApi() resolves Modules.Waitlist through the real ModuleRegistry.
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("Waitlist", { name: "waitlists", model: Waitlist } as any);
+});
+
+const baseInput: WaitlistInput = {
+  id: "11111111-1111-4111-8111-111111111111",
+  email: "gm@example.com",
+  gdprConsent: true,
+  gdprConsentAt: "2026-10-21T10:00:00.000Z",
+};
+
+const SOURCE_KEYS = [
+  "sourceRef",
+  "sourceUtmSource",
+  "sourceUtmMedium",
+  "sourceUtmCampaign",
+  "sourceReferrer",
+  "sourceLandingPath",
+];
+
+describe("Waitlist.createJsonApi()", () => {
+  it("createJsonApi writes the six source attributes when present", () => {
+    const payload = new Waitlist().createJsonApi({
+      ...baseInput,
+      source: {
+        sourceRef: "discord-embed",
+        sourceUtmSource: "reddit",
+        sourceUtmMedium: "social",
+        sourceUtmCampaign: "r_rpg",
+        sourceReferrer: "www.enworld.org",
+        sourceLandingPath: "/it/pricing",
+      },
+    });
+
+    expect(payload.data.attributes).toMatchObject({
+      sourceRef: "discord-embed",
+      sourceUtmSource: "reddit",
+      sourceUtmMedium: "social",
+      sourceUtmCampaign: "r_rpg",
+      sourceReferrer: "www.enworld.org",
+      sourceLandingPath: "/it/pricing",
+    });
+  });
+
+  it("omits them when source is undefined", () => {
+    const payload = new Waitlist().createJsonApi(baseInput);
+
+    for (const key of SOURCE_KEYS) {
+      expect(payload.data.attributes).not.toHaveProperty(key);
+    }
+  });
+});
+
+describe("Waitlist.rehydrate()", () => {
+  const hydrate = (attributes: Record<string, any>) =>
+    new Waitlist().rehydrate({ jsonApi: { type: "waitlists", id: "w-1", attributes }, included: [] });
+
+  it("keeps the questionnaire object the API sends", () => {
+    const waitlist = hydrate({ questionnaire: { system: "dnd2024", headache: "Too many plot threads" } });
+
+    expect(waitlist.questionnaire).toEqual({ system: "dnd2024", headache: "Too many plot threads" });
+  });
+
+  it("leaves the questionnaire undefined when the API sends none", () => {
+    expect(hydrate({ questionnaire: null }).questionnaire).toBeUndefined();
+  });
+});

package/src/features/waitlist/data/__tests__/WaitlistService.spec.ts

@@ -0,0 +1,48 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { AbstractService } from "../../../../core/abstracts/AbstractService";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../permissions/types";
+import { WaitlistStatsModule } from "../../waitlist-stats.module";
+import { WaitlistModule } from "../../waitlist.module";
+import { WaitlistService } from "../WaitlistService";
+
+const moduleFactory: ModuleFactory = (params) =>
+  ({ pageUrl: params.pageUrl, name: params.name, model: params.model }) as ModuleWithPermissions;
+
+// ModuleRegistry is shared across test files in a worker, hence the
+// register-if-absent guard (same idiom as AnalyticsAdminService.spec.ts).
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("Waitlist", WaitlistModule(moduleFactory));
+  registerIfAbsent("WaitlistStats", WaitlistStatsModule(moduleFactory));
+});
+
+type CallApiParams = { type: ApiRequestDataTypeInterface; method: string; endpoint: string };
+
+// `callApi` is a protected static on AbstractService; spying on the base class
+// intercepts every call without touching the HTTP layer.
+const callApi = () => vi.spyOn(AbstractService as any, "callApi").mockResolvedValue({});
+const firstCall = (spy: ReturnType<typeof callApi>): CallApiParams => spy.mock.calls[0][0] as CallApiParams;
+
+describe("WaitlistService", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("getStats calls waitlists/stats with type WaitlistStats", async () => {
+    const spy = callApi();
+
+    await WaitlistService.getStats();
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("WaitlistStats" as any));
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toMatch(/waitlists\/stats$/);
+  });
+});

package/src/features/waitlist/data/waitlist.fields.ts

@@ -3,6 +3,7 @@ export enum WaitlistFields {
   email = "email",
   status = "status",
   createdAt = "createdAt",
+  source = "source",
   questionnaire = "questionnaire",
   actions = "actions",
 }

package/src/features/waitlist/hooks/__tests__/formatSignupSource.spec.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { formatSignupSource } from "../formatSignupSource";
+
+describe("formatSignupSource", () => {
+  it("prefers ref over utm source", () => {
+    expect(formatSignupSource({ sourceRef: "discord-embed", sourceUtmSource: "reddit" })).toBe("discord-embed");
+  });
+
+  it("joins utm source and campaign", () => {
+    expect(formatSignupSource({ sourceUtmSource: "reddit", sourceUtmCampaign: "r_rpg" })).toBe("reddit / r_rpg");
+  });
+
+  it("shows utm source alone when there is no campaign", () => {
+    expect(formatSignupSource({ sourceUtmSource: "reddit" })).toBe("reddit");
+  });
+
+  it("falls back to the referring host", () => {
+    expect(formatSignupSource({ sourceReferrer: "enworld.org" })).toBe("enworld.org");
+  });
+
+  it("returns undefined for a direct visit", () => {
+    expect(formatSignupSource({})).toBeUndefined();
+  });
+});

package/src/features/waitlist/hooks/formatSignupSource.ts

@@ -0,0 +1,14 @@
+import { SignupSource } from "../../signup-source/signup-source";
+
+/**
+ * The one-line source shown in the waitlist admin table, first rule that applies:
+ * ref; utm source (with " / utm campaign" when present); referring host.
+ * Undefined means a direct visit.
+ */
+export function formatSignupSource(entry: SignupSource): string | undefined {
+  if (entry.sourceRef) return entry.sourceRef;
+  if (entry.sourceUtmSource)
+    return entry.sourceUtmCampaign ? `${entry.sourceUtmSource} / ${entry.sourceUtmCampaign}` : entry.sourceUtmSource;
+  if (entry.sourceReferrer) return entry.sourceReferrer;
+  return undefined;
+}

package/src/features/waitlist/hooks/useWaitlistTableStructure.tsx

@@ -9,18 +9,8 @@ import { useI18nLocale } from "../../../i18n";
 import { Badge, Button } from "../../../shadcnui";
 import { WaitlistFields } from "../data/waitlist.fields";
 import { WaitlistInterface, WaitlistStatus } from "../data/WaitlistInterface";
-
-/**
- * Parse questionnaire JSON string safely
- */
-function parseQuestionnaire(questionnaire: string | undefined): Record<string, any> | null {
-  if (!questionnaire) return null;
-  try {
-    return JSON.parse(questionnaire);
-  } catch {
-    return null;
-  }
-}
+import { SIGNUP_SOURCE_FIELDS } from "../../signup-source/signup-source";
+import { formatSignupSource } from "./formatSignupSource";
 
 /**
  * Columns for the administrative waitlist. The invite action needs the list's
@@ -86,13 +76,35 @@ export const useWaitlistTableStructure: UseTableStructureHook<WaitlistInterface,
       enableSorting: false,
       enableHiding: false,
     }),
+    [WaitlistFields.source]: () => ({
+      id: "source",
+      header: t("waitlist.admin.columns.source"),
+      cell: ({ row }: { row: TableContent<WaitlistInterface> }) => {
+        const entry: WaitlistInterface = row.original.jsonApiData;
+        const details = SIGNUP_SOURCE_FIELDS.filter((field) => !!entry[field])
+          .map((field) => `${t(`waitlist.admin.source.fields.${field}`)}: ${entry[field]}`)
+          .join("\n");
+        const source = formatSignupSource(entry);
+
+        if (!source) {
+          return (
+            <span className="text-muted-foreground" title={details || undefined}>
+              {t("waitlist.admin.source.direct")}
+            </span>
+          );
+        }
+
+        return <span title={details}>{source}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
     [WaitlistFields.questionnaire]: () => ({
       id: "questionnaire",
       accessorKey: "questionnaire",
       header: t("waitlist.admin.columns.questionnaire"),
       cell: ({ row }: { row: TableContent<WaitlistInterface> }) => {
-        // IMPORTANT: Parse JSON string from backend
-        const questionnaire = parseQuestionnaire(row.original.jsonApiData.questionnaire);
+        const questionnaire = row.original.jsonApiData.questionnaire;
         if (!questionnaire || Object.keys(questionnaire).length === 0) {
           return <span className="text-muted-foreground">-</span>;
         }

package/src/hooks/__tests__/usePageTracker.spec.tsx

@@ -245,16 +245,22 @@ describe("usePageTracker", () => {
     const view = mount(store);
     await waitFor(() => expect(pages(store)[0]?.title).toBe("Venezia Obscura"));
     const firstTimestamp = pages(store)[0].timestamp;
-
-    pathnameRef.current = "/campaigns/camp-1//npcs";
-    document.title = "[Campaign] NPCs Venezia Obscura | App";
-    view.rerender(
-      <Provider store={store}>
-        <Harness />
-      </Provider>,
-    );
-
-    await waitFor(() => expect(pages(store)[0]?.timestamp).not.toBe(firstTimestamp));
+    // Both visits can land in the same millisecond; move the clock so the refresh is observable.
+    const now = vi.spyOn(Date, "now").mockReturnValue(firstTimestamp + 1000);
+
+    try {
+      pathnameRef.current = "/campaigns/camp-1//npcs";
+      document.title = "[Campaign] NPCs Venezia Obscura | App";
+      view.rerender(
+        <Provider store={store}>
+          <Harness />
+        </Provider>,
+      );
+
+      await waitFor(() => expect(pages(store)[0]?.timestamp).toBe(firstTimestamp + 1000));
+    } finally {
+      now.mockRestore();
+    }
     expect(pages(store)[0].title).toBe("Venezia Obscura");
     expect(pages(store)[0].url).toBe("/campaigns/camp-1");
     expect(pages(store)).toHaveLength(1);

package/src/index.ts

@@ -47,6 +47,9 @@ export type {
 export { configureReferral, getReferralConfig, isReferralEnabled } from "./features/referral/config";
 export type { ReferralConfig } from "./features/referral/config";
 
+// Sign-up source capture (utilities; SignupSourceCapture component via /components)
+export * from "./features/signup-source";
+
 // Toast utilities
 export { showToast, showError, dismissToast, showCustomToast, type ToastOptions } from "./utils/toast";
 

package/dist/auth.interface-CeFCz9NU.d.mts

@@ -1,34 +0,0 @@
-import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.mjs';
-import { U as UserInterface } from './user.interface-CIWGlbqM.mjs';
-
-type AuthInput = {
-    id?: string;
-    email?: string | undefined | null;
-    password?: string | undefined;
-    name?: string;
-    companyName?: string;
-    partitaIva?: string;
-    codiceFiscale?: string;
-    termsAcceptedAt?: string;
-    marketingConsent?: boolean;
-    marketingConsentAt?: string | null;
-    inviteCode?: string;
-    referralCode?: string;
-};
-type AuthQuery = {
-    userId?: string;
-    tokenCode?: string;
-    refreshToken?: string;
-    login?: boolean;
-    forgot?: boolean;
-    code?: string;
-    activationCode?: string;
-    checkUsername?: string;
-};
-interface AuthInterface extends ApiDataInterface {
-    get token(): string;
-    get refreshToken(): string;
-    get user(): UserInterface;
-}
-
-export type { AuthInput as A, AuthQuery as a, AuthInterface as b };

package/dist/auth.interface-D1R7VVky.d.ts

@@ -1,34 +0,0 @@
-import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.js';
-import { U as UserInterface } from './user.interface-C0ZdsBZj.js';
-
-type AuthInput = {
-    id?: string;
-    email?: string | undefined | null;
-    password?: string | undefined;
-    name?: string;
-    companyName?: string;
-    partitaIva?: string;
-    codiceFiscale?: string;
-    termsAcceptedAt?: string;
-    marketingConsent?: boolean;
-    marketingConsentAt?: string | null;
-    inviteCode?: string;
-    referralCode?: string;
-};
-type AuthQuery = {
-    userId?: string;
-    tokenCode?: string;
-    refreshToken?: string;
-    login?: boolean;
-    forgot?: boolean;
-    code?: string;
-    activationCode?: string;
-    checkUsername?: string;
-};
-interface AuthInterface extends ApiDataInterface {
-    get token(): string;
-    get refreshToken(): string;
-    get user(): UserInterface;
-}
-
-export type { AuthInput as A, AuthQuery as a, AuthInterface as b };